Percorsi di menu e barre degli strumenti

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.  

Percorsi di menu

Analizzeremo i percorsi di menu prima attraverso il menu Guida.

Gruppi denominati nel workbench

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 nella classe IWorkbenchActionConstants. Per ciascun menu del workbench, i gruppi denominati si trovano nelle posizioni del menu in cui i plug-in 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"
   Informazioni sull'azione - ABOUT - "About"

Il menu standard della guida del workbench è formato da un gruppo denominato "start," seguito da un gruppo denominato "end," che è a sua volta seguito dall'azione "About". La definizione di due gruppi conferisce ai plug-in 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 plug-in maggiore controllo sulla posizione in cui i loro contributi verranno visualizzati rispetto ai contributi già esistenti.

Tuttavia,  nel menu Guida sono presenti anche altre voci  che vengono aggiunte dai plug-in.  Ad esempio, il plug-in della Guida aggiunge al workbench un insieme di azioni che contiene il menu "Argomenti della Guida".  Il tag del file plugin.xml del plug-in org.eclipse.help.ui è il seguente:

<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 nuova azione della Guida sarà posizionata nel menu Guida all'interno del gruppo helpEnd. Se nessun altro plug-in ha contribuito al menu Guida, la voce di menu "Argomenti della Guida" verrà visualizzata come prima voce del menu al di sopra della voce "Informazioni sul prodotto". Se si desidera che un altro plug-in contribuisca con una voce che sia visualizzata sempre al di sopra di "Argomenti della Guida", è necessario che questo plug-in specifichi il gruppo helpStart sul suo percorso.  

Percorsi di menu completi

Un percorso completo di menu è semplicemente "menu name/group name."  I nomi di menu per il workbench vengono definiti in IWorkbenchActionConstants. Questa classe viene utilizzata per scoprire che il nome di percorso completo per l'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."

Esternalizzazione delle etichette di interfaccia utente

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 plug-in in altre lingue.  È possibile esternalizzare le stringhe contenute nei file plugin.xml sostituendo la stringa con una chiave (ad esempio, %help, %helpcontents) e creando nel file plugin.properties voci di questo tipo:

   help = "Guida"
   helpContents = "Argomenti della Guida"

Il file plugin.properties può essere tradotto in altra lingua senza bisogno di modificare il file plugin.xml.

Aggiunta di nuovi menu e gruppi

In molti esempi fin qui illustrati, le azioni fornite dai plug-in 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.gif"
		   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 plug-in 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.

Percorsi di barre degli strumenti

I percorsi di barre degli strumenti operano in modo simile ai percorsi di menu.  

Barre degli strumenti denominate nel workbench

La barra degli strumenti del workbench è composta da barre degli strumenti fornite da diversi plug-in, 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 plug-in 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 plug-in.

Aggiunta di insiemi di azioni di un altro plug-in

Nel caso in cui un plug-in richieda una migliore integrazione delle proprie voci della barra degli strumenti con le azioni di una altro plug-in,  di seguito viene illustrato un esempio di come il plug-in 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.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>
   ...

Come per lo strumento readme, il plug-in 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 plug-in 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.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>

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 plug-in 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. 

Utilizzo di percorsi da un altro plug-in

In generale, nel caso di contributi ad un menu o barra degli strumenti di un altro plug-in, 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 plug-in, i nomi dei percorsi potrebbero risultare modificati.  I metodi più comuni per contrassegnare gli ID dell'insieme di azioni e i percorsi per il plug-in per uso da parte di altri sono:

Copyright IBM Corporation e altri 2000, 2003.