Menús, barras de herramientas y acciones de las vistas

Identificador: org.eclipse.ui.viewActions

Descripción: este punto de extensión permite añadir acciones al menú desplegable y a la barra de herramientas para las vistas registradas por otros conectores. Cada vista posee un menú desplegable local, que se activa generalmente al pulsar el botón triangular del área superior derecha. Los otros conectores pueden contribuir suministrando submenús y acciones a este menú. Los conectores también pueden contribuir proporcionando acciones a la barra de herramientas de una vista. Los propietarios de la vista son los primeros en recibir la opción de poblar estas áreas. Las adiciones opcionales de otros conectores se añaden al final.

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.

Códigos XML de configuración:

   <!ELEMENT extension (viewContribution+)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

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

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

   <!ATTLIST viewContribution
      id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

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

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

   <!ATTLIST action
      id            CDATA #REQUIRED
      label         CDATA #REQUIRED
     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
   >

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

   Este elemento se utiliza para definir un menú nuevo.

   <!ATTLIST menu
      id    CDATA #REQUIRED
      label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

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

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   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.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   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.

   <!ATTLIST selection
      class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

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

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

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

   Este elemento se utiliza para definir la visibilidad de la acció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 dos expresiones de subelemento.

   <!ELEMENT objectClass EMPTY>

   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.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   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.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Este elemento se utiliza para evaluar el estado de un conector. El estado del conector puede ser una de los siguientes: instalado (installed) o activado (activated).

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

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

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Ejemplos: a continuación figura un ejemplo de extensión de acciones de vista:

   <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="&amp;Ejecutar herramienta XYZ"
            menubarPath="com.xyz.xyzMenu/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> 
     </viewContribution> 
   </extension> 

En el ejemplo anterior, la acción especificada solo se habilitará para una selección individual (atributo enablesFor). Además, el objeto de la selección debe ser ser un recurso de archivo Java.

A continuación figura otro ejemplo de extensión de acciones de vista:

   <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.runXYZ2" 
            label="&amp;Ejecutar herramienta XYZ2"
            menubarPath="com.xyz.xyzMenu/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 este ejemplo, la acción especificada aparecerá como elemento de menú. La acción se habilita si la selección no contiene recursos de archivo Java.

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.IViewActionDelegate. Esta clase se cargará lo más tarde posible para evitar que se cargue todo el conector antes de que sea realmente necesario.

La interfaz org.eclipse.ui.IViewActionDelegate amplía org.eclipse.ui.IActionDelegate y añade un método adicional que permite al delegado inicializar con la instancia de vista a la que está contribuyendo.

Este punto de extensión puede utilizarse para suministrar acciones a los menús creados anteriormente por la vista destino. La omisión del atributo de vía de acceso de menú (menu path) dará como resultado la adición del nuevo menú o acción al final del menú desplegable.

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>

Implementación suministrada: normalmente, cada vista viene con varios elementos estándar en el menú desplegable y en la barra de herramientas local. Las contribuciones procedentes de otros conectores se añadirán al final del complemento estándar.

Copyright (c) 2000, 2003 IBM Corporation y otros. Reservados todos los derechos. Este programa y sus materiales adjuntos están disponibles bajo los términos de la licencia pública común (Common Public License) v1.0 que acompaña a esta distribución, y está disponible en http://www.eclipse.org/legal/cpl-v10.html