Menús emergentes

Identificador: org.eclipse.ui.popupMenus

Descripción: este punto de extensión sirve para añadir acciones nuevas a los menús de contexto que son propiedad de otros conectores. La contribución de acciones puede realizarse con respecto a un tipo de objeto específico (objectContribution) o con respecto a un menú de contexto específico de un componente de vista o editor (viewerContribution). Si se utiliza objectContribution, la contribución aparecerá en todos los menús de contexto de componente de vista o editor en los que estén seleccionados objetos del tipo especificado. Por el contrario, si se utiliza viewerContribution, la contribución únicamente aparecerá en el menú de contexto del componente de vista o editor especificado, sin tener en cuenta la selección.

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

La selección se puede restringir adicionalmente si se utiliza un filtro de nombres. En tal caso, todos los objetos de la selección deben coincidir con el filtro para que se aplique la contribución.

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

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

La habilitación y/o visibilidad de una acción puede definirse mediante los elementos enablement y visibility, respectivamente. Estos dos elementos contienen una expresión booleana que se evalúa para determinar la habilitación y/o visibilidad.

La sintaxis es la misma para ambos elementos, enablement y visibility. Ambos contienen sólo un subelemento de expresión booleana. En el caso más simple, se tratará de un elemento objectClass, objectState, pluginState o systemProperty. En el caso más complejo, pueden combinarse los elementos and, or y not para formar una expresión booleana. Tanto lo elementos and como los elementos or deben contener 2 subelementos. El elemento not debe contener sólo 1 subelemento.

Códigos XML de configuración:

   <!ELEMENT extension (objectContribution , viewerContribution)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

   <!ELEMENT objectContribution (filter* , visibility? , menu* , action*)>

   Este elemento se utiliza para definir un grupo de acciones y/o menús para los menús de contexto de visor en los que se seleccionen los objetos del tipo especificado .

   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
     objectClass CDATA #REQUIRED
     nameFilter  CDATA #IMPLIED
     adaptable   (true | false) "false"
   >

   <!ELEMENT viewerContribution (visibility? , menu* , action*)>

   Este elemento se utiliza para definir un grupo de acciones y/o menús para un menú de contexto de componente de vista o editor específico.

   <!ATTLIST viewerContribution
      id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

   <!ELEMENT action (selection* , enablement?)>

   Este elemento define una acción a la que el usuario puede llamar en la UI.

   <!ATTLIST action
      id               CDATA #REQUIRED
      label            CDATA #REQUIRED
     menubarPath      CDATA #IMPLIED
      icon             CDATA #IMPLIED
     helpContextId    CDATA #IMPLIED
     style            (push|radio|toggle)
     state            (true | false)
      class            CDATA #REQUIRED
     enablesFor       CDATA #IMPLIED
     overrideActionId CDATA #IMPLIED
      tooltip          CDATA #IMPLIED
   >

   <!ELEMENT filter EMPTY>

   Este elemento se utiliza para evaluar el estado de atributo de cada objeto de la selección actual. Si cada objeto de la selección tiene el estado de atributo especificado, la expresión se evalúa como true. Cada objeto de la selección debe implementar o adaptarse a la interfaz org.eclipse.ui.IActionFilter.

   <!ATTLIST filter
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT menu (separator+ , groupMarker*)>

   Este elemento se utiliza para definir un menú nuevo.

   <!ATTLIST menu
      id    CDATA #REQUIRED
      label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

   Este elemento se utiliza para crear un separador de menú en el menú nuevo.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   Este elemento se utiliza para crear un grupo con nombre en el menú nuevo. No tiene representación visual en el menú nuevo, a diferencia del elemento separator.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   Este elemento se utiliza para ayudar a determinar la habilitación de la acción en función de la selección actual. Se pasa por alto si se ha especificado el elemento enablement.

   <!ATTLIST selection
      class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

   <!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento se utiliza para definir la habilitación de la acción.

   <!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento se utiliza para definir la visibilidad de la acción.

   <!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento representa una operación booleana AND en el resultado de evaluar sus dos expresiones de subelemento.

   <!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento representa una operación booleana OR en el resultado de evaluar sus dos expresiones de subelemento.

   <!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento representa una operación booleana NOT en el resultado de evaluar sus dos expresiones de subelemento.

   <!ELEMENT objectClass EMPTY>

   Este elemento se utiliza para evaluar la clase o interfaz de cada objeto de la selección actual. Si cada objeto de la selección implementa la clase o interfaz especificada, la expresión se evalúa como true.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Este elemento se utiliza para evaluar el estado de atributo de cada objeto de la selección actual. Si cada objeto de la selección tiene el estado de atributo especificado, la expresión se evalúa como true. Para evaluar este tipo de expresión, cada objeto de la selección debe implementar o adaptarse a la interfaz org.eclipse.ui.IActionFilter.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Este elemento se utiliza para evaluar el estado de un conector. El estado del conector puede ser una de los siguientes: instalado (installed) o activado (activated).

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   Este elemento se utiliza para evaluar el estado de alguna propiedad del sistema. El valor de propiedad se recupera de java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Ejemplos: a continuación figura 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;Herramientas Java XYZ">
            <separator name="group1"/> 
         </menu> 
         <action
            id="com.xyz.runXYZ" 
               label="&amp;Ejecutar herramienta XYZ"
            style="push"
            menubarPath="com.xyz.xyzMenu/group1" 
            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;Mostrar XYZ"
            style="toggle"
            state="true"
            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 de contribución de objeto especificada solo se habilitará para una selección individual (atributo enablesFor). Además, cada objeto de la selección debe implementar la interfaz especificada (IFile) y tiene que ser un archivo Java. Esta acción se añadirá a un submenú creado anteriormente. Esta contribución entrará en vigor en cualquier vista que tenga la selección necesaria.

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

A continuación figura un ejemplo del mecanismo de filtro. En este caso, la acción únicamente aparecerá para los IMarkers que se hayan completado y tengan alta prioridad.

   <extension point="org.eclipse.ui.popupMenus"> 
      <objectContribution 
         id="com.xyz.C3" 
         objectClass="org.eclipse.core.resources.IMarker"> 
         <filter name="done" value="true"/> 
         <filter name="priority" value="2"/> 
         <action
            id="com.xyz.runXYZ" 
            label="Herramienta de acción completada de alta prioridad"
            icon="icons/runXYZ.gif" 
            class="com.xyz.actions.MarkerActionDelegate"> 
         </action> 
      </objectContribution> 
   </extension> 

A continuación figura otro ejemplo de utilización del elemento de visibilidad (visibility):

   <extension point="org.eclipse.ui.popupMenus"> 
      <viewerContribution 
         id="com.xyz.C4" 
         targetID="org.eclipse.ui.views.TaskList">
         <visibility>
            <and>
               <pluginState id="com.xyz" value="activated"/>
               <systemProperty name="ADVANCED_MODE" value="true"/>
            </and>
         </visibility>
         <action
            id="com.xyz.showXYZ" 
            label="&amp;Mostrar XYZ"
            style="push"
            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 aparecerá como elemento de menú en el menú de contexto de la vista Tareas, pero sólo si el conector "com.xyz" está activo y la propiedad del sistema especificada está establecida en true.

Información sobre las API: el valor del atributo class de la acción debe ser un nombre totalmente calificado de una clase Java que implemente org.eclipse.ui.IObjectActionDelegate, en el caso las contribuciones de objeto, org.eclipse.ui.IViewActionDelegate, para las contribuciones a menús de contexto que pertenezcan a vistas, o org.eclipse.ui.IEditorActionDelegate para las contribuciones a menús de contexto que pertenezcan a editores. En todos los casos, la clase de implementación se carga lo más tarde posible para evitar que se cargue todo el conector antes de que sea realmente necesario.

Nota: para la compatibilidad con versiones anteriores, puede implementarse org.eclipse.ui.IActionDelegate para las contribuciones de objeto.

La extensión de menú de contexto dentro de un componente sólo es posible cuando el componente destino publica un menú para la extensión. Esto es altamente aconsejable, ya que mejora la capacidad de ampliación del producto. Para lograrlo, cada componente debe publicar los menús de contexto definidos llamando a IWorkbenchPartSite.registerContextMenu. Una vez realizada esta operación, el entorno de trabajo insertará automáticamente las extensiones de acción que existan.

Debe proporcionarse un ID de menú para cada menú registrado. A efectos de coherencia en los componentes, todos los implementadores de componentes deben adoptar la estrategia siguiente:

Los menús de contexto que estén registrados en el entorno de trabajo también deben contener un punto de inserción estándar con el ID IWorkbenchActionConstants.MB_ADDITIONS. Otros conectores utilizarán este valor como punto de referencia para la inserción. El punto de inserción puede definirse añadiendo un GroupMarker al menú en una ubicación adecuada para la inserción.

Un objeto del entorno de trabajo que sea la selección de un menú de contexto puede definir un org.eclipse.ui.IActionFilter. Esta es una estrategia de filtrado que puede realizar el filtrado de tipos específicos. El entorno de trabajo recuperará el filtro destinado a la selección comprobando si implementa IActionFilter. Si esta operación falla, el entorno de trabajo solicitará un filtro por medio del mecanismo IAdaptable.

Las etiquetas de acción y de menú pueden contener caracteres especiales que codifican nemotécnicos, que se especifican utilizando el carácter & delante de un carácter seleccionado del texto traducido. Como el símbolo ampersand no está permitido en las series XML, hay que utilizar la entidad de tipo carácter &amp;.

Si se suministran dos o más acciones a un menú mediante una extensión individual, las acciones aparecerán en el orden inverso a como figuran en el archivo plugin.xml. Obviamente, este comportamiento no es intuitivo. No obstante, se descubrió después de haber congelado la API de la plataforma Eclipse. Si se cambiara ahora el comportamiento, quedarían dañados todos los conectores que se basan en el comportamiento existente.

Los elementos selection y enablement son mutuamente excluyentes. El elemento enablement puede sustituir al elemento selection mediante los subelementos objectClass y objectState. Por ejemplo, el siguiente código:

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
puede expresarse de esta forma:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Implementación suministrada: las vistas del entorno de trabajo tienen menús de contexto incorporados que ya vienen cargados con varias acciones. Los conectores pueden suministrar contribuciones a estos menús. Si un visor tiene espacios reservados para estas contribuciones y se hacen públicos, los nombres de los espacios pueden utilizarse como vías de acceso. En caso contrario, las acciones y los submenús se añadirán al final del menú emergente.

Copyright (c) 2000, 2003 IBM Corporation y otros. Reservados todos los derechos. Este programa y sus materiales adjuntos están disponibles bajo los términos de la licencia pública común (Common Public License) v1.0 que acompaña a esta distribución, y está disponible en http://www.eclipse.org/legal/cpl-v10.html