Serie di azioni
Identificativo: org.eclipse.ui.actionSets
Descrizione: questo punto di estensione viene utilizzato per aggiungere menu, voci di menu e pulsanti della barra degli strumenti alle aree comuni presenti nella finestra del workbench.
Questi contributi sono conosciuti collettivamente come serie di azioni e vengono visualizzati nella finestra del workbench in base alle preferenze dell'utente.
Tag di configurazione:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id - un nome univoco che verrà utilizzato per identificare questa serie di azioni.
-
label - un nome traducibile che verrà utilizzato nel menu della finestra del workbench per rappresentare questa serie di azioni.
-
visible - un attributo facoltativo che indica se la serie di azioni debba essere inizialmente visibile nella finestra del workbench. L'opzione può essere esclusa dall'utente mediante la finestra di dialogo Personalizza prospettiva.
-
description - un elemento secondario facoltativo al cui interno deve essere contenuta una breve descrizione della serie di azioni.
<!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 - un'etichetta di testo per il nuovo menu. L'etichetta può contenere informazioni di scelta rapida.
-
path - un percorso del menu a partire dalla directory principale della barra dei menu. Se omesso, il menu viene aggiunto sulla barra dei menu tra i menu Prospettiva e Finestra. Ciascun token del percorso deve fare riferimento ad un menu esistente nel workbench, eccetto l'ultimo che deve rappresentare un gruppo denominato nell'ultimo menu del percorso.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - un nome del separatore a cui si può in seguito fare riferimento come ultimo token nel percorso dell'azione. Pertanto, i separatori fungono da gruppi denominati in cui è possibile aggiungere azioni e sottomenu.
<!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
pulldown
(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, a seconda del 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 viene adoperato per specificare la posizione dell'azione nella barra del menu. Ciascun token del percorso, eccetto l'ultimo, deve indicare l'ID valido di un menu presente nella gerarchia.
L'ultimo token indica il gruppo del separatore denominato al quale verrà aggiunta l'azione. Se il percorso è omesso, l'azione non verrà visualizzata nella barra del menu.
-
toolbarPath - un percorso delimitato da barre ('/'), che viene adoperato per specificare la posizione dell'azione nella barra degli strumenti. Il primo token indica l'ID della barra degli strumenti (Normale costituisce la barra degli strumenti predefinita), mentre il secondo token rappresenta il gruppo denominato all'interno della barra. Se il gruppo non esiste nella barra degli strumenti, verrà creato. Se il percorso toolbarPath è omesso, l'azione non verrà visualizzata nella barra degli strumenti.
-
icon - un percorso relativo all'icona che verrà utilizzata per indicare in modo visivo l'azione nel relativo contesto. Se è omessa 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.
-
tooltip - un valore del testo descrittivo quando si desidera visualizzare l'azione nella barra degli strumenti. In caso contrario, ignorare questo elemento.
-
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.
-
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 ad una barra degli strumenti, viene visualizzato come un interruttore.
Se definito, il valore dell'attributo verrà utilizzato come stato iniziale (true
o false). Questo attributo si esclude a vicenda con pulldown.
-
pulldown - un attributo opzionale che indica che l'azione dispone di un menu a discesa aggiuntivo. Quando l'azione viene visualizzata nella barra degli strumenti e il valore dell'attributo è true, accanto all'azione viene visualizzato un menu a discesa. Quando l'azione viene visualizzata in un menu, questo attributo è ignorato.
Questo attributo si esclude a vicenda con state.
-
class - un nome completo di una classe che implementa org.eclipse.ui.IWorkbenchWindowActionDelegate
o org.eclipse.ui.IWorkbenchWindowPulldownDelegate. La seconda viene implementata nei casi in cui pulldown sia true.
-
enablesFor - un valore che indica la selezione necessaria 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 - un nome completo della classe o dell'interfaccia che tutti gli oggetti della selezione devono inserire in una classe di livello superiore o implementare per poter abilitare l'azione.
-
name - un filtro con carattere jolly per il nome che può essere aggiunto facoltativamente agli oggetti della selezione. Se questo filtro viene specificato, senza che si verifichi alcuna corrispondenza, l'azione sarà disabilitata.
Si osservi che il workbench non genera menu per conto del plug-in: i percorsi di menu devono fare riferimento a menu già presenti.
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 selezionato nel testo tradotto. 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 di una serie di azioni (si notino i sottoelementi e il modo in cui vengono utilizzati gli attributi):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visible="true">
<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>
</actionSet>
</extension>
Nell'esempio sopra riportato, l'azione specificata, denominata "My Actions", può inizialmente essere visualizzata in ciascuna prospettiva. Viene abilitata per una sola selezione (attributo enablesFor). Inoltre, gli oggetti all'interno della selezione devono implementare l'interfaccia specificata (IFile) e devono essere un file Java.
Informazioni API: il valore dell'attributo class deve costituire il nome completo di una classe che implementa org.eclipse.ui.IWorkbenchWindowActionDelegate
o org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Il secondo viene implementato nei casi in cui pulldown sia true.
Questa classe viene caricata il più tardi possibile per evitare di caricare l'intero plug-in prima che sia realmente necessario.
Implementazione fornita: i plug-in possono utilizzare questo punto di estensione per aggiungere nuovi menu di livello superiore (ad esempio, debug). I plug-in possono anche definire gruppi denominati mediante i quali altri plug-in possono fornire il proprio contributo.
I menu di livello superiore vengono creati utilizzando per l'attributo path i seguenti valori:
-
additions - indica un gruppo posto a sinistra del menu Finestra.
Se l'attributo path viene omesso, il nuovo menu viene aggiunto nel gruppo della barra dei menu additions.
I gruppi predefiniti di una finestra del workbench sono definiti nell'interfaccia IWorkbenchActionConstants. È possibile utilizzare queste costanti in codice per un contributo dinamico.
È anche possibile copiare i valori in un file XML per integrarli in maniera precisa con i menu e la barra degli strumenti presenti sul workbench.
Diversi elementi del menu e della barra degli strumenti presenti nella finestra del workbench sono definiti mediante algoritmi. In questi casi, è necessario utilizzare un meccanismo separato per estendere la finestra. Ad esempio, l'aggiunta di una nuova visualizzazione del workbench determina la visualizzazione di un nuovo elemento nel menu Prospettiva. Anche le estensioni relative a Importazione, Esportazione e Nuove procedure guidate vengono aggiunte automaticamente alla finestra.