Contribuciones de menú del entorno de trabajo

Se han visto diferentes puntos de extensión que efectúan contribuciones a varios menús y barras de herramientas del entorno de trabajo. Para saber cuál ha de utilizar, vea la tabla siguiente, que muestra un resumen de las diversas contribuciones de menú y de cómo utilizarlas.

Nombre de punto de extensión

Ubicación de acciones

Detalles

viewActions

Las acciones aparecen en una barra de herramientas local y en un menú desplegable local específicos de la vista.

Contribuya con una clase de acción que implemente IViewActionDelegate. Especifique el identificador de la contribución y el identificador de la vista destino que debe mostrar la acción. La etiqueta y la imagen indican el aspecto de la acción en la UI. La vía de acceso especifica la ubicación relativa a los elementos de menú y de barra de herramientas de la vista.

editorActions

Las acciones están asociadas con un editor y aparecen en el menú y/o la barra de herramientas del entorno de trabajo.

Contribuya con una clase de acción que implemente IEditorActionDelegate. Especifique el identificador de la contribución y el identificador del editor destino que hace que se muestre la acción. La etiqueta y la imagen indican el aspecto de la acción en la UI. Diferentes vías de acceso de menú y de barra de herramientas especifican la existencia y ubicación de la contribución en el menú y la barra de herramientas del entorno de trabajo.

popupMenu

Las acciones aparecen en el menú emergente de un editor o una vista. Las acciones asociadas con un tipo de objeto aparecen en todos los menús emergentes de vistas y editores que muestran el tipo de objeto. Las acciones asociadas con un menú emergente específico sólo aparecen en ese menú emergente.

Las Contribuciones de objeto especifican el tipo de objeto para el que la acción debe aparecer en un menú emergente. La acción se mostrará en los menús emergentes de todas las vistas y editores que contienen el tipo de objeto.  Proporcione una clase de acción que implemente IObjectActionDelegate
Las Contribuciones de visor especifican el identificador del menú emergente destino en el que debe aparecer el elemento de menú.  Proporcione una clase de acción que implemente IEditorActionDelegate o IViewActionDelegate

actionSets

Las acciones aparecen en los menús principales y la barra de herramientas del entorno de trabajo. Las acciones se agrupan en conjuntos de acciones. Todas las acciones de un conjunto de acciones se mostrarán en los menús y las barras de herramientas del entorno de trabajo de acuerdo con el conjunto de acciones y la perspectiva actual que haya seleccionado el usuario, y que se muestran en el entorno de trabajo.

Contribuya con una clase de acción que implemente IWorkbenchWindowActionDelegate o IWorkbenchWindowPulldownDelegate. Especifique el nombre y el identificador del conjunto de acciones. Enumere todas las acciones que se han definido para ese conjunto de acciones. Para cada acción, diferentes vías de acceso de menú y de barra de herramientas especifican la existencia y ubicación de la contribución en el menú y la barra de herramientas del entorno de trabajo.

Vías de acceso de menú y de barra de herramientas

Se han visto muchas contribuciones de acciones que especifican la vía de acceso para la ubicación de dichas acciones. A continuación, se hablará de lo que significan estas vías de acceso.  En el menú Ayuda del entorno de trabajo encontrará una descripción de las vías de acceso.

Grupos con nombre

Las ubicaciones para insertar menús, elementos de menú o elementos de barra de herramientas nuevos se definen mediante grupos con nombre. Un grupo con nombre es como una ranura o espacio reservado que le permite insertar contribuciones de menú y de barra de herramientas en puntos concretos de un menú o de una barra de herramientas.

El entorno de trabajo define todos sus nombres de ranura de grupo en la clase IWorkbenchActionConstants. En cada menú del entorno de trabajo, los grupos con nombre se colocan en ubicaciones en las que se espera que los conectores inserten acciones nuevas.

La siguiente descripción del menú de ayuda se ha adaptado de la definición de clase IWorkbenchActionConstants.

Acciones del menú Ayuda estándar
Iniciar grupo HELP_START "start"
Finalizar grupo HELP_END "end"
Acerca de la acción ABOUT "About"

El menú de ayuda estándar del entorno de trabajo se compone de un grupo con nombre llamado"start," seguido de un grupo con nombre llamado "end," seguido de la acción "About". ¿Por qué dos grupos? Porque de esta manera, los conectores pueden controlar la ubicación en la que aparecen en el menú de ayuda. Al definir un menú, se pueden definir tantas ranuras como se desee. Si se añaden más ranuras, los conectores tendrán más control sobre el lugar en que aparecen sus contribuciones en relación a las contribuciones existentes.

Pero eso no es todo.  Se sabe que hay otros elementos de menú en el menú Ayuda,  que han sido añadidos por conectores.  Por ejemplo, los conectores de ayuda añaden al entorno de trabajo un conjunto de acciones que contiene el menú "Contenido de la ayuda". A continuación, se muestra la marcación  del plugin.xml del conector org.eclipse.help.ui.

<extension 
    point="org.eclipse.ui.actionSets">
    <actionSet
        id="org.eclipse.help.internal.ui.HelpActionSet"
        label="%help"
        visible="true">
        <action id="org.eclipse.help.internal.ui.HelpAction"
            menubarPath="help/helpEnd"
            label="%helpcontents"
            class="org.eclipse.help.internal.ui.ShowHelp"/>
    </actionSet>
</extension>

La nueva acción de ayuda se colocará en el menú de ayuda, dentro del grupo helpEnd. Si ningún otro conector ha efectuado contribuciones al menú de ayuda, esto significa que el elemento de menú "Contenido de la ayuda" aparecerá como el primer elemento del menú encima del elemento "Acerca de". Si otro conector quisiera contribuir con un elemento que siempre apareciera encima del elemento "Contenido de la ayuda", tendría que especificar el grupo helpStart en su vía de acceso.

Para las vías de acceso de barra de herramientas el proceso es similar. Siempre que se especifique una vía de acceso, debe finalizar con el nombre de un grupo en la barra de herramientas.

Vías de acceso totalmente calificadas de menú y de barra de herramientas

Una vía de acceso completa de menú o de barra de herramientas es simplemente una lista de parejas de nombre de menú y grupo con nombre. Los nombres de menú del entorno de trabajo también se definen en IWorkbenchActionConstants. Esto permite saber que la vía de acceso totalmente calificada para la acción de ayuda es "help/helpEnd."

Algunos menús contienen submenús jerarquizados, lo cual hace que las vías de acceso sean más largas. Si el menú de ayuda tuviera definido un submenú llamado "submenu" con un grupo con nombre llamado "submenuStart," la vía de acceso totalmente calificada del menú para una acción del nuevo submenú sería "help/submenu/submenuStart."

Externalizar etiquetas de UI

El ejemplo anterior también muestra un procedimiento para externalizar series que aparecen en la UI.  Esto resulta satisfactorio para traducir la UI del conector a otros idiomas.  Se pueden externalizar las series en archivos plugin.xml sustituyendo la serie por una clave (por ejemplo, %help, %helpcontents) y creando entradas en el archivo plugin.properties de esta manera:

help = "Ayuda"
helpContents = "Contenido de la ayuda"

De esta manera, se puede traducir el archivo plugin.properties a diferentes idiomas y no se precisa modificar el archivo plugin.xml.

Añadir menús y grupos nuevos

En la mayoría de los ejemplos que se han visto hasta ahora, las acciones con las que los conectores de muestra han contribuido se han añadido a grupos con nombre existentes en menús y barras de herramientas.

Los puntos de extensión actionSets, viewActions, editorActions y popupMenus también le permiten definir menús y grupos nuevos en las contribuciones. Esto significa que puede definir submenús o menús desplegables nuevos y contribuir con acciones a dichos menús. En este caso, la vía de acceso para la nueva acción contendrá el nombre del menú definido recientemente.

Se vio este procedimiento cuando la herramienta readme definió un menú nuevo para su conjunto de acciones.  A continuación, y después de haber tratado las vías de acceso de menú de manera más detallada, se muestra la marcación una vez más.

<extension 
    point = "org.eclipse.ui.actionSets">
    <actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
        label="ReadMe Actions"
        visible="true">
        <menu id="org_eclipse_ui_examples_readmetool"
            label="Readme &amp;File Editor"
            path="window/additions"> 
            <separator name="slot1"/>
            <separator name="slot2"/>
            <separator name="slot3"/>
        </menu>
        <action id="org_eclipse_ui_examples_readmetool_readmeAction"
            menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
            toolbarPath="readme"
            label="&amp;Open Readme Browser@Ctrl+R"
            tooltip="Open Readme Browser"
            helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
            icon="icons/basic/ctool16/openbrwsr.gif"
            class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
            enablesFor="1">
            <selection class="org.eclipse.core.resources.IFile"
                name="*.readme">
            </selection>
        </action>
    </actionSet>
</extension>

Se ha añadido un nuevo menú llamado  "org_eclipse_ui_examples_readmetool." Su etiqueta es la serie "Readme &File Editor." En este menú se han definido tres grupos con nombre:  "slot1," "slot2," y "slot3."  Se ha añadido este nuevo menú a la vía de acceso "window/additions."

Si se retrocede a IWorkbenchActionConstants, puede verse la siguiente definición del menú de ventana en el javadoc:

* <h3>Standard Window menu actions</h3>
* <ul>
* <li>Extra Window-like action group (<code>WINDOW_EXT</code>)</li> 

Si se sigue mirando la definición de clase, ser verán estas definiciones relacionadas:

public static final String MENU_PREFIX = "";
...
public static final String M_WINDOW = MENU_PREFIX+"window";
...
public static final String MB_ADDITIONS = "additions"; // Group.
...
public static final String WINDOW_EXT = MB_ADDITIONS; // Group.

A partir de esta información, se puede crear la vía de acceso para efectuar adiciones en el menú "Window" del entorno de trabajo.  El menú se llama "window" y define una ranura llamada "additions." . Para añadir el menú nuevo, se utilizará la vía de acceso"window/additions".

En la declaración del conjunto de acciones, se ha añadido una acción al menú definido recientemente utilizando la vía de acceso "window/org_eclipse_ui_examples_readmetool/slot1."

Se podrían añadir otros conectores al menú utilizando esta misma vía de acceso (o tal vez una de las ranuras restantes) al objeto de añadir uno de sus propios menús.  

Generalmente, no es aconsejable efectuar contribuciones a otro menú u otra barra de herramientas del conector derivando el nombre de vía de acceso desde el plugin.xml,  ya que una versión futura del conector podría cambiar los nombres de las vías de acceso.  Lo que se aconseja es definir una interfaz pública (como IWorkbenchActionConstants) que especifica exactamente qué menús, grupos de barras de herramientas y ranuras son fiables para que las puedan utilizar otros conectores.