Establecimiento de acciones
Identificador: org.eclipse.ui.actionSets
Descripción: Este punto de extensión se utiliza para añadir menús, elementos de menús y botones de la barra de herramientas en las áreas comunes de la ventana del entorno de trabajo. Estas contribuciones son conocidas colectivamente como un establecimiento de acciones y aparecen dentro de la ventana del entorno de trabajo a petición del usuario.
Señalamiento 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 establecimiento de acciones.
-
label - nombre traducible que se utilizará en el menú de la ventana del entorno de trabajo para describir este establecimiento de acciones.
-
visible - atributo opcional que indica si el establecimiento de acciones será visible en la ventana del entorno de trabajo. El usuario puede
alterar temporalmente esta opción desde el "Diálogo personalizar perspectiva".
-
description - subelemento opcional cuyo cuerpo debe contener un texto que proporcione una breve descripción del establecimiento de acciones.
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - identificador único que puede usarse para referenciar este menú
-
label - etiqueta de texto del nuevo menú. La etiqueta debe incluir información mnemotécnica.
-
path - ubicación del menú que comienza desde la raíz de la barra de menú. Si se omite, el menú se añadirá entre los menús Perspectiva y Ventana de la barra de menús. Cada señal de la vía de acceso debe hacer referencia a un menú existente en el entorno de trabajo, excepto el último, que debe representar a un grupo nominado en el último menú de la vía de acceso.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - el nombre del separador que más tarde puede ser referenciado como la última señal de la vía de acceso de la acción. Por tanto, los separadores sirven como grupos nominados en los cuales pueden añadirse acciones y submenús.
<!ELEMENT action (selección)*>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id - identificador único que puede usarse para referenciar esta acción
-
label - nombre traducible que se utiliza de diversas formas, dependiendo del contexto. En los menús, se utiliza como el texto del menú. En las barras de herramientas, se utiliza como etiqueta de botón. La etiqueta puede contener información mnemotécnica y del acelerador codificada con JFace (ver ejemplo).
-
menubarPath - vía de acceso delimitada por barras inclinadas ('/') utilizada para especificar la ubicación de la acción en la barra de menús. Cada señal de la vía de acceso, excepto la última, describe el identificador válido de un menú presente en la jerarquía.
La última señal describe el grupo separador denominado, en el cual 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 ('/') utilizada para especificar la ubicación de
la acción en la barra de herramientas. La primera señal describe el identificador de la barra de herramientas (la barra de herramientas "Normal" será la barra de herramientas por omisión), mientras que la segunda señal es el grupo denominado dentro de la barra de herramientas. Si el grupo no existe en la barra de herramientas, será creado. Si se omite la vía de acceso a la barra de herramientas, la acción no aparecerá en la barra de herramientas.
-
icon - vía de acceso relativa de un icono que se utilizará para describir visualmente la acción en su contexto. Si se omite y la acción debiera aparecer en la barra de menús, el entorno de trabajo utilizará un icono simbólico. La vía de acceso es relativa a la ubicación del archivo plugin.xml del plug-in contributivo.
-
tooltip - el valor del texto alusivo a las herramientas si la acción aparece en la barra de herramientas. De lo contrario, es ignorado.
-
helpContextId - identificador único que indica el identificador del contexto de ayuda para esta acción. Si la acción aparece como un elemento de menú, al pulsar F1 mientras el elemento de menú está resaltado se visualizará la ayuda para el identificador de contexto dado.
-
state - atributo opcional que indica que la acción debe ser del tipo conmutador. Al añadirlo a un menú, éste se manifestará como un elemento de recuadro de selección. Al añadirlo a una barra de herramientas, devendrá un botón conmutador.
Si está definido, el valor del atributo se utilizará como estado inicial (tanto
true como false). Este atributo es mutuamente excluyente con pulldown.
-
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", aparecerá un menú desplegable junto a la acción. Si la acción aparece en un menú, este atributo se ignora.
Este atributo es mutuamente excluyente con state.
-
class - nombre totalmente calificado de una clase que implementa org.eclipse.ui.IWorkbenchWindowActionDelegate
o org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Éste último debe implementarse en aquellos casos en los que pulldown es "true".
-
enablesFor - valor que indica el nivel de selección que debe darse para habilitar la acción. Si se especifica este atributo y se cumple la condición, se permite la acción. Si la condición no no se cumple, la acción se inhabilita. Si no se especifica ningún atributo, la acción se habilita para cualquier número de elementos seleccionados. Se da soporte a los atributos siguientes:
! - 0 elementos seleccionados
? - 0 o 1 elementos seleccionados
+ - 1 o más elementos seleccionados
múltiples, 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 interfaz que cada objeto de la selección debe subclasificar o implementar para habilitar la acción.
-
name - filtro comodín para el nombre que puede opcionalmente aplicarse a los objetos de la selección. Si este filtro fallase, la acción sería inhabilitada.
Es importante tener en cuenta que el entorno de trabajo no genera menús en nombre de los plug-ins:
las vías de acceso a los menús deben describir menús ya existentes.
Los criterios de habilitación para la extensión de una acción son definidos inicialmente por enablesFor y selection. Sin embargo, una vez que la acción delegada ha sido instanciada, podrá controlar el estado de habilitación de la acción directamente dentro de su método selectionChanged.
Las etiquetas de acción y de menú pueden contener caracteres especiales que codifican mnemotécnicos y aceleradores utilizando las reglas siguientes:
-
Los mnemotécnicos se especifican utilizando el carácter "y comercial" ('&') delante de un carácter seleccionado del texto traducido. Como no se permite usar el signo "y comercial" en las series XML, utilice los caracteres &.
-
Los aceleradores opcionales se especifican al final de la cadena de caracteres del nombre, utilizando
@ seguido de una serie de modificadores y el carácter acelerador final (por ejemplo, &Save@Ctrl+S). El modificador puede encadenarse utilizando el signo '+' como delimitador (como en @Ctrl+Shift+S).
Ejemplos:
A continuación vemos un ejemplo de establecimiento de acción (adviértanse los subelementos y 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="grupo1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Ejecutar herramienta XYZ"
menubarPath="com.xyz.xyzMenu/grupo1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="Ejecutar herramienta XYZ"
helpContextId="com.xyz.contexto_ejecutar_acción"
class="com.xyz.actions.RunXYZ"
enablesFor="1">
<selection class="org.eclipse.core.resources.IFile" name="*.java"/>
</action>
</actionSet>
</extension>
En el ejemplo anterior, la acción especificada, denominada "Mis Acciones", es inicialmente visible desde cada perspectiva. Solamente habilitará una selección (atributo enablesFor). Por añadidura, los objetos seleccionados deben implementar el interfaz especificado (IFile) y deberán ser archivos de Java.
Información del API: El valor del atributo class debe ser el nombre totalmente calificado de una clase que implementa org.eclipse.ui.IWorkbenchWindowActionDelegate
o org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Éste último debe implementarse en los casos en que pulldown sea "true". Esta clase se carga lo más tarde posible para evitar la carga del plug-in en su totalidad antes de que sea realmente necesario.
Implementación suministrada: Los plug-ins pueden utilizar este punto de extensión para añadir nuevos menús de máximo nivel (por ejemplo, Depurar). Los plug-ins pueden asimismo definir grupos nombrados que permitan que otros plug-ins les contribuyan sus acciones.
Los menús de máximo nivel se crean utilizando los valores siguientes para el atributo path:
-
additions - describen a un grupo situado a la izquierda del menú Ventana.
La omisión del atributo path dará como resultado la adición del nuevo menú en el grupo additions de la barra de menús.
Los grupos por omisión de una ventana de entorno de trabajo están definidos en el interfaz IWorkbenchActionConstants. Estas constantes pueden utilizarse en código para contribución dinámica.
Los valores también pueden copiarse en un archivo XML para una integración mayor con los menús del entorno de trabajo y la barra de herramientas existente.
Varios elementos de menú y de barra de herramientas de la ventana del entorno de trabajo se definen algorrítmicamente. En tales casos, deberá utilizarse 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 de menú en el menú Perspectiva. Las extensiones Importar, Exportar y Nuevos asistentes también se añaden a la ventana automáticamente.