Menús emergentes

Identificador: org.eclipse.ui.popupMenus

Descripción: Este punto de extensión se utiliza para añadir nuevas acciones a los menús emergentes propios de otros plug-ins.  La contribución de acciones puede ser hecha hacia un tipo de objeto específico (objectContribution) o para un menú emergente específico. Cuando esté registrada para un tipo de objeto, la contribución aparecerá en todos los visores donde estén seleccionados objetos del tipo especificado. Por contra, si se registra contra un menú emergente únicamente aparecerá en el menú especificado, sin tener en cuenta la selección.

Cuando la selección es heterogénea, la contribución se aplicará si es registrada contra un tipo común de la selección, en caso posible. Si no es posible una coincidencia directa, se intentará respecto de las superclases y los superinterfaces.

La selección será más limitada si se utiliza un filtro de nombre. Al utilizarlo, todos los objetos de la selección deberán coincidir con el filtro para poder aplicar la contribución.

En una contribución de objeto, las acciones individuales pueden utilizar el atributo enablesFor para especificar si solamente debe aplicarse para un tipo sencillo, múltiple o cualquier otro tipo de selección.

Si estos mecanismos de filtrado son inadecuados, una contribución de acción puede utilizar el mecanismo filter.  En este caso, los atributos del objeto de destino se describen en una serie de pares de valores clave.  Los atributos aplicables a la selección son específicos para el tipo y sobrepasan el dominio del entorno de trabajo mismo, por lo que éste delegará el filtrado a este nivel a la propia selección.

Códigos de configuración:

   <!ELEMENT objectContribution (filter | menu | action)*>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter  CDATA #IMPLIED
   >

   <!ELEMENT viewerContribution (menu | action)*>
   <!ATTLIST viewerContribution
      id        CDATA #REQUIRED
      targetID  CDATA #REQUIRED
   >    <!ELEMENT filter EMPTY>
   <!ATTLIST filter
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >    <!ELEMENT menu (separator)+>
   <!ATTLIST menu
      id         CDATA #REQUIRED
      label      CDATA #REQUIRED
      path       CDATA #IMPLIED
   >    <!ELEMENT separator EMPTY>
   <!ATTLIST separator
      name       CDATA #REQUIRED
   >
  • name - nombre del separador que más tarde puede ser mencionado como la última señal de la vía de acceso de la acción. Por tanto, los separadores sirven como grupos nominados en los cuales pueden añadirse acciones.
  •    <!ELEMENT action EMPTY>
       <!ATTLIST action
          id                NMTOKEN #REQUIRED
          label             CDATA #REQUIRED
          menubarPath       CDATA #IMPLIED
          icon              CDATA #IMPLIED
          helpContextId     CDATA #IMPLIED
          state             (true | false) #IMPLIED
          class             CDATA #REQUIRED
          enablesFor        CDATA #IMPLIED
       > Los criterios de habilitación para la extensión de una acción son definidos inicialmente por enablesFor y selection.  Sin embargo, una vez que la acción delegada ha sido instanciada, podrá controlar el estado de habilitación de la acción directamente dentro de su método selectionChanged.

    Las etiquetas de acción y de menú pueden contener caracteres especiales que codifican mnemotécnicos y aceleradores utilizando las reglas siguientes:

    1. Los mnemotécnicos se especifican utilizando el carácter "y comercial" ('&') delante de un carácter seleccionado del texto traducido. Como no se permite usar el signo "y comercial" en las series XML, utilice los caracteres &amp;.
    2. Los aceleradores opcionales se especifican al final de la cadena de caracteres del nombre, utilizando '@' seguido de la serie de modificadores y el carácter acelerador final (por ejemplo, &amp;Save@Ctrl+S). Los aceleradores con más de un modificador se obtienen encadenando los modificadores, utilizando el signo '+' como delimitador (como en @Ctrl+Shift+S).
    Ejemplos:

    A continuación podemos observar un ejemplo de punto de extensión de menú emergente:

       <extension point="org.eclipse.ui.popupMenus">
          <objectContribution
             id="com.xyz.C1"
             objectClass="org.eclipse.core.resources.IFile"
             nameFilter="*.java">
             <menu id="com.xyz.xyzMenu"
                   path="additions"
                   label="&amp;XYZ Java Tools">
                <separator name="group1"/>
             </menu>
             <action id="com.xyz.runXYZ"
                  label="&amp;Ejecutar herramienta XYZ"
                  menubarPath="com.xyz.xyzMenu/grupo1"
                  icon="icons/runXYZ.gif"
                  helpContextId="com.xyz.run_action_context"
                  class="com.xyz.actions.XYZToolActionDelegate"
                  enablesFor="1">
              </action>
            </objectContribution>
            <viewerContribution
               id="com.xyz.C2"
               targetID="org.eclipse.ui.views.TaskList">
               <action id="com.xyz.showXYZ"
                       label="&amp;Show XYZ"
                       menubarPath="additions"
                       icon="icons/showXYZ.gif"
                       helpContextId="com.xyz.show_action_context"
                       class="com.xyz.actions.XYZShowActionDelegate">
               </action>
            </viewerContribution>
         </extension>

    En el ejemplo anterior, la acción especificada habilitará únicamente una selección (atributo enablesFor). Por añadidura, los objetos seleccionados deben implementar el interfaz especificado (IFile) y deben ser archivos de Java. Esta acción se añadirá a un submenú creado previamente. Esta contribución se hará efectiva en cualquier vista que tenga la selección necesaria.

    Por el contrario, la contribución de visor anterior únicamente aparecerá en la vista Tasks, y no se verá afectada por la selección en la vista.

    A continuación podemos observar un ejemplo del mecanismo de filtro.  En este caso la acción únicamente aparecerá en los IMarkers completados y que tengan prioridad alta.

       <extension point="org.eclipse.ui.popupMenus">
          <objectContribution
             id="com.xyz.C1"
             objectClass="org.eclipse.core.resources.IMarker">
             <filter name="done" value="true"/>
             <filter name="priority" value="2"/>
             <action id="com.xyz.runXYZ"
                  label="High Priority Completed Action Tool"
                  icon="icons/runXYZ.gif"
                  class="com.xyz.actions.MarkerActionDelegate">
              </action>
            </objectContribution>
         </extension>

    Información del API:  El valor del atributo de acción class debe ser un nombre totalmente calificado de una clase de Java que implemente org.eclipse.ui.IObjectActionDelegate en caso de contribuir a objetos, org.eclipse.ui.IViewActionDelegate para contribuciones a visores que pertenecen a vistas, o org.eclipse.ui.IEditorActionDelegate para contribuciones a visores que pertenecen a editores.  En todos los casos, la clase implementada se carga lo más tarde posible para evitar la carga del plug-in en su totalidad antes de que sea verdaderamente necesario.

    Nota: Para compatibilidad con anteriores versiones, debe implementarse org.eclipse.ui.IActionDelegate para las contribuciones a objetos.

    La extensión de un menú emergente dentro de un componente es únicamente posible cuando la parte en cuestión publica un menú para su extensión.  Ello es totalmente fomentado, pues mejora la expansibilidad del producto.  Para que esto se cumpla, cada componente deberá publicar cualquiera de los menús que se definen al efectuar una llamada a IWorkbenchPartSite#registerContextMenu.  Una vez hecho esto, el entorno de trabajo insertará automáticamente toda extensión de acción existente.

    Debe proporcionarse un identificador de menú por cada menú registrado.  Para lograr una mayor cohesión entre los componentes, todos los implementadores de componentes deberán adoptar la estrategia siguiente:

    Todo menú emergente que se registre con el entorno de trabajo también deberá contener un punto de inserción estándar con el identificador IWorkbenchActionConstants.MB_ADDITIONS.  Otros plug-ins utilizarán este valor como punto de referencia para inserción.  El punto de inserción puede definirse añadiendo un GroupMarker al menú en una ubicación apropiada para su inserción.

    Un objeto del entorno de trabajo que sea la selección en un menú de contexto puede definir un org.eclipse.ui.IActionFilter.  Ésta es una estrategia de filtrado que puede desempeñar un filtrado específico del tipo.  El entorno de trabajo recuperará el filtro para la selección al comprobar si éste implementa IActionFilter.  Si esto falla, el entorno de trabajo solicitará un filtro mediante el mecanismo IAdaptable.

    Implementación suministrada: La vista del entorno de trabajo incluye menús emergentes que ya vienen cargados con varias acciones. Los plug-ins pueden contribuir a tales menús. Si un visor tiene espacios reservados para éstas contribuciones y son hechos públicos, los nombres de los espacios pueden utilizarse como vías de acceso. De lo contrario, las acciones y los submenús serán añadidos al final del menú emergente.

    Copyright IBM Corp. 2000, 2001.  Reservados todos los derechos.