Menu, barre degli strumenti e azioni dell'editor

org.eclipse.ui.editorActions

Questo punto di estensione consente di aggiungere azioni al menu e alla barra degli strumenti degli editor registrati da altri plugin.

L'insieme di contributi iniziali di un editor è definito da un altro punto di estensione (org.eclipse.ui.editors). Un unico insieme di azioni viene creato e condiviso 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.

L'abilitazione e/o la visibilità di una azione possono essere definite utilizzando rispettivamente gli elementi enablement e visibility. Questi due elementi contengono un'espressione booleana valutata per stabilire l'abilitazione e/o la visibilità.

La sintassi per gli elementi enablement e visibility è uguale. Entrambi contengono un elemento secondario con espressione booleana. Nel caso più semplice, sarà un elemento objectClass, objectState, pluginState o systemProperty. Nei casi più complessi, gli elementi and, or e not saranno combinati per creare espressioni booleane. Sia l'elemento and che l'elemento or devono contenere 2 elementi secondari. L'elemento not deve contenere un solo elemento secondario.

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT editorContribution (menu* , action*)>

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Questo elemento è utilizzato per definire un gruppo di azioni e/o menu dell'editor.



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

accelerator   CDATA #IMPLIED

definitionId  CDATA #IMPLIED

menubarPath   CDATA #IMPLIED

toolbarPath   CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      CDATA #IMPLIED>

Questo elemento definisce un'azione che l'utente può richiamare dall'interfaccia utente.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Questo elemento è utilizzato per definire un nuovo menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name  CDATA #REQUIRED>

Questo elemento è utilizzato per creare un separatore di menu nel nuovo menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name  CDATA #REQUIRED>

Questo elemento è utilizzato per creare un gruppo denominato nel nuovo menu. A differenza dell'elemento separator, questo non dispone di una rappresentazione visiva.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Questo elemento è utilizzato nella determinazione dell'abilitazione dell'azione in base alla selezione corrente. Viene ignorato se è specificato l'elemento enablement.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Questo elemento è utilizzato per definire l'abilitazione per l'estensione.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Questo elemento è utilizzato per definire la visibilità per l'estensione.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Questo elemento rappresenta un'operazione booleana AND sul risultato della valutazione delle due espressioni secondarie.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Questo elemento rappresenta un'operazione booleana OR sul risultato della valutazione delle due espressioni secondarie.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Questo elemento rappresenta un'operazione booleana NOT sul risultato della valutazione delle sue espressioni secondarie.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name  CDATA #REQUIRED>

Questo elemento è utilizzato per valutare la classe o l'interfaccia di ciascun oggetto nella selezione corrente. Se ciascun oggetto nella selezione implementa la classe o interfaccia specificata, l'espressione è considerata verificata.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Questo elemento è utilizzato per valutare lo stato dell'attributo di ciascun oggetto nella selezione corrente. Se ciascun oggetto nella selezione presenta lo stato dell'attributo specificato, l'espressione è considerata verificata. Per valutare questo tipo di espressione, tutti gli oggetti della selezione devono implementare o adattarsi all'interfaccia org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Questo elemento è utilizzato per valutare lo stato di un plugin. Lo stato di un plugin può assumere i valori installed (equivalente al concetto OSGi di "resolved") o activated (equivalente al concetto OSGi di "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Questo elemento è utilizzato per valutare lo stato delle proprietà di un sistema. Il valore della proprietà è richiamato da java.lang.System.



Di seguito è riportato un esempio di estensione per un'azione di editor:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"&amp;XYZ Menu"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</editorContribution>

</extension>

Nell'esempio sopra riportato, l'azione specificata viene visualizzata come una casella di controllo nel nuovo menu di livello superiore denominato "XYZ Menu" e come pulsante di attivazione/disattivazione nella barra degli strumenti. Questa azione è abilitata se la selezione contiene solo risorse file Java.

Di seguito è riportato un altro esempio di punto di estensione per un'azione di editor:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"&amp;XYZ2 Menu"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Run XYZ2 Tool"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Run XYZ2 Tool"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</editorContribution>

</extension>

Nell'esempio sopra riportato, l'azione specificata viene visualizzata come una voce di menu nel sottomenu "XYZ2 Menu" del menu di livello principale "Edit". Questa azione è abilitata se la selezione contiene solo risorse file Java.

il valore dell'attributo class deve essere un nome completo di una classe Java che implementi org.eclipse.ui.IEditorActionDelegate. Questa classe viene caricata per ultima, in modo da evitare il caricamento dell'intero plugin 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 creato un unico insieme di azioni e di menu, indipendentemente dal numero 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. Questi devono essere utilizzati come punto di riferimento per l'aggiunta di nuove azioni. I menu di livello superiore vengono creati utilizzando per l'attributo path i seguenti valori:

Se l'attributo path viene omesso, il nuovo menu viene aggiunto nel gruppo della barra dei menu additions.

Le azioni e i menu aggiunti in questi percorsi vengono visualizzati soltanto quando l'editor ad essi associato è attivo. Alla chiusura dell'editor, menu ed azioni vengono rimossi.

I criteri di abilitazione per l'estensione di un'azione sono inizialmente definiti da enablesFor e da uno tra 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.

L'utente può includere nelle etichette delle azioni e dei menu caratteri speciali, che codificano tasti di scelta utilizzando le seguenti regole:

  1. I tasti di scelta vengono specificati mediante il carattere e commerciale ('&') davanti al carattere selezionato nel testo. Dal momento che il carattere e commerciale non è supportato nelle stringhe XML, utilizzare il carattere &amp;.
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 intenzionale. È stato, tuttavia, scoperto dopo che le API della piattaforma Eclipse erano state completate. La modifica del comportamento adesso danneggerebbe tutti i plugin basati sul comportamento esistente.

Gli elementi selection e enablement sono mutualmente esclusivi. L'elemento enablement può sostituire l'elemento selection se si utilizzano gli elementi secondari objectClass e objectState. Ad esempio:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

può essere espresso utilizzando:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Il workbench fornisce un "Editor di testo predefinito" incorporato. I plugin possono contribuire all'editor predefinito o a editor forniti da altri plugin.