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 deve essere visibile inizialmente in tutte le prospettive. L'opzione sarà valida soltanto all'apertura di una nuova prospettiva che non è stata personalizzata. L'utente può modificare l'opzione nella 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)+ (groupMarker)*>
<!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 sulle opzioni di scelta rapida.
-
path - un percorso del menu a partire dalla directory principale della barra dei menu. Se omesso, il menu verrà aggiunto alla barra dei menu, prima del menu 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 groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name - un nome dell'indicatore di gruppo a cui si può in seguito fare riferimento come ultimo token nel percorso dell'azione.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
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 e informazioni di scelta rapida, come mostrato nell'esempio.
-
accelerator - un numero intero che viene utilizzato per specificare il codice chiave dell'acceleratore relativo all'azione. Il valore del numero intero deriva dall'operatore OR bit per bit o da più maschere di un modificatore chiave SWT (ad es., SWT.CTRL o SWT.ALT) più un codice del carattere. Ad esempio, per Ctrl+Z utilizzare SWT.CTRL | 'Z' =
(1<<18)|'Z' = 262234.
-
definitionId - id specificato nella definizione dell'azione. E necessario soltanto quando una serie di azioni specifica i tasti di scelta rapida attraverso il servizio dei binding chiave. Consultare
i punti di estensione definizioni delle azioni
e set di tasti di scelta rapida
-
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'ultima voce 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. L'icona sarà visualizzata nelle barre degli strumenti ma non nei menu. Le azioni abilitate saranno presentate nei menu dall'elemento hoverIcon.
-
disabledIcon - il percorso relativo all'icona che verrà utilizzata per indicare in modo visivo l'azione nel relativo contesto quando è disabilitata. Se omessa, l'icona normale verrà semplicemente visualizzata in grigio. Il percorso si riferisce alla posizione del file plugin.xml del plug-in che interviene. L'icona disattivata sarà visualizzata nelle barre degli strumenti ma non nei menu. Le icone relative alle azioni disabilitate nei menu saranno fornite dal sistema operativo.
-
hoverIcon - il percorso relativo all'icona che verrà utilizzata per indicare in modo visivo l'azione nel relativo contesto quando il mouse è posizionato sull'azione.
Se omessa, sarà utilizzata l'icona normale. 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, questo elemento viene ignorato.
-
helpContextId - un identificativo univoco che indica l'ID di contesto della guida per questa azione. Quando l'azione viene visualizzata come una voce del menu, se si preme F1 mentre la voce è evidenziata, è possibile visualizzare la guida per il determinato id 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 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). 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.
Questo attributo non deve essere fornito se l'attributo retarget è true.
-
retarget - se questo attributo è true, sarà creata un'azione di nuova destinazione (globale). Le parti possono fornire un gestore dell'azione globale utilizzando il meccanismo standard per impostare un gestore di azione globale sul proprio sito attraverso l'identificativo dell'azione. Se l'attributo è true, l'attributo class non deve essere fornito.
-
allowLabelUpdates - si applica soltanto se l'attributo retarget è true. Se questo attributo è true, i corrispondenti gestori aggiorneranno l'etichetta e la descrizione comandi dell'azione di nuova destinazione.
-
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 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.
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty | pluginState)*>
<!ATTLIST enablement EMPTY>
In Eclipse 2.0, è possibile utilizzare un elemento enablement per definire l'abilitazione dell'azione. Per ulteriori informazioni sull'utilizzo di un elemento enablement, consultare actionExpressions.html.
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>
<action id="com.xyz.runABC"
label="&Run ABC Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runABC.gif"
tooltip="Run ABC Tool"
helpContextId="com.xyz.run_abc_action_context"
retarget="true"
allowLabelUpdate="true">
</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.
I criteri di abilitazione per l'estensione di un'azione sono inizialmente definiti da enablesFor, selection e enablement. Tuttavia, dopo aver creato l'istanza di gestione dell'azione, è possibile controllare lo stato di abilitazione dell'azione utilizzando direttamente il relativo metodo selectionChanged.
Si osservi che il workbench non genera menu per conto dei plug-in: i percorsi di menu devono fare riferimento a menu già presenti.
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).
Se due o più azioni sono fornite a un menu o una barra degli strumenti mediante una singola estensione, le azioni verranno visualizzate in ordine inverso rispetto a come sono elencate nel file plugin.xml. Questo comportamento non era francamente intenzionale. E stato, tuttavia, scoperto dopo che la versione delle API della piattaforma Eclipse era diventata definitiva. La modifica del comportamento adesso danneggerebbe tutti i plug-in basati sul comportamento esistente.
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. E possibile utilizzare queste costanti in codice per un contributo dinamico.
E 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 Finestra. Anche le estensioni relative a Importazione, Esportazione e Nuove procedure guidate vengono aggiunte automaticamente alla finestra.