Menús, barras de herramientas y acciones de editor
Identificador: org.eclipse.ui.editorActions
Descripción: este punto de extensión permite añadir
acciones a los menús y barras herramientas de los editores registrados
por otros conectores.
El conjunto de contribución inicial de un editor está definido por 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 invocan, las acciones actúan sobre el editor activo. Este punto de
extensión sigue el mismo patrón de comportamiento. Todas las instancias del
mismo tipo de editor crean y comparten cada extensión de acción. La clase de
acción debe implementar org.eclipse.ui.IEditorActionDelegate. El
editor activo se pasa al delegado al invocar
IEditorActionDelegate#setActiveEditor.
Códigos XML de configuración:
<!ELEMENT editorContribution (menu | action)*>
<!ATTLIST editorContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id: identificador exclusivo que puede utilizarse para hacer referencia a
esta contribución.
editorId: identificador exclusivo de un editor registrado anteriormente
que sea el destino de esta contribución.
<!ELEMENT menu (separator)+>
<!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á al espacio additions 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
representa 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.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
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
class
CDATA #REQUIRED
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: acelerador de la acción. Se especifica como una combinación de las
teclas CTRL (Control), SHIFT (Mayús) y ALT y una tecla aceleradora. Estos valores no están
internacionalizados y no se deben traducir. La especificación del acelerador para el
título de la entrada debe efectuarse en la etiqueta; este valor no se utilizará para
construir una entrada de menú.
-
menubarPath: vía de acceso absoluta delimitada por barras inclinadas
('/') que sirve para especificar la ubicación de la acción en la barra de
menús. La vía de acceso únicamente puede señalar hacia los menús que
pertenezcan al editor destino. 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 aparecerá.
-
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.
-
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.
-
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: se utiliza si la acción debe 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).
-
class: nombre de la clase totalmente calificada que implementa
org.eclipse.ui.IEditorActionDelegate.
-
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 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 utilizar el elemento enablement en
actionExpressions.html.
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.
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 la serie de modificadores y el
carácter acelerador final (por ejemplo,
&Guardar@Control+G). Los modificadores se pueden 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.
Ejemplos:
A continuación figura un ejemplo de punto de
extensión de acciones de un editor:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu id="XYZ"
label="&Menú XYZ">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ"
label="&Ejecutar herramienta XYZ"
menubarPath="XYZ/group1"
toolbarPath="Normal/additions"
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 elemento de
recuadro de selección en el nuevo menú de nivel superior llamado "Menú XYZ", y
como botón conmutador en la barra de herramientas.
A continuación figura un ejemplo de punto de
extensión de acciones de un editor:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyz2Contribution"
targetID="com.ibm.XMLEditor">
<menu
id="XYZ2"
label="&Menú XYZ2"
path="edit/additions">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ2"
label="&Ejecutar herramienta XYZ2"
menubarPath="edit/XYZ2/group1"
state="true"
icon="icons/runXYZ2.gif"
tooltip="Ejecutar herramienta XYZ2"
helpContextId="com.xyz.run_action_context2"
class="com.xyz.actions.RunXYZ2">
</action>
</editorContribution>
</extension>
En el ejemplo anterior, la acción especificada aparecerá como elemento de
recuadro de selección en el submenú llamado "Menú XYZ2" del menú "Editar" de
nivel superior.
Información sobre las API: el valor del atributo
class debe ser un nombre totalmente calificado de una clase Java
que implemente org.eclipse.ui.IEditorActionDelegate. Esta interfaz se
cargará lo más tarde posible para evitar que se cargue todo el conector antes
de que sea realmente necesario. Cada vez que se active un editor del tipo
especificado, se llamará al método setActiveEditor. Solamente se
creará un único conjunto de acciones y menús para todas las instancias del tipo de
editor especificado, sin reparar en el número de instancias del editor que estén
abiertas actualmente en el entorno de trabajo.
Este punto de extensión puede utilizarse para contribuir suministrando acciones a los
menús creados anteriormente por el editor destino. Además, se puede
contribuir proporcionando menús y acciones a la ventana del entorno de trabajo. Los
identificadores de las acciones y los grupos principales que hay en la ventana
del entorno de trabajo están definidos en la interfaz de constantes
org.eclipse.ui.IWorkbenchActionConstants. Estas constantes deben
utilizarse como punto de referencia para la adición de nuevas acciones. Los
menús de nivel superior se crean utilizando los siguientes valores para el
atributo path:
-
additions: representa 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 este se cierre, los
menús y las acciones quedarán eliminados.
Implementación suministrada: el entorno de trabajo proporciona
un "editor de texto por omisión" incorporado. Los conectores pueden
suministrar contribuciones a este editor por omisión o a los editores
proporcionados por otros conectores.