Menús, barras de herramientas y acciones de editor

org.eclipse.ui.editorActions

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, estas acciones actúan sobre el editor activo. Este punto de extensión sigue el mismo patrón. Todas las instancias del mismo tipo de editor crean y comparten cada extensión de acciones. La clase de las acciones debe implementar org.eclipse.ui.IEditorActionDelegate. El editor activo se pasa al delegado invocando a IEditorActionDelegate.setActiveEditor.

La habilitación y/o visibilidad de una acción puede definirse mediante los elementos enablement y visibility, respectivamente. Estos dos elementos contienen una expresión booleana que se evalúa para determinar la habilitación y/o visibilidad.

La sintaxis es la misma para ambos elementos, enablement y visibility. Ambos contienen sólo un subelemento de expresión booleana. En el caso más simple, se tratará de un elemento objectClass, objectState, pluginState o systemProperty. En el caso más complejo, pueden combinarse los elementos and, or y not para formar una expresión booleana. Tanto lo elementos and como los elementos or deben contener 2 subelementos. El elemento not debe contener sólo 1 subelemento.

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT editorContribution (menu* , action*)>

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Este elemento se utiliza para definir un grupo de acciones y/o menús de editor.



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

accelerator   CDATA #IMPLIED

definitionId  CDATA #IMPLIED

menubarPath   CDATA #IMPLIED

toolbarPath   CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      CDATA #IMPLIED>

Este elemento define una acción a la que el usuario puede llamar en la UI.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Este elemento se utiliza para definir un menú nuevo.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Este elemento se utiliza para crear un separador de menú en el menú nuevo.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Este elemento se utiliza para crear un grupo con nombre en el menú nuevo. No tiene representación visual en el menú nuevo, a diferencia del elemento separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Este elemento se utiliza para ayudar a determinar la habilitación de la acción en función de la selección actual. Se pasa por alto si se ha especificado el elemento enablement.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento se utiliza para definir la habilitación de la extensión.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento se utiliza para definir la visibilidad de la extensión.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento representa una operación booleana AND en el resultado de evaluar sus dos expresiones de subelemento.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento representa una operación booleana OR en el resultado de evaluar sus dos expresiones de subelemento.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento representa una operación booleana NOT en el resultado de evaluar sus expresiones de subelemento.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Este elemento se utiliza para evaluar la clase o interfaz de cada objeto de la selección actual. Si cada objeto de la selección implementa la clase o interfaz especificada, la expresión se evalúa como true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento se utiliza para evaluar el estado de atributo de cada objeto de la selección actual. Si cada objeto de la selección tiene el estado de atributo especificado, la expresión se evalúa como true. Para evaluar este tipo de expresión, cada objeto de la selección debe implementar o adaptarse a la interfaz org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Este elemento se utiliza para evaluar el estado de un conector. El estado del conector puede ser uno de los siguientes: instalado (installed) (equivalente al concepto OSGi de "resuelto") o activado (activated) (equivalente al concepto OSGi de "activo").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento se utiliza para evaluar el estado de alguna propiedad del sistema. El valor de propiedad se recupera de java.lang.System.



A continuación figura un ejemplo 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=

"&amp;Menú XYZ"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Ejecutar herramienta XYZ"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Ejecutar herramienta XYZ"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</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. La acción se habilita si la selección contiene sólo recursos de archivo Java.

A continuación figura otro ejemplo 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=

"&amp;Menú XYZ2"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Ejecutar herramienta XYZ2"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Ejecutar herramienta XYZ2"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</editorContribution>

</extension>

En el ejemplo anterior, la acción especificada aparecerá como elemento de menú en el submenú llamado "Menú XYZ2" del menú "Editar" de nivel superior. La acción se habilita si la selección no contiene recursos de archivo Java.

El valor del atributo class debe ser un nombre totalmente calificado de una clase Java que implemente org.eclipse.ui.IEditorActionDelegate. Esta clase 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 conjunto de acciones y menús para todas las instancias del tipo de editor especificado, independientemente del 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, pueden añadirse menús y acciones a la ventana Entorno de trabajo. Los identificadores de las acciones y grupos principales dentro de la ventana Entorno de trabajo se definen en org.eclipse.ui.IWorkbenchActionConstants. Deben utilizarse como punto de referencia para la adición de acciones nuevas. Los menús de nivel superior se crean utilizando los valores siguientes para el atributo path:

La omisión del atributo path dará como resultado la adición del nuevo menú al grupo additions de la barra de menús.

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 quedarán eliminados.

Los criterios de habilitación de una extensión de acción se definen inicialmente en los atributos enablesFor, y también en selection o 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 siguiendo estas reglas:

  1. 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 &amp;.
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. Obviamente, este comportamiento no es 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.

Los elementos selection y enablement son mutuamente excluyentes. El elemento enablement puede sustituir al elemento selection mediante los subelementos objectClass y objectState. Por ejemplo, el siguiente código:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

puede expresarse de esta forma:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

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.