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.
push | - como elemento de menú o elemento de barra de herramientas habitual. | |
radio | - como elemento de menú o de barra de herramientas de tipo botón de selección. Las acciones con estilo de botón de selección que se encuentran en el mismo grupo de barra de herramientas o de menús de comportan como un conjunto de botones de selección. El valor inicial se especifica en el atributo state. | |
toggle | - como elemento de menú o de barra de herramientas de tipo marca de selección. El valor inicial se especifica en el atributo state. | |
pulldown | - como opción de menú de estilo en cascada. |
! | - 0 elementos seleccionados | |
? | - 0 ó 1 elementos seleccionados | |
+ | - 1 o más elementos seleccionados | |
multiple, 2+ | - 2 o más elementos seleccionados | |
n | - un número concreto de elementos seleccionados. Por ejemplo: enablesFor=" 4" habilita la acción sólo cuando hay 4 elementos seleccionados | |
* | - cualquier número de elementos seleccionados |
Los criterios de habilitación de una extensión de acción se definen inicialmente en los atributos enablesFor, selection y enablement. Sin embargo, una vez creada una instancia del delegado de la acción, dicha instancia puede controlar el estado de habilitación de la acción directamente dentro del correspondiente método selectionChanged.
<!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.
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.<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=
"&Herramientas Java XYZ"
>
<separator name=
"group1"
/>
</menu>
<action id=
"com.xyz.runXYZ"
label=
"&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=
"&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>
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.
A continuación figura otro ejemplo de utilización del elemento de visibilidad (visibility):<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>
<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=
"&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.
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 &.
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:
puede expresarse de esta forma:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2005 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 (Eclipse Public License) v1.0 que acompaña a esta
distribución, y está disponible en
http://www.eclipse.org/legal/epl-v10.html