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 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.
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 conector "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 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 &.
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:
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