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 plug-ins. 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 plug-in. El estado del plug-in 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.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Elemento raíz genérico. El elemento puede utilizarse en un punto de extensión para definir su expresión enablement. Los hijos de una expresión de habilitación se combinan mediante el operador and.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

Este elemento representa una operación NOT en el resultado de evaluar la correspondiente expresión de subelemento.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Este elemento representa una operación AND en el resultado de evaluar todas las expresiones de los correspondientes subelementos.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Este elemento representa una operación OR en el resultado de evaluar todas las expresiones de subelementos.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Este elemento se utiliza para realizar una comprobación instanceof del objeto que tiene el foco. La expresión devuelve EvaluationResult.TRUE si el tipo del objeto es un subtipo del tipo especificado por el atributo value. De lo contrario, se devuelve EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Este elemento se utiliza para evaluar el estado de propiedad del objeto que tiene el foco. El conjunto de propiedades que pueden probarse puede ampliarse mediante el punto de extensión de probador de propiedades. La expresión de prueba devuelve EvaluationResult.NOT_LOADED si el probador de propiedades que realiza la prueba no se ha cargado todavía.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Prueba una propiedad del sistema llamando al método System.getProperty y compara el resultado con el valor especificado con el atributo value.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Este elemento se utiliza para realizar una comprobación equals del objeto que tiene el foco. La expresión devuelve EvaluationResult.TRUE si el objeto es igual al valor proporcionado por el atributo value. De lo contrario, se devuelve EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Este elemento se utiliza para probar el número de elementos de una colección.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

Este elemento cambia el objeto en el que hay que inspeccionar todos los elementos hijo para que pase a ser el objeto al que hace referencia la variable dada. Si la variable no se puede resolver, la expresión lanzará una ExpressionException al evaluarla. Los hijos de una expresión with se combinan mediante el operador and.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Este elemento cambia el objeto en el que hay que inspeccionar todos los elementos hijo para que pase a ser el objeto al que hace referencia la variable dada. Si la variable no se puede resolver, la expresión lanzará una ExpressionException al evaluarla. Los hijos de una expresión with se combinan mediante el operador and.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

Este elemento se utiliza para adaptar el objeto en foco al tipo especificado por el atributo type. La expresión retorna sin cargar si el adaptador o el tipo al que se hace referencia todavía no está cargado. Se lanza una ExpressionException durante la evaluación si el nombre del tipo no existe en absoluto. Los hijos de una expresión adapt se combinan mediante el operador and.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

Este elemento se usa para reiterar una variable del tipo java.util.Collection. Si el objeto que tiene el foco no es del tipo java.util.Collection, se enviará una ExpressionException al evaluar la expresión.



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 plug-in "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 plug-in 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 plug-ins 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 plug-ins 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 plug-ins 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.