Conjuntos de acciones
Identificador: org.eclipse.ui.actionSets
Descripción: este punto de extensión permite añadir
menús, elementos 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 sean las preferencias del usuario.
Códigos XML de configuración:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id
CDATA #REQUIRED
label CDATA
#REQUIRED
visible (true | false)
#IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id: nombre exclusivo que se utilizará para identificar este
conjunto de acciones.
-
label: nombre traducible que se utilizará en el menú de la ventana del
entorno de trabajo para representar este conjunto de acciones.
-
visible: atributo opcional que indica si el conjunto de acciones estará
inicialmente visible en todas las perspectivas. Esta opción solo se respetará cuando el usuario
abra una perspectiva nueva que no se haya personalizado. El usuario también puede
alterar temporalmente esta opción desde el diálogo "Personalizar perspectiva".
-
description: subelemento opcional cuyo cuerpo debe contener un texto
que proporcione una descripción corta del conjunto de acciones.
<!ELEMENT menu (separator)+ (groupMarker)*>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id: identificador exclusivo que puede utilizarse para hacer referencia a
este menú.
-
label: etiqueta de texto del menú nuevo. La etiqueta debe incluir
información nemotécnica.
-
path: ubicación del menú, a partir de la raíz de la barra de
menús. Si se omite, el menú se añadirá antes del menú Ventana de la barra de
menús. Cada símbolo de la vía de acceso debe hacer referencia a un
menú existente en el entorno de trabajo, excepto el último, que debe
representar un grupo con nombre del último menú de la vía de acceso.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name: nombre del separador al que más adelante se puede hacer referencia
como último símbolo de la vía de acceso de la acción. Por lo tanto, los
separadores actúan a modo de grupos con nombre a los que pueden añadirse acciones
y submenús.
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name: nombre del marcador de grupo al que más adelante se puede hacer
referencia como último símbolo de la vía de acceso de la acción.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
enablesFor
CDATA #IMPLIED
>
-
id: identificador exclusivo que puede usarse como referencia para esta
acción.
-
label: nombre traducible que se utiliza de diversas formas, en función
del contexto. En los menús, se utiliza como texto del menú. En las barras de
herramientas, se utiliza como etiqueta de los botones. La etiqueta puede
contener información nemotécnica y de acelerador codificada con JFace (vea
el ejemplo).
-
accelerator: entero que sirve para especificar el código de teclas del
acelerador de la acción. Es el valor entero que se obtiene como resultado de
efectuar una operación OR a nivel de bits en cero o más máscaras de modificador
de teclas SWT (por ejemplo, SWT.CTRL o SWT.ALT) y un código de
caracteres. Por ejemplo, para Control+Z, se utilizaría SWT.CTRL | 'Z' =
(1<<18)|'Z' = 262234.
-
definitionId: ID especificado en la definición de la acción. Solo se
necesita cuando un conjunto de acciones especifica aceleradores mediante el
servicio de enlace de teclas. Vea los puntos de extensión
Definiciones de acción
y Conjuntos de aceleradores.
-
menubarPath: vía de acceso delimitada por barras inclinadas ('/') que
sirve para especificar la ubicación de la acción en la barra de menús. Cada
símbolo de la vía de acceso, excepto el último, debe representar un ID válido
de un menú existente en la jerarquía. El último símbolo representa el grupo de
separadores con nombre al que se añadirá la acción. Si se omite la vía de
acceso, la acción no aparecerá en la barra de menús.
-
toolbarPath: vía de acceso delimitada por barras inclinadas ('/')
que sirve para especificar la ubicación de la acción en la barra de
herramientas. El primer símbolo representa el ID de la barra de herramientas
(siendo "Normal" la barra de herramientas por omisión), mientras que el segundo
símbolo es el grupo con nombre dentro de la barra de herramientas. Si el grupo
no existe en la barra de herramientas, se creará. Si se omite el atributo
toolbarPath, la acción no figurará en la barra de herramientas.
-
icon: vía de acceso relativa de un icono que se utilizará para
representar visualmente la acción en su contexto. Si se omite este atributo y
la acción debe aparecer en la barra de menús, el entorno de trabajo utilizará
un icono de espacio reservado. La vía de acceso es relativa a la ubicación del
archivo plugin.xml del conector que hace la contribución. El icono aparecerá en
las barras de herramientas, pero no en los menús. Las acciones habilitadas
vendrán representadas en los menús mediante el objeto hoverIcon.
-
disabledIcon: vía de acceso relativa de un icono que se empleará para
representar visualmente la acción en su contexto cuando esté inhabilitada. Si se
omite este atributo, se verá sencillamente el icono normal atenuado. La vía de acceso es relativa a la ubicación del
archivo plugin.xml del conector que hace la contribución. El icono de
inhabilitado aparecerá en las barras de herramientas, pero no en los
menús. El sistema operativo (OS) suministrará los iconos de las acciones
inhabilitadas en los menús.
-
hoverIcon: vía de acceso relativa de un icono que se empleará para
representar visualmente la acción en su contexto cuando el puntero del ratón
esté sobre la acción. Si se omite este atributo, se utilizará el icono
normal. La vía de acceso es relativa a la ubicación del
archivo plugin.xml del conector que hace la contribución.
-
tooltip: valor del texto de ayuda flotante si la acción tiene que aparecer en la
barra de herramientas. De lo contrario, no se tiene en cuenta.
-
helpContextId: identificador exclusivo que indica el ID del contexto de
ayuda para esta acción. Si la acción aparece como elemento de menú y se pulsa
F1 mientras el elemento de menú esté resaltado, se visualizará la ayuda
correspondiente al ID del contexto dado.
-
state: atributo opcional que indica que la acción debe ser de tipo
conmutador. Cuando se añade a un menú, se automanifestará como elemento de
recuadro de selección. Cuando se añade a una barra de herramientas, pasará a
ser un botón conmutador. Si está definido, se utilizará el valor del atributo
como estado inicial (ya sea true o false). Este atributo y el
atributo pulldown se excluyen mutuamente.
-
pulldown: atributo opcional que indica que la acción posee un menú
desplegable adicional. Si la acción aparece en una barra de herramientas
y el valor del atributo es true, se verá un menú desplegable junto a la
acción. Si la acción aparece en un menú, este atributo se pasa por alto.
Este atributo y el atributo state se excluyen mutuamente.
-
class: nombre totalmente calificado de una clase que implementa
la interfaz org.eclipse.ui.IWorkbenchWindowActionDelegate o la interfaz
org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Esta última debe
implementarse en los casos en que el valor de pulldown sea true. Este atributo no
se debe suministrar si el valor del atributo retarget es true.
-
retarget: si el valor de este atributo es true, se creará una acción de redestinar
(global). Los componentes pueden suministrar un manejador para esta acción
global utilizando el mecanismo estándar que permite establecer un manejador de
acciones global en el correspondiente sitio mediante el ID de esta acción. Si
el valor de este atributo es true, no debe suministrarse el atributo class.
-
allowLabelUpdates: solo es aplicable si el valor del atributo retarget
es true. Si el valor del presente atributo es true, la acción de redestinar
actualizará su etiqueta y su ayuda flotante a partir del correspondiente
manejador.
-
enablesFor: valor que indica la cuenta de selecciones que debe cumplirse
para que se habilite la acción. Si se especifica este atributo y se cumple la
condición, la acción queda habilitada. Si la condición no se cumple, la acción
queda inhabilitada. Si no se especifica el atributo, la acción queda habilitada
para cualquier número de elementos que se seleccionen. Los formatos soportados para
este atributo son los siguientes:
! - 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. Ejemplo: 4
* - cualquier número de elementos seleccionados
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class: nombre totalmente calificado de la clase o la interfaz que cada
objeto de la selección debe implementar o tener como subclase para que se habilite la
acción.
-
name: filtro comodín para el nombre, que puede opcionalmente aplicarse a
los objetos de la selección. Si se especifica este filtro y falla la
comparación, la acción quedará inhabilitada.
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty | pluginState)*>
<!ATTLIST enablement EMPTY>
En la versión 2.0 de Eclipse, puede usarse un elemento enablement
para definir la habilitación de la acción. Hallará más información sobre cómo
se utiliza el elemento enablement en
actionExpressions.html.
Ejemplos:
A continuación vemos un ejemplo de un conjunto de
acciones (fíjese en los subelementos y en la manera de utilizar los atributos):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="Mis Acciones"
visible="true">
<menu id="com.xyz.xyzMenu"
label="Menú XYZ"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Ejecutar herramienta XYZ"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
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="&Ejecutar herramienta ABC"
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">
</action>
</actionSet>
</extension>
En el ejemplo anterior, la acción especificada, denominada "Mis Acciones",
está inicialmente visible dentro de cada perspectiva. Únicamente se habilitará
para una sola selección (atributo enablesFor). Además, los objetos que
hay dentro de la selección deben implementar la interfaz especificada
(IFile) y tienen que ser un archivo Java.
Información sobre las API: el valor del atributo
class debe ser el nombre totalmente calificado de una clase que
implementa la interfaz org.eclipse.ui.IWorkbenchWindowActionDelegate o la interfaz
org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Esta última debe
implementarse en los casos en que el valor del atributo pulldown sea
true. Esta clase se carga 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 acciones se definen
inicialmente con 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.
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 y aceleradores siguiendo estas reglas:
-
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
&.
-
Los aceleradores opcionales se especifican al final de la serie del nombre,
utilizando el carácter @ seguido de una serie de modificadores y el
carácter acelerador final (por ejemplo,
&Guardar@Control+G). El modificador se puede encadenar
utilizando el signo '+' como delimitador (como en @Control+Mayús+G).
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. Este comportamiento es
definitivamente poco 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.
Implementación suministrada: los conectores pueden utilizar
este punto de extensión para añadir nuevos menús de nivel superior (por
ejemplo, Depuración). 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:
-
additions: representa un grupo situado a la izquierda del menú Ventana.
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 (constantes de acciones de entorno de
trabajo). 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 de la ventana 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ú Ventana. Las extensiones de
los asistentes de Importar, Exportar y Nuevo también se añaden a la ventana
automáticamente.