Hemos visto muchas contribuciones de acciones que especifican la vía de acceso para la ubicación de dichas acciones. Examinemos con más detalle el significado de estas vías de acceso.
En primer lugar, examinaremos las vías de acceso de menú observando el menú Ayuda del entorno de trabajo.
Las ubicaciones para insertar nuevos menús y elementos de menú se definen mediante grupos con nombre. Un grupo con nombre es como una ranura o espacio reservado que le permite insertar elementos de menú en puntos concretos de una barra de menús o de un menú desplegable.
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 la clase IWorkbenchActionConstants.
Acciones del menú Ayuda estándar Principio del grupo - HELP_START - "start" Fin del grupo - HELP_END - "end" Acción Acerca de - 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". La definición de dos grupos proporciona a los conectores más control sobre dónde se situarán en el menú Ayuda los elementos con los que se ha contribuido. Cuando defina un menú, podrá definir el número de ranuras que desee. Si se añaden más ranuras, los otros conectores tendrán más control sobre el lugar en que aparecen sus contribuciones en relación a las contribuciones existentes.
¡Pero espere! Sabemos que existen otros elementos de menú en el menú Ayuda. Han sido añadidos por los conectores. Por ejemplo, el conector de la ayuda añade un conjunto de acciones que contiene el menú "Contenido de la ayuda" al entorno de trabajo. El siguiente fragmento de código procede del archivo 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.ui.internal.HelpContentsAction" icon="icons/view.gif" helpContextId="org.eclipse.help.ui.helpContentsMenu" tooltip="%openhelpcontents"/> ...
La nueva acción de ayuda se colocará en el menú Ayuda, dentro del grupo helpEnd. Si ningún otro conector ha contribuido en el menú Ayuda, esto significa que el elemento de menú "Contenido de la ayuda" aparecerá como primer elemento del menú, más arriba del elemento "Acerca de". Si otro conector quisiera contribuir con un elemento que siempre apareciera más arriba del elemento "Contenido de la ayuda", podría especificar el grupo helpStart en su vía de acceso.
El formato de las vías de acceso de menú completas es "nombre de menú/nombre de grupo". En el entorno de trabajo, los nombres de menú se definen en la interfaz IWorkbenchActionConstants. Esta clase permite averiguar que el nombre de vía de acceso totalmente calificado de nuestra acción de ayuda es "help/helpEnd".
Algunos menús contienen submenús anidados. Esto 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".
El ejemplo anterior muestra una técnica que permite externalizar las series que aparecen en la UI. Las series externalizadas sirven para simplificar la traducción de la UI del conector a otros idiomas. Podemos externalizar las series de nuestros archivos plugin.xml sustituyendo cada serie por una clave (por ejemplo, %help, %helpcontents) y creando en el archivo plugin.properties entradas con este formato:
help = "Ayuda" helpContents = "Contenido de la ayuda"
El archivo plugin.properties se puede traducir a los distintos idiomas y no será necesario modificar el archivo plugin.xml.
En la mayoría de los ejemplos que hemos visto hasta ahora, las acciones con las que los conectores de ejemplo han contribuido se han añadido a los grupos con nombre existentes en los menús.
Los puntos de extensión actionSets, viewActions, editorActions y popupMenus también le permiten definir menús y grupos nuevos en sus contribuciones. Esto significa que puede definir submenús o menús desplegables nuevos y contribuir suministrando acciones a dichos menús. En este caso, la vía de acceso de la acción nueva contendrá el nombre del menú definido recientemente.
Vimos cómo se aplicaba esta técnica cuando la herramienta readme definió un menú nuevo para su conjunto de acciones. Ahora que hemos explicado las vías de acceso de menú de manera más detallada, examinemos los códigos XML una vez más.
<extension point = "org.eclipse.ui.actionSets"> <actionSet id="org_eclipse_ui_examples_readmetool_actionSet" label="%ActionSet.name" visible="true"> <menu id="org_eclipse_ui_examples_readmetool" label="%ActionSet.menu" 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="%ReadmeAction.label" tooltip="%ReadmeAction.tooltip" helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context" icon="icons/ctool16/openbrwsr.gif" class="org.eclipse.ui.examples.readmetool.WindowActionDelegate" enablesFor="1"> <selection class="org.eclipse.core.resources.IFile" name="*.readme"> </selection> </action> ...
Hemos añadido un menú nuevo, llamado "org_eclipse_ui_examples_readmetool", cuya etiqueta está definida por la clave "%ActionSet.name" en el archivo de propiedades. Dentro de este menú, definimos tres grupos con nombre: "slot1", "slot2" y "slot3". Añadimos este menú nuevo a la vía de acceso "window/additions".
Si regresamos a IWorkbenchActionConstants, vemos la siguiente definición del menú de ventana en el javadoc:
* <h3>Acciones del menú Ventana estándar</h3> * <ul> * <li>Grupo de acciones adicionales al estilo de Ventana (<code>WINDOW_EXT</code>)</li>
Si seguimos mirando la definición de clase, veremos 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"; // Grupo. ... public static final String WINDOW_EXT = MB_ADDITIONS; // Grupo.
A partir de esta información, podemos componer la vía de acceso para añadir algún elemento al menú "Ventana" del entorno de trabajo. El propio menú se llama "window" y define una ranura llamada "additions". Para añadir el menú nuevo, utilizaremos la vía de acceso "window/additions".
En la declaración del conjunto de acciones, añadimos una acción al menú recién definido utilizando la vía de acceso "window/org_eclipse_ui_examples_readmetool/slot1".
Otros conectores podrían añadir uno de sus propios menús al nuestro utilizando esta misma vía de acceso (o tal vez una de las ranuras restantes).
En el ejemplo de la herramienta readme, hemos utilizado el atributo separator para identificar los nombres de grupo. Esto provocará la aparición de una línea de separación entre estos grupos cuando contengan elementos. En lugar de ello, podríamos utilizar el atributo groupMarker si deseamos definir un grupo con nombre sin mostrar separadores en el menú para distinguir los grupos.
Las vías de acceso de barra de herramientas funcionan de forma parecida a las vías de acceso de menú.
La barra de herramientas del entorno de trabajo se compone de barras de herramientas aportadas por diversos conectores, incluido el propio entorno de trabajo. Dentro de una barra de herramientas determinada, existen grupos con nombre o ranuras que pueden utilizarse para insertar nuevos elementos de barra de herramientas.
La siguiente descripción del menú de las barras de herramientas del entorno de trabajo se ha adaptado de la definición de la clase IWorkbenchActionConstants.
// Los ID de barra de herramientas del entorno de trabajo public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file" public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; // Los ID de grupos de barra de herramientas del entorno de trabajo. Para añadir // un elemento al principio del grupo, // utilice el ID de GRUPO. Para añadir un elemento al final del grupo, use el ID EXT. public static final String PIN_GROUP = "pin.group"; public static final String HISTORY_GROUP = "history.group"; public static final String NEW_GROUP = "new.group"; public static final String SAVE_GROUP = "save.group"; public static final String BUILD_GROUP = "build.group";
En el caso más simple, un conector puede añadir un elemento de barra de herramientas a su propia barra de herramientas. Por ejemplo, las acciones de la herramienta readme añadidas al menú también reciben una vía de acceso de barra de herramientas:
... <action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="readme" ...
Puesto que no existe ninguna referencia a las vías de acceso o grupos de barra de herramientas del entorno de trabajo, las acciones de readme aparecen en su propio grupo de la barra de herramientas. Si en lugar de ello se especifica la siguiente vía de acceso, el elemento se colocará en la barra de herramientas de archivo del grupo de guardar:
... <action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="org.eclipse.ui.workbench.file/save.group" ...
En las vías de acceso de barra de herramientas de otros conectores puede hacerse referencia a las vías de acceso definidas en IWorkbenchActionConstants.
Supongamos que un conector desea que sus elementos de barra de herramientas estén mejor integrados en las acciones de otro conector. Observemos la forma en que el conector de las herramientas externas (org.eclipse.ui.externaltools) integra su acción en la barra de herramientas del depurador. El depurador (org.eclipse.debug.ui) define sus acciones de barra de herramientas de la forma siguiente:
<extension point="org.eclipse.ui.actionSets"> <actionSet label="%LaunchActionSet.label" visible="false" id="org.eclipse.debug.ui.launchActionSet"> ... <action toolbarPath="debug" id="org.eclipse.debug.internal.ui.actions.RunDropDownAction" hoverIcon="icons/full/ctool16/run_exc.gif" class="org.eclipse.debug.internal.ui.actions.RunToolbarAction" disabledIcon="icons/full/dtool16/run_exc.gif" icon="icons/full/etool16/run_exc.gif" helpContextId="run_action_context" label="%RunDropDownAction.label" pulldown="true"> </action> ...
Al igual que la herramienta readme, el conector del depurador define su propia vía de acceso de barra de herramientas, lo que implica que sus elementos de barra de herramientas se encontrarán dentro de su propia barra de herramientas en el entorno de trabajo. ¿Qué hace el conector de las herramientas externas?
<extension point="org.eclipse.ui.actionSets"> <actionSet id="org.eclipse.ui.externaltools.ExternalToolsSet" label="%ActionSet.externalTools" visible="true"> ... <action id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar" definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar" label="%Action.externalTools" toolbarPath="org.eclipse.debug.ui.launchActionSet/debug" disabledIcon="icons/full/dtool16/external_tools.gif" icon="icons/full/etool16/external_tools.gif" hoverIcon="icons/full/ctool16/external_tools.gif" tooltip="%Action.externalToolsTip" pulldown="true" class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate"> </action> </actionSet> </extension>
Observe la utilización del ID de conjunto de acciones del depurador en la vía de acceso de barra de herramientas. La utilización de un ID de conjunto de acciones en la vía de acceso indica que el elemento de barra de herramientas debe colocarse en la barra de herramientas utilizada por el conjunto de acciones al que se hace referencia. Dentro de un grupo de barra de herramientas, los elementos se ordenan según su ID de conjunto de acciones; por tanto, en el ejemplo, la acción de las herramientas externas aparecerá después de las acciones del depurador.
Al efectuar adiciones a la barra de herramientas de un conjunto de acciones, también pueden definirse grupos nuevos. Si el conector de las herramientas externas ha definido su toolbarpath como "org.eclipse.debug.ui.launchActionSet/external", se creará un grupo nuevo para la acción en la barra de herramientas. Al igual que los menús, los grupos de barra de herramientas están delimitados por separadores.
En general, no es una buena praxis efectuar contribuciones al menú o barra de herramientas de otro conector derivando el nombre de vía de acceso del archivo plugin.xml, a menos que se haya marcado específicamente como disponible para los clientes. Es posible que una versión futura del conector pueda cambiar los nombres de las vías de acceso. Dos formas habituales de marcar como disponibles los ID y vías de acceso de los conjuntos de acciones del conector son: