Sono stati illustrati molti contributi di azioni che specificano il percorso per posizionare le rispettive azioni. Il significato di questi percorsi può essere analizzato in dettaglio.
Analizzeremo i percorsi di menu prima attraverso il menu Guida.
Le posizioni per inserire nuovi menu e voci di menu vengono definite mediante gruppi denominati. Un gruppo denominato può essere considerato uno slot o un segnaposto mediante il quale è possibile inserire le voci di menu in punti determinati di una barra di menu o di un menu a discesa.
Il workbench definisce tutti i nomi degli slot di gruppo presenti nelle classiIWorkbenchActionConstants e IIDEActionConstants. (Vengono utilizzate due classi diverse, poiché le voci di menu relative alle risorse sono concesse in factoring al workbench generico). Per ciascun menu del workbench, i gruppi denominati si trovano nelle posizioni del menu in cui i plugin dovranno inserire nuove azioni.
La seguente descrizione del menu Guida è adattata dalla definizione di classe IWorkbenchActionConstants.
Azioni standard del menu Guida Inizio gruppo - HELP_START - "start" Fine gruppo - HELP_END - "end"
Il menu standard della guida del workbench definisce un gruppo denominato "start," seguito da un gruppo denominato "end". La definizione di due gruppi conferisce ai plugin un maggiore controllo sulle posizioni nel menu della guida da assegnare alle voci fornite. Durante la definizione di un menu, è possibile stabilire il numero di slot desiderati. L'aggiunta di più slot fornisce agli altri plugin maggiore controllo sulla posizione in cui i loro contributi verranno visualizzati rispetto ai contributi già esistenti.
I plugin che aggiungono una voce di menu al menu della guida possono utilizzare i nomi dei gruppi per stabilire la posizione della voce di menu. Ad esempio, il plugin della pagina di aiuto aggiunge al workbench un insieme di azioni che contiene il menu "Pagine di aiuto...". Il tag del file plugin.xml del plugin org.eclipse.ui.cheatsheets è il seguente:
<extension point="org.eclipse.ui.actionSets"> <actionSet label="%CHEAT_SHEETS" visible="true" id="org.eclipse.ui.cheatsheets.actionSet"> <action label="%CHEAT_SHEETS_MENU" class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction" menubarPath="help/helpStart" id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction"> </action> </actionSet> </extension>
La nuova azione della Guida sarà posizionata nel menu Guida all'interno del gruppo helpStart.
Un percorso completo di menu è semplicemente "nome menu/nome gruppo." I nomi di menu per il workbench vengono definiti in IWorkbenchActionConstants. (I nomi dei menu relativi alle risorse sono definiti in IIDEActionConstants.) Se si ricerca il nome del menu della guida in questa classe, viene rilevato che il nome percorso completo relativo all'azione della guida è "help/helpEnd."
Alcuni menu sono dotati di sottomenu nidificati, quando coinvolgono percorsi più lunghi. Se il menu Guida ha definito un sottomenu denominato "submenu" contenente un gruppo denominato "submenuStart", il percorso di menu completo per un'azione nel nuovo sottomenu corrisponderà a "help/submenu/submenuStart."
Nell'esempio riportato sopra viene illustrata una tecnica per esternalizzare le stringhe visualizzate nell'interfaccia utente. Le stringhe esternalizzate vengono utilizzate per rendere più semplice la traduzione dell'interfaccia utente del plugin in altre lingue. È possibile esternalizzare le stringhe contenute nei file plugin.xml sostituendo la stringa con una chiave (%CHEAT_SHEETS_MENU) e creando nel file plugin.properties voci di questo tipo:
CHEAT_SHEETS_MENU = Cheat Sheets...
Il file plugin.properties può essere tradotto in altra lingua senza bisogno di modificare il file plugin.xml.
In molti esempi fin qui illustrati, le azioni fornite dai plugin campioni sono state aggiunte a gruppi denominati già presenti nei menu.
I punti di estensione actionSets, viewActions, editorActions, e popupMenus consentono all'utente di definire nuovi menu e gruppi all'interno del contributo. È possibile, cioè, definire nuovi sottomenu o nuovi menu a discesa e fornire loro le azioni. In questo caso, il percorso relativo alla nuova azione conterrà il nome del menu di nuova definizione.
Questa tecnica è stata già mostrata quando lo strumento readme ha definito un nuovo menu per il proprio insieme di azioni. Si osservi nuovamente il tag, adesso che i percorsi di menu sono stati analizzati più dettagliatamente.
<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.png" class="org.eclipse.ui.examples.readmetool.WindowActionDelegate" enablesFor="1"> <selection class="org.eclipse.core.resources.IFile" name="*.readme"> </selection> </action> ...
È stato aggiunto un nuovo menu denominato "org_eclipse_ui_examples_readmetool" la cui etichetta viene definita mediante la chiave "%ActionSet.name" nel file delle proprietà. All'interno di questo menu, sono stati definiti tre gruppi denominati: "slot1," "slot2," e "slot3." Questo nuovo menu deve essere aggiunto al percorso "window/additions."
Se si ritorna a IWorkbenchActionConstants, nel javadoc è visibile la seguente definizione del menu della finestra:
* <h3>Standard Window menu actions</h3> * <ul> * <li>Extra Window-like action group (<code>WINDOW_EXT</code>)</li>
Se si osserva anche la definizione della classe, saranno visibili le seguenti definizioni correlate:
public static final String MENU_PREFIX = ""; ... public static final String M_WINDOW = MENU_PREFIX+"window"; ... public static final String MB_ADDITIONS = "additions"; // Gruppo. ... public static final String WINDOW_EXT = MB_ADDITIONS; // Gruppo.
Questa informazione consente di ricostruire il percorso per aggiungere qualche elemento al menu "Finestra" del workbench. Lo stesso menu è denominato "window" e definisce uno slot denominato "additions." Il nuovo menu viene aggiunto mediante il percorso "window/additions".
Nella dichiarazione dell'insieme di azioni, al menu di nuova definizione viene aggiunta un'azione mediante il percorso "window/org_eclipse_ui_examples_readmetool/slot1."
Altri plugin potrebbero essere aggiunti al menu, utilizzando lo stesso percorso (o magari uno degli altri slot) per aggiungere i relativi menu.
Nell'esempio dello strumento readme, l'attributo separator è stato utilizzato per identificare i nomi di gruppo. In questo caso, viene visualizzata una linea di separazione tra i gruppi se contengono voci. Se invece viene utilizzato l'attributo groupMarker, il gruppo denominato viene definito senza separatori che evidenzino i gruppi nel menu.
I percorsi di barre degli strumenti operano in modo simile ai percorsi di menu.
La barra degli strumenti del workbench è composta da barre degli strumenti fornite da diversi plugin, incluso il workbench stesso. All'interno di una particolare barra degli strumenti sono presenti gruppi denominati o slot che possono essere utilizzati per l'inserimento di nuove voci della barra degli strumenti.
La seguente descrizione delle barre degli strumenti del workbench è adattata dalla definizione di classe IWorkbenchActionConstants.
// Id barra degli strumenti del workbench public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file" public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; // Id barra degli strumenti del workbench. Per aggiungere un elemento all'inizio del gruppo, // utilizzare l'id GROUP. Per aggiungere un elemento alla fine del gruppo utilizzare 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";
Nel caso più semplice, un plugin può fornire una voce alla propria barra degli strumenti. Ad esempio, alle azioni dello strumento readme fornite al menu viene anche assegnato un percorso:
<action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="readme" ...
Dal momento che non ci sono riferimenti a percorsi o gruppi della barra degli strumenti del workbench, le azioni del readme appaiono in un proprio gruppo nella barra degli strumenti. Se invece si specifica il percorso seguente la voce viene collocata nella barra degli strumenti File nel gruppo Salva:
... <action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="org.eclipse.ui.workbench.file/save.group" ...
È possibile fare riferimento ai percorsi definiti in IWorkbenchActionConstants nei percorsi delle barre degli strumenti di altri plugin.
Nel caso in cui un plugin richieda una migliore integrazione delle proprie voci della barra degli strumenti con le azioni di una altro plugin, di seguito viene illustrato un esempio di come il plugin degli strumenti esterni (org.eclipse.ui.externaltools) può integrare le azioni con la barra degli strumenti del debugger. Il debugger (org.eclipse.debug.ui) definisce le azioni della barra degli strumenti nel modo seguente:
<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.png" class="org.eclipse.debug.internal.ui.actions.RunToolbarAction" disabledIcon="icons/full/dtool16/run_exc.png" icon="icons/full/etool16/run_exc.png" helpContextId="run_action_context" label="%RunDropDownAction.label" pulldown="true"> </action> ...
Come per lo strumento readme, il plugin del debugger definisce il percorso della propria barra degli strumenti, ovvero le voci saranno all'interno di una barra degli strumenti separata nel workbench. Pertanto il plugin degli strumenti esterni dovrà effettuare le operazioni riportate di seguito.
<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.png" icon="icons/full/etool16/external_tools.png" hoverIcon="icons/full/ctool16/external_tools.png" tooltip="%Action.externalToolsTip" pulldown="true" class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate"> </action> </actionSet> </extension>
Si noti l'uso dell'ID dell'insieme di azioni del debugger nel percorso della barra degli strumenti. Utilizzando l'ID dell'insieme di azioni nel percorso, la voce sarà collocata nella barra degli strumenti utilizzata dall'insieme di azioni referenziato. All'interno di un gruppo di barra degli strumenti, le voci sono ordinate per ID dell'insieme di azioni, pertanto nel nostro esempio, le azioni degli strumenti esterni saranno visualizzate dopo le azioni del debugger.
Quando si aggiunge una barra degli strumenti dell'insieme di azioni, è anche possibile definire nuovi gruppi. Se il plugin degli strumenti esterni ha definito il proprio toolbarpath come "org.eclipse.debug.ui.launchActionSet/external", nella barra degli strumenti viene creato un nuovo gruppo per l'azione. Come per i menu, i gruppi delle barre degli strumenti sono delimitati da separatori.
In generale, nel caso di contributi ad un menu o barra degli strumenti di un altro plugin, non si consiglia di ricavare il nome del percorso da plugin.xml a meno che non sia stata dichiarato esplicitamente come disponibile per i client. In una futura versione del plugin, i nomi dei percorsi potrebbero risultare modificati. I metodi più comuni per contrassegnare gli ID dell'insieme di azioni e i percorsi per il plugin per uso da parte di altri sono: