Menús, barras de tareas y acciones del editor
Identificador: org.eclipse.ui.editorActions
Descripción: Este punto de extensión se utiliza para añadir acciones a las barras de menú y de herramientas para los editores registrados por otros plug-ins.
El conjunto de contribución inicial para un editor lo define otro punto de extensión (org.eclipse.ui.editors).
Todas las instancias del mismo tipo de editor crean y comparten un conjunto de acciones. Cuando se recurre a una de ellas, esta acción actúa sobre el editor activo. Este punto de extensión actúa del mismo modo. Todas las instancias del mismo tipo de editor crean y comparten cada extensión de acción. La clase de acción es necesaria para implementar org.eclipse.ui.IEditorActionDelegate.
El editor activo pasa al delegado al recurrir a IEditorActionDelegate#setActiveEditor.
Señalamiento de configuración:
<!ELEMENT editorContribution (menu | action)*>
<!ATTLIST editorContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - identificador único que puede utilizarse para denominar esta contribución
editorId - identificador único de un editor registrado previamente que constituye el objetivo de esta contribución
<!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ús. Si se omite, el menú se encajará en el elemento adiciones 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 representa a un grupo nominado en el último menú de la vía de acceso.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - nombre del separador que más tarde puede ser mencionado 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.
<!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 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. La vía de acceso únicamente puede indicar menús que pertenezcan al editor de objetivos. 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, la acción no aparecerá.
-
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 contribuido.
-
tooltip - utilizado si la acción ha de aparecer 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).
-
class - nombre de la clase calificada que implementa org.eclipse.ui.IEditorActionDelegate
-
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.
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 traducido. 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). Los modificadores pueden encadenarse utilizando el signo '+' como delimitador (como en @Ctrl+Shift+S).
Ejemplos:
A continuación podemos observar un ejemplo de punto de extensión de acción de editor:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu id="com.xyz.xyzMenu"
label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Ejecutar herramienta XYZ"
menubarPath="com.xyz.xyzMenu/grupo1"
toolbarPath="Normal/XYZ"
state="true"
icon="icons/runXYZ.gif"
tooltip="Ejecutar herramienta XYZ"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ">
</action>
</editorContribution>
</extension>
En el ejemplo anterior, la acción especificada aparecerá como un elemento de recuadro de selección en el menú, y como un botón conmutador en la barra de herramientas.
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.IEditorActionDelegate.
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.
Cada vez que se active un editor del tipo especificado, se solicitará el método setActiveEditor.
Solamente se creará un conjunto de acciones y menú para todas las instancias del tipo de editor especificado, sin reparar en el número de instancias del editor que se hallen abiertas en el entorno de trabajo.
Este punto de extensión puede utilizarse para contribuir acciones en los menús creados previamente por el editor de objetivos. Además, los menús y las acciones pueden contribuirse a la ventana del entorno de trabajo. Los identificadores para las acciones y los grupos principales incluidos en la ventana del entorno de trabajo están definidos en org.eclipse.ui.IWorkbenchActionConstants.
Éstos deben utilizarse como punto de referencia para la adición de nuevas acciones.
Los menús de alto nivel se crean utilizando los siguientes valores para el atributo path:
-
additions - describen a un grupo situado a la izquierda del menú Ventana.
Las acciones y los menús añadidos a estas vías de acceso únicamente se mostrarán mientras esté activo el editor asociado. Cuando éste se cierre, los menús y las acciones serán eliminados.
Implementación suministrada: El entorno de trabajo proporciona de serie un "editor de textos por omisión". Los plug-ins pueden contribuir en este editor por omisión o en los editores proporcionados por otros plug-ins.