Menús, barras de herramientas y acciones de vistas
Identificador: org.eclipse.ui.viewActions
Descripción: Este punto de extensión se utiliza para añadir acciones al menú y la barra de herramientas para vistas registradas por otros plug-ins. Cada vista posee un menú desplegable local, que se activa generalmente al pulsar en el área superior derecha. Otros plug-ins pueden contribuir submenús y acciones a este menú.
Los plug-ins pueden también contribuir acciones para una barra de herramientas de vista. Los propietarios de la vista son los primeros en recibir la opción de poblar estas áreas. Las adiciones opcionales de otros plug-ins se añaden.
Señalamiento de configuración:
<!ELEMENT viewContribution (menu | action)*>
<!ATTLIST viewContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - identificador único que puede utilizarse para denominar esta contribución
targetID - identificador exclusivo de la vista (como se especifica en el registro) a la cual se efectúa la contribución.
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - identificador único que puede utilizarse para hacer referencia a este menú
-
label - etiqueta de texto del nuevo menú. La etiqueta debe incluir información mnemotécnica.
-
path - ubicación del menú que comienza a partir del desplegable, cuyo último símbolo representa al grupo mencionado. Si se omite, el menú se añadirá al final del menú desplegable.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - nombre del separador que más tarde puede ser mencionado como el último símbolo 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.
<!ELEMENT action (selection)*>
<!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
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id - identificador único que puede usarse para referirse a 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 el menú desplegable. Cada símbolo de la vía de acceso, excepto el último, describe un submenú presente en la jerarquía.
El último símbolo 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 el desplegable.
-
toolbarPath - grupo denominado dentro de la barra de herramientas local de la vista en cuestión. Si el grupo no existe, será creado. Si se omite la vía de acceso, la acción no aparecerá en la barra de herramientas local.
-
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 herramientas local, 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 contribuyente.
-
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).
-
tooltip - utilizado si la acción ha de aparecer en la barra de herramientas local. 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.
-
class - nombre de la clase totalmente calificada que implementa org.eclipse.ui.IViewActionDelegate
-
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 ó 1 elemento seleccionado
+ - 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.
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 solicitada, 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 signo "y comercial" ('&') delante de un carácter seleccionado del texto traducible. Como no se permite usar el signo "y comercial" en las series XML, utilice el carácter &.
-
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). Lo modificado puede encadenarse utilizando el signo '+' como delimitador (como en @Ctrl+Shift+S).
Ejemplos:
A continuación vemos un ejemplo de punto de extensión de acciones de vista (adviértanse los subelementos y la manera de utilizar los atributos):
<extension point="org.eclipse.ui.viewActions">
<viewContribution
id="com.xyz.xyzViewC1"
targetID="org.eclipse.ui.views.navigator.ResourceNavigator">
<menu id="com.xyz.xyzMenu"
label="Menú XYZ"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1"/>
<selection class="org.eclipse.core.resources.IFile" name="*.java">
</action>
</viewContribution>
</extension>
En el ejemplo anterior, la acción especificada habilitará únicamente una selección (atributo enablesFor). Por añadidura, los objetos de esta selección deben implementar el interfaz especificado (IFile) y deben ser archivos de Java.
Pueden especificarse múltiples elementos de selection, significando "uno de".
Información del API: El valor del atributo class debe ser un nombre totalmente calificado de una clase de Java que implemente org.eclipse.ui.IViewActionDelegate.
Este interfaz se cargará lo más tarde posible a fin de evitar cargar el plug-in en su totalidad antes de que sea verdaderamente necesario.
Extiende org.eclipse.ui.IActionDelegate
y añade un método adicional que permite al delegado inicializar con la instancia de vista que éste contribuye.
Información suministrada: Cada vista por lo general posee varios elementos estándar en el menú desplegable y en la barra de herramientas local. Las adiciones efectuadas por otros plug-ins se añadirán al complemento estándar.
Es útil publicar los identificadores de acción de una vista dentro de un interfaz público. Por ejemplo, las acciones y los grupos principales de la ventana del entorno de trabajo están definidos en org.eclipse.ui.IWorkbenchActionConstants.