Percorsi di menu e barre degli strumenti

Sono stati illustrati molti contributi di azioni che specificano il percorso per la posizione delle rispettive azioni. Il significato di questi percorsi può essere analizzato  mediante un'analisi del menu ? del workbench.

Gruppi denominati

Le posizioni per inserire nuovi menu, voci di menu o della barra degli strumenti vengono definite mediante gruppi denominati. Un gruppo denominato può essere considerato uno slot o un segnaposto che consente di inserire contributi in punti determinati di un menu o di una barra degli strumenti.

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 in cui i plug-in devono inserire nuove azioni.

La seguente descrizione del menu ? è adattata dalla definizione di classe IWorkbenchActionConstants.

   Azioni standard del menu ?
   Start group - HELP_START - "start"
   End group - HELP_END - "end"
   About action - 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.  Quando si definisce 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 ? sono presenti anche altre voci  che vengono aggiunte dai plug-in.  Ad esempio, il plug-in della Guida aggiunge al workbench una serie 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 ? all'interno del gruppo helpEnd. Se nessun altro plug-in ha contribuito al menu ?, 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.  

I percorsi delle barre degli strumenti hanno un identico funzionamento. Il percorso, dovunque sia specificato, deve sempre terminare con il nome di un gruppo nella barra degli strumenti.

Percorsi di menu e barre degli strumenti completi

Un percorso completo di menu o di barra degli strumenti è 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 ? 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.  E 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 = "Help"
   helpContents = "Help Contents"

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 e nelle barre degli strumenti.

I punti di estensione actionSets, viewActions, editorActions, e popupMenus consentono all'utente di definire nuovi menu e gruppi all'interno del contributo. E 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 la propria serie 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>
	   ...

E 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";  // Group.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Group.

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 della serie 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.  

Generalmente, è meglio evitare di contribuire al menu o alla barra degli strumenti di un altro plug-in ricavando il nome del percorso dal file plugin.xml.  In una futura versione del plug-in, i nomi dei percorsi potrebbero risultare modificati.  Si consiglia di definire un'interfaccia pubblica (simile a IWorkbenchActionConstants) che specifica con precisione i menu, i gruppi di barre degli strumenti e gli slot che possono essere utilizzati da altri plug-in.

Copyright
IBM Corp. e altri 2000,2002.