Contributi al menu del workbench

Nei capitoli precedenti sono stati analizzati diversi punti di estensione che contribuiscono a vari menu e barre degli strumenti del workbench. Per verificare quale punto di estensione utilizzare, consultare la seguente tabella, dove sono sintetizzati i contributi che possono essere forniti ai vari menu e il relativo utilizzo.

Nome del punto di estensione

Percorso delle azioni

Dettagli

viewActions

Le azioni vengono visualizzate nella barra degli strumenti e nel menu a discesa locali di una specifica visualizzazione.

Fornire una classe di azioni che implementa IViewActionDelegate. Specificare l'ID del contributo e quello della visualizzazione di destinazione dell'azione. L'etichetta e l'immagine sono responsabili dell'aspetto dell'azione nell'interfaccia utente. Il percorso specifica la posizione rispetto alle voci della barra degli strumenti e del menu della visualizzazione.

editorActions

Le azioni sono associate a un editor e vengono visualizzate nel menu e/o nella barra degli strumenti del workbench.

Fornire una classe di azioni che implementa IEditorActionDelegate. Specificare l'ID del contributo e quello dell'editor di destinazione responsabile dell'azione. L'etichetta e l'immagine specificano l'aspetto dell'azione nell'interfaccia utente. Separare i percorsi del menu e della barra degli strumenti che specificano l'esistenza e la posizione del contributo nel menu e nella barra degli strumenti del workbench.

popupMenu

Le azioni vengono visualizzate nel menu di scelta rapida di un editor o di una visualizzazione. Le azioni associate a un tipo di oggetto appaiono in tutti i popup delle visualizzazioni e degli editor in cui viene mostrato il tipo di oggetto. Le azioni associate a un menu specifico di scelta rapida vengono visualizzate soltanto in quel menu.

I contributi dell'oggetto specificano il tipo di oggetto del quale visualizzare l'azione in un menu di scelta rapida. L'azione deve essere mostrata in tutti i menu di scelta rapida delle visualizzazioni e degli editor che contengono il tipo di oggetto.  Fornire una classe di azioni che implementa IObjectActionDelegate
I contributi del visualizzatore specificano l'ID del menu di scelta rapida di destinazione nel quale deve essere visualizzata la voce di menu.  Fornire una classe di azioni che implementa IEditorActionDelegate o IViewActionDelegate

actionSets

Le azioni vengono visualizzate nei menu e nella barra degli strumenti principali del workbench. Le azioni sono raggruppate in serie. Tutte le azioni di una serie vengono mostrate nei menu e nelle barre degli strumenti del workbench a seconda della selezione delle serie di azioni effettuata dall'utente e della prospettiva corrente visualizzata nel workbench.

Fornire una classe di azioni che implementa IWorkbenchWindowActionDelegate o IWorkbenchWindowPulldownDelegate. Specificare il nome e l'ID della serie di azioni. Enumerare tutte le azioni definite per quella serie. Separare per ciascuna azione i percorsi del menu e della barra degli strumenti che specificano l'esistenza e la posizione del contributo nel menu e nella barra degli strumenti del workbench.

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 mediante il quale è possibile 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. I gruppi denominati si trovano in ciascun menu del workbench 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 del workbench è formato da un gruppo denominato "start," seguito da un gruppo denominato "end," che è a sua volta seguito dall'azione "About". I due gruppi permettono di fornire un controllo per i plug-in lungo tutta la loro visualizzazione nel menu ?. 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 ? 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.internal.ui.ShowHelp"/>
    </actionSet>
</extension>

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 di menu o di barra degli strumenti completo non è altro che un elenco di nomi del menu e di coppie di gruppi denominati. I nomi di menu per il workbench sono anche definiti in IWorkbenchActionConstants. 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 sopra illustrato viene mostrata anche una tecnica per esternalizzare le stringhe visualizzate nell'interfaccia utente.  L'esternalizzazione è utile per tradurre l'interfaccia utente del plug-in in altre lingue.  Le stringhe contenute nei file plugin.xml possono essere esternalizzate sostituendo la stringa con una chiave (ad esempio, %help, %helpcontents) e creando voci nel file plugin.properties del form:

help = "Help"
helpContents = "Help Contents"

In questo modo, è possibile tradurre il file plugin.properties in un'altra lingua senza dover 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. È 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="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>

È stato aggiunto un nuovo menu denominato  "org_eclipse_ui_examples_readmetool." La relativa etichetta è la stringa "Readme &File Editor." 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.