Menu, barre degli strumenti e azioni delle visualizzazioni
Identificativo: org.eclipse.ui.viewActions
Descrizione: questo punto di estensione consente di aggiungere azioni al menu e alla barra degli strumenti delle visualizzazioni registrate da altri plug-in. Ogni visualizzazione dispone di un menu a discesa, che viene attivato facendo clic nella zona superiore destra. Altri plug-in possono poi aggiungere sottomenu e azioni a questo menu
o alla barra degli strumenti di una visualizzazione. Chi utilizza una visualizzazione ha la precedenza nella definizione del contenuto di queste aree. Le ulteriori aggiunte dei plug-in costituiscono un elemento opzionale.
Tag di configurazione:
<!ELEMENT viewContribution (menu | action)*>
<!ATTLIST viewContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - un identificativo univoco che può essere utilizzato per fare riferimento a questi elementi
targetID - l'identificativo univoco della visualizzazione (come specificato nel registro) nella quale viene aggiunto l'elemento
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - un identificativo univoco che può essere utilizzato per fare riferimento a questo menu
-
label - l'etichetta di testo per il nuovo menu. L'etichetta può contenere informazioni sulle opzioni di scelta rapida.
-
path - la posizione del menu rispetto agli elementi del menu a discesa, in cui l'ultima posizione rappresenta il gruppo denominato. Se omesso, il menu viene aggiunto come ultima voce del menu a discesa.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - il nome del separatore a cui si può in seguito fare riferimento come ultima posizione nel percorso dell'azione. Pertanto, i separatori fungono da gruppi denominati in cui è possibile aggiungere azioni.
<!ELEMENT action (selection)*>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id - un identificativo univoco che può essere utilizzato per fare riferimento a questa azione.
-
label - un nome traducibile che viene utilizzato in diversi modi, in base al contesto. Nei menu, viene utilizzato come testo del menu. Nelle barre degli strumenti, viene utilizzato come etichetta del pulsante. Tale etichetta può contenere informazioni codificate con Jface ed informazioni di scelta rapida, come mostrato nell'esempio.
-
menubarPath - un percorso delimitato da barre ('/'), che consente di specificare la posizione dell'azione nel menu a discesa. Ciascuna voce del percorso, eccetto la prima, indica un menu presente nella gerarchia. L'ultima voce indica il gruppo del separatore denominato al quale verrà aggiunta l'azione. Se il percorso è omesso, l'azione non verrà visualizzata nel menu a discesa.
-
toolbarPath - un gruppo denominato all'interno della barra degli strumenti della visualizzazione di destinazione. Se il gruppo non esiste, verrà creato. Se omesso, l'azione non verrà visualizzata nella barra degli strumenti locale.
-
icon - un percorso relativo a un'icona che verrà utilizzata per rappresentare in modo visivo l'azione nel relativo contesto. Se il percorso dell'icona viene omesso e l'azione deve essere visualizzata nella barra degli strumenti, il workbench utilizzerà un'icona segnaposto. Il percorso si riferisce alla posizione del file plugin.xml del plug-in che interviene.
-
state - un attributo opzionale che indica che l'azione può essere attivata/disattivata. Se aggiunto a un menu, esso verrà visualizzato come un elemento di selezione. Se aggiunto a una barra degli strumenti, viene visualizzato come un pulsante di attivazione/disattivazione.
Se definito, il valore dell'attributo verrà utilizzato come stato iniziale (true
o false).
-
tooltip - utilizzato se l'azione deve essere visualizzata nella barra degli strumenti locale.
In caso contrario, questo elemento viene ignorato.
-
helpContextId - un identificativo univoco che indica l'ID di contesto della guida per questa azione. Se l'azione viene mostrata come voce di menu, premendo F1 quando questa voce è selezionata, verrà visualizzata la guida relativa a questo ID di contesto.
-
class - nome completo della classe che implementa org.eclipse.ui.IViewActionDelegate.
-
enablesFor - un valore che indica il conteggio di selezione che deve verificarsi per abilitare l'azione. Se questo attributo viene specificato e la condizione si verifica, l'azione viene abilitata. Se la condizione non si verifica, l'azione viene disattivata. Se non viene specificato alcun attributo, l'azione è abilitata per tutti gli elementi selezionati. Sono supportati i seguenti formati di attributi:
! - nessun elemento selezionato
? - nessuno o un solo elemento selezionato
+ - 1 o più elementi selezionati
multiple, 2+ - due o più elementi selezionati
n - un determinato numero di elementi selezionati. Ad esempio: 4.
* - un qualsiasi numero di elementi selezionati
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class - nome completo della classe o dell'interfaccia che ogni oggetto della selezione deve inserire in una classe di livello superiore o implementare per poter abilitare l'azione.
-
name - un filtro con carattere jolly che può essere aggiunto facoltativamente agli oggetti della selezione. Se questo filtro viene specificato, senza che si verifichi alcuna corrispondenza, l'azione sarà disabilitata.
I criteri di abilitazione per l'estensione di un'azione vengono definiti inizialmente da enablesFor
e selection. Tuttavia, dopo aver creato l'istanza di gestione dell'azione, è possibile controllare lo stato di abilitazione dell'azione utilizzando direttamente il relativo metodo selectionChanged.
L'utente può includere nelle etichette delle azioni e dei menu caratteri speciali, che codificano tasti di scelta e tasti di scelta rapida, utilizzando le seguenti regole:
-
I tasti di scelta vengono specificati mediante il carattere e commerciale ('&') davanti al carattere corrispondente a un tasto di scelta nel testo traducibile. Dal momento che il carattere e commerciale non è supportato nelle stringhe XML, utilizzare il carattere &.
-
I tasti di scelta rapida facoltativi vengono specificati alla fine della stringa del nome, utilizzando @
seguito da una serie di modificatori e il carattere di scelta rapida finale (ad esempio, &Save@Ctrl+S). I modificatori possono essere uniti tramite il simbolo '+' come il delimitatore (ad esempio, @Ctrl+Shift+S).
Esempi:
Di seguito viene riportato un esempio dell'estensione azioni di visualizzazione (notare i sottoelementi e il modo in cui vengono utilizzati gli attributi):
<extension point="org.eclipse.ui.viewActions">
<viewContribution
id="com.xyz.xyzViewC1"
targetID="org.eclipse.ui.views.navigator.ResourceNavigator">
<menu id="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1"/>
<selection class="org.eclipse.core.resources.IFile" name="*.java">
</action>
</viewContribution>
</extension>
Nell'esempio sopra riportato, l'azione specificata viene abilitata per una sola selezione (l'attributo enablesFor). Inoltre, ogni oggetto di questa selezione deve implementare l'interfaccia specificata (IFile) e deve essere un file Java. Possono essere specificati più elementi selection, da cui è possibile effettuare la selezione.
Informazione API: il valore dell'attributo class deve essere un nome completo di una classe Java che implementi org.eclipse.ui.IViewActionDelegate.
Questa interfaccia viene caricata per ultima, in modo da evitare il caricamento dell'intero plug-in prima del necessario. Essa estende org.eclipse.ui.IActionDelegate
e aggiunge un metodo supplementare che consente al delegato l'inizializzazione con l'istanza di visualizzazione in cui interviene.
Implementazione fornita: ogni visualizzazione viene normalmente fornita con alcuni elementi standard sul menu a discesa e nella barra degli strumenti locale. Le modifiche dei plug-in vengono aggiunte agli elementi standard.
È consigliabile pubblicare gli identificativi di azione relativi a una visualizzazione in un'interfaccia pubblica. Ad esempio, le azioni e i gruppi principali della finestra del workbench vengono definiti in org.eclipse.ui.IWorkbenchActionConstants.