Conjuntos de acciones

org.eclipse.ui.actionSets

Este punto de extensión permite añadir menús, opciones de menú y botones de barra de herramientas a las áreas comunes de la ventana del entorno de trabajo. A estas contribuciones se las conoce colectivamente como conjunto de acciones y aparecen dentro de la ventana del entorno de trabajo según sea la personalización de una perspectiva que realice el usuario.

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 (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT actionSet (menu* , action*)>

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

visible     (true | false)

description CDATA #IMPLIED>

Este elemento se utiliza para definir un grupo de acciones y/o menús.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

accelerator      CDATA #IMPLIED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

toolbarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

disabledIcon     CDATA #IMPLIED

hoverIcon        CDATA #IMPLIED

tooltip          CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown) "push"

state            (true | false)

pulldown         (true | false)

class            CDATA #IMPLIED

retarget         (true | false)

allowLabelUpdate (true | false)

enablesFor       CDATA #IMPLIED>

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



<!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 una ejemplo de conjunto de acciones (observe los subelementos y la manera de utilizar los atributos):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"Mis acciones"

>

<menu id=

"com.xyz.xyzMenu"

label=

"Menú XYZ"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Ejecutar herramienta XYZ"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Ejecutar herramienta XYZ"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

enablesFor=

"1"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

<action id=

"com.xyz.runABC"

label=

"&amp;Ejecutar herramienta ABC"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Ejecutar herramienta ABC"

helpContextId=

"com.xyz.run_abc_action_context"

retarget=

"true"

allowLabelUpdate=

"true"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

<action id=

"com.xyz.runDEF"

label=

"&amp;Ejecutar herramienta DEF"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Ejecutar herramienta DEF"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Ejecutar herramienta GHI"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Ejecutar herramienta GHI"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Ejecutar herramienta JKL"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Ejecutar herramienta JKL"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

En el ejemplo anterior, el conjunto de acciones especificado, denominado "Mis acciones", no está inicialmente visible dentro de cada perspectiva, debido a que no se ha especificado el atributo visible.

La acción XYZ aparecerá como elemento de menú de tipo recuadro de selección, inicialmente sin seleccionar. Sólo se habilitará si la cuenta de selecciones es 1 y si ésta contiene un recurso de archivo Java.

La acción ABC aparecerá tanto en el menú como en la barra de herramientas. Sólo se habilitará si la selección no contiene ningún recurso de archivo Java. Observe también que se trata de una acción de redireccionamiento de etiqueta; por tanto, no suministra ningún atributo class.

Las acciones DEF, GHI y JKL aparecerán como elementos de menú de tipo botón de selección. Se habilitarán siempre, independientemente del estado de la selección actual.

El valor del atributo class debe ser el nombre totalmente calificado de una clase que implemente org.eclipse.ui.IWorkbenchWindowActionDelegate o org.eclipse.ui.IWorkbenchWindowPulldownDelegate. La última de ellas debe implementarse en los casos en que el atributo style tenga el valor pulldown. Esta clase es el manejador responsable de realizar la acción. Si el atributo retarget es true, este atributo se pasa por alto y no debe suministrarse. Esta clase se cargará lo más tarde posible para evitar que se cargue todo el conector antes de que sea realmente necesario.

Los criterios de habilitación de una extensión de acción se definen inicialmente en los atributos enablesFor, y también en selection o 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.

Es importante tener en cuenta que el entorno de trabajo no genera menús en nombre de los conectores. Las vías de acceso de los menús deben hacer referencia a menús que ya existen.

Las etiquetas de acción y de menú pueden contener caracteres especiales que codifiquen nemotécnicos siguiendo estas reglas:

  1. Los nemotécnicos 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 contribuye suministrando dos o más acciones a un menú o barra de herramientas mediante una extensión individual, las acciones aparecerán en el orden inverso de 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>

Los conectores pueden utilizar este punto de extensión para añadir nuevos menús de nivel superior. Los conectores pueden asimismo definir grupos con nombre que permitan a otros conectores contribuir suministrando sus acciones a dichos grupos.

Los menús de nivel superior se crean utilizando los valores siguientes para el atributo path:

La omisión del atributo path dará como resultado la adición del nuevo menú al grupo additions de la barra de menús.

Los grupos por omisión de una ventana del entorno de trabajo están definidos en la interfaz IWorkbenchActionConstants. Estas constantes pueden utilizarse en el código para la contribución dinámica. Los valores también pueden copiarse en un archivo XML para obtener una integración más precisa con los menús y la barra de herramientas existentes en el entorno de trabajo.

Dentro de la ventana del entorno de trabajo, hay diversos elementos de menú y de barra de herramientas que están definidos algorítmicamente. En tales casos, hay que utilizar un mecanismo aparte para ampliar la ventana. Por ejemplo, la adición de una vista nueva del entorno de trabajo da como resultado la aparición de un nuevo elemento en el menú Perspectiva. Las extensiones de los asistentes de Importar, Exportar y Nuevo también se añaden a la ventana automáticamente.