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
       >    <!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
       >    <!ELEMENT selection EMPTY>
       <!ATTLIST selection
          class             CDATA #REQUIRED
          name              CDATA #IMPLIED
       >    <!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:

    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;.
    2. 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, &amp;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="&amp;Menú XYZ">
                <separator name="group1"/>
             </menu>
             <action
                  id="com.xyz.runXYZ"
                  label="&amp;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="&amp;Menú XYZ2"
                path="edit/additions">
                <separator name="group1"/>
             </menu>
             <action
                  id="com.xyz.runXYZ2"
                  label="&amp;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:

    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.

    Copyright IBM Corporation y otros 2000, 2002.