Menu, barre degli strumenti e azioni dell'editor
Identificativo: org.eclipse.ui.editorActions
Descrizione: questo punto di estensione consente di aggiungere azioni al menu e alla barra degli strumenti degli editor registrati da altri plug-in.
La serie iniziale di contributi di un editor è definita da un altro punto di estensione (org.eclipse.ui.editors).
Un'unica serie di azioni viene creata e condivisa da tutte le istanze dello stesso tipo di editor. Quando vengono richiamate, queste azioni agiscono sull'editor attivo.
Questo punto di estensione segue lo stesso modello. Ciascuna estensione dell'azione viene creata e condivisa da tutte le istanze dello stesso tipo di editor. È necessaria la classe di azione che implementa org.eclipse.ui.IEditorActionDelegate.
L'editor attivo è trasferito al delegato richiamando IEditorActionDelegate#setActiveEditor.
Tag di configurazione:
<!ELEMENT editorContribution (menu | action)*>
<!ATTLIST editorContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - un identificativo univoco che può essere utilizzato per fare riferimento a questo contributo
editorID - un identificativo univoco di un editor registrato in precedenza che costituisce la destinazione di questo contributo.
<!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 del nuovo menu. L'etichetta può contenere informazioni di scelta rapida.
-
path - il percorso del menu a partire dalla directory principale della barra dei menu. Se omesso, il menu viene aggiunto alle aggiunte di slot sulla barra dei menu. Ciascun token del percorso deve fare riferimento a un menu presente nel workbench, eccetto l'ultimo che rappresenta 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.
<!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, 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 e 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. Il percorso può riferirsi soltanto a menu dell'editor di destinazione. 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 toolbarPAth è omesso, l'azione non verrà visualizzata.
-
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 - da utilizzare quando si desidera visualizzare l'azione nella barra degli strumenti. In caso contrario, ignorare questo elemento.
-
helpContextId - un identificativo univoco che indica l'id contesto 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, verrà visualizzato come un pulsante di attivazione/disattivazione.
Se definito, il valore dell'attributo verrà utilizzato come stato iniziale (true
o false)
-
class - il nome completo della classe che implementa org.eclipse.ui.IEditorActionDelegate
-
enablesFor - un valore che indica la 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 - 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 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 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 è riportato un esempio di punto di estensione per un'azione di editor:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu id="com.xyz.xyzMenu"
label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
state="true"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ">
</action>
</editorContribution>
</extension>
Nell'esempio sopra riportato, l'azione specificata viene visualizzata come una casella di controllo nel menu e come pulsante di attivazione/disattivazione nella barra degli strumenti.
Informazione API: il valore dell'attributo class deve essere un nome completo di una classe Java che implementi org.eclipse.ui.IEditorActionDelegate.
Questa interfaccia viene caricata per ultima, in modo da evitare il caricamento dell'intero plug-in prima del necessario. Il metodo setActiveEditor
viene richiamato ogni qualvolta è attivato uno specifico tipo di editor.
Per tutte le istanze del tipo di editor specificato viene creata un'unica serie di azioni e di menu, indipendentemente dalla quantità di istanze correntemente aperte nel workbench.
Questo punto di estensione può essere utilizzato per contribuire con azioni ai menu precedentemente creati dall'editor di destinazione. Inoltre, è possibile contribuire con menu e azioni alla finestra del workbench. Gli identificativi delle azioni e i maggiori gruppi all'interno della finestra del workbench vengono definiti in org.eclipse.ui.IWorkbenchActionConstants e devono essere utilizzati come punto di riferimento per l'aggiunta di nuove azioni.
I menu di livello superiore vengono creati utilizzando i seguenti valori per l'attributo path:
-
additions - indica un gruppo posto a sinistra del menu Finestra.
Le azioni e i menu aggiunti in questi percorsi vengono visualizzati soltanto quando l'editor ad essi associato è attivo. Alla chiusura dell'editor, menu e azioni vengono rimossi.
Implementazione fornita: il workbench fornisce un editor di testo predefinito incorporato. I plug-in possono contribuire all'editor predefinito o a editor forniti da altri plug-in.