Menús emergentes

org.eclipse.ui.popupMenus

Este punto de extensión sirve para añadir acciones nuevas a los menús de contexto que son propiedad de otros conectores. Las contribuciones de acciones pueden 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.

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

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 .



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

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

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.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

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



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

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.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Este elemento se utiliza para definir un menú nuevo.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

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



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

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.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

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.



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

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



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

Este elemento se utiliza para definir la visibilidad de la extensió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 expresiones de subelemento.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

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.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

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.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Este elemento se utiliza para evaluar el estado de un conector. El estado del conector puede ser uno de los siguientes: instalado (installed) (equivalente al concepto OSGi de "resuelto") o activado (activated) (equivalente al concepto OSGi de "activo").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

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



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"

/>

</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"

/>

</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=

"terminado"

value=

"true"

/>

<filter name=

"prioridad"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"Herramienta de acciones completadas 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.

El valor del atributo de acción class debe ser el nombre totalmente calificado de una clase Java que implemente org.eclipse.ui.IObjectActionDelegate en el caso de contribuciones de objeto, org.eclipse.ui.IViewActionDelegate para contribuciones a menús de contexto que pertenezcan a vistas o org.eclipse.ui.IEditorActionDelegate para 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>

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.