Menu di scelta rapida

org.eclipse.ui.popupMenus

Questo punto di estensione viene utilizzato per aggiungere nuove azioni ai menu di scelta rapida gestiti da altri plugin. L'azione potrebbe contribuire a un tipo specifico di oggetto (objectContribution) o a uno specifico menu di scelta rapida di una parte di vista o di editor (viewerContribution). Quando si utilizza objectContribution, il contributo sarà visualizzato in tutti i menu di scelta rapida di parti di viste o di editor in cui sono selezionati oggetti del tipo specificato. Al contrario, utilizzando viewerContribution, il contributo sarà visualizzato solo nel menu di scelta rapida della parte di vista o di editor specificato, a prescindere dalla selezione.

Quando la selezione è eterogenea, il contributo viene applicato se registrato su un tipo comune della selezione. In assenza di una corrispondenza diretta, sarà tentata la corrispondenza a superclassi e superinterfacce.

È possibile limitare ulteriormente la selezione utilizzando il filtro del nome. Quando viene utilizzato un filtro, tutti gli oggetti della selezione devono corrispondere al filtro per poter essere applicati al contributo.

Le singole azioni in un contributo di oggetto possono utilizzare l'attributo enablesFor per specificare se debbano essere applicate soltanto a selezioni singole o multiple, oppure ad altri tipi di selezione.

Se questi meccanismi di filtro dovessero risultare insufficienti, il contributo dell'azione può utilizzare il meccanismo filter. In questo caso gli attributi dell'oggetto di destinazione sono descritti in una serie di coppie di valori nome. Gli attributi che si applicano alla selezione sono di un tipo specifico e diverso rispetto al dominio del workbench, in modo che il filtro a questo livello venga delegato dal workbench alla selezione corrente.

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 (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

Questo elemento è utilizzato per definire un gruppo di azioni e/o menu per i menu di scelta rapida del visualizzatore per il quale sono selezionati gli oggetti del tipo specificato.



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Questo elemento è utilizzato per definire un gruppo di azioni e/o menu per un menu di scelta rapida di parti di viste o di editor.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

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



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Questo elemento è utilizzato per valutare lo stato dell'attributo di ciascun oggetto nella selezione corrente. La corrispondenza viene verificata solo se ciascun oggetto nella selezione presenta lo stato di attributo specificato. Tutti gli oggetti della selezione devono implementare o adattarsi a org.eclipse.ui.IActionFilter.



<!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 due 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 o activated.



<!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.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

un elemento principale generico. Questo elemento può essere utilizzato all'interno di un punto di estensione per definire la sua espressione di attivazione. Gli elementi secondari di una espressione di attivazione sono combinati con l'operatore AND.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

Questo elemento rappresenta un'operazione NOT sul risultato della valutazione della sua espressione secondaria.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

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



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

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



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Questo elemento viene utilizzato per eseguire un controllo instanceof dell'oggetto attivo. L'espressione restituisce EvaluationResult.TRUE se il tipo dell'oggetto è un tipo secondario del tipo specificato dal valore dell'attributo. Altrimenti viene restituito EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Questo elemento viene utilizzato per verificare lo stato delle proprietà dell'oggetto attivo. L'insieme delle proprietà da controllare può essere esteso utilizzando il punto di estensione tester delle proprietà. L'espressione di verifica restituisce EvaluationResult.NOT_LOADED se il tester delle proprietà non è ancora stato caricato.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Verifica una proprietà di sistema richiamando il metodo System.getProperty e confronta il risultato con il valore specificato dall'attributo del valore.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Questo elemento viene utilizzato per eseguire un controllo di eguaglianza dell'oggetto attivo. L'espressione restituisce EvaluationResult.TRUE se l'oggetto è uguale al valore fornito dal valore dell'attributo. Altrimenti viene restituito EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Questo elemento viene utilizzato per verificare il numero di elementi in una raccolta.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

Questo elemento modifica l'oggetto da esaminare con i suoi elementi secondari nell'oggetto referenziato dalla variabile data. Se non è possibile risolvere la variabile, l'espressione genera un ExpressionException durante la valutazione. Gli elementi secondari di una espressione WITH sono combinati con l'operatore AND.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Questo elemento modifica l'oggetto da esaminare con i suoi elementi secondari nell'oggetto referenziato dalla variabile data. Se non è possibile risolvere la variabile, l'espressione genera un ExpressionException durante la valutazione. Gli elementi secondari di una espressione WITH sono combinati con l'operatore AND.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

Questo elemento viene utilizzato per adattare l'oggetto attivo al tipo specificato dal tipo di attributo. L'espressione restituisce NOT LOADED se l'adattatore o il tipo referenziati non sono stati ancora caricati. Viene generata una ExpressionException durante la valutazione se il nome del tipo non esiste. Gli elementi secondari di una espressione di adattamento sono combinati con l'operatore AND.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

Questo elemento viene utilizzato per iterare una variabile di tipo java.util.Collection. Se l'oggetto attivo non è del tipo java.util.Collection viene generata una ExpressionException durante la valutazione dell'espressione.



Di seguito viene riportato un esempio di punto di estensione per un menu di scelta rapida:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

<menu id=

"com.xyz.xyzMenu"

path=

"additions"

label=

"&amp;XYZ Java Tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.XYZToolActionDelegate"

enablesFor=

"1"

>

</action>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Show XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

Nell'esempio sopra riportato, l'azione di contributo dell'oggetto specificata viene abilitata per una sola selezione (l'attributo enablesFor). Inoltre, ogni oggetto della selezione deve implementare l'interfaccia specificata (IFile) e deve essere un file Java. L'azione viene aggiunta a un sottomenu creato in precedenza. Questo contributo sarà valido su tutte le viste caratterizzate dalla selezione richiesta.

Al contrario, il contributo al visualizzatore sopra riportato verrà mostrato soltanto nella vista Attività e non sarà influenzato dalla selezione effettuata nella vista.

Di seguito è riportato un esempio di meccanismo di filtro. In questo caso l'azione sarà visualizzata soltanto per gli IMarkers completi caratterizzati da elevata priorità.

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C3"

objectClass=

"org.eclipse.core.resources.IMarker"

>

<filter name=

"done"

value=

"true"

/>

<filter name=

"priority"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"High Priority Completed Action Tool"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Di seguito è riportato un altro esempio di utilizzo dell'elemento visibility:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<viewerContribution id=

"com.xyz.C4"

targetID=

"org.eclipse.ui.views.TaskList"

>

<visibility>

<and>

<pluginState id=

"com.xyz"

value=

"activated"

/>

<systemProperty name=

"ADVANCED_MODE"

value=

"true"

/>

</and>

</visibility>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Show XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

Nell'esempio sopra riportato, l'azione specificata viene visualizzata come una voce di menu nel menu di scelta rapida della vista Attività, ma solo se il plugin "com.xyz" è attivo e se la proprietà di sistema specificata è impostata a true.

il valore dell'attributo class dell'azione deve essere un nome completo di una classe Java che implementa org.eclipse.ui.IObjectActionDelegate in caso di contributo oggetto, org.eclipse.ui.IViewActionDelegate per contributi a visualizzatori che appartengono a viste, oppure org.eclipse.ui.IEditorActionDelegate per contributi a visualizzatori che appartengono a editor. In tutti i casi, la classe di implementazione viene caricata il più tardi possibile per evitare di caricare l'intero plugin prima che sia effettivamente necessario.

Nota: per garantire la compatibilità con il pregresso, è possibile implementare org.eclipse.ui.IActionDelegate in caso di contributi oggetti.

L'estensione di menu di scelta rapida all'interno di una parte è possibile solo se la parte di destinazione pubblica un menu per estensione. Questa operazione è consigliata in quanto migliora l'estensibilità del prodotto. Per ottenere ciò, ciascuna parte dovrebbe pubblicare tutti i menu di scelta rapida definiti richiamando IWorkbenchPartSite.registerContextMenu. Una volta effettuata questa operazione, il workbench inserirà automaticamente le estensioni di azioni esistenti.

È necessario fornire un id per ciascun menu registrato. Perché vi sia coerenza tra le parti, è necessario che la seguente strategia sia adottata da tutti gli implementatori di parti.

Tutti i menu di scelta rapida che sono registrati con il workbench devono anche contenere un punto di inserimento standard con id IWorkbenchActionConstants.MB_ADDITIONS. Gli altri plugin utilizzeranno questo valore come riferimento per il relativo inserimento. Il punto di inserimento potrebbe essere definito mediante l'aggiunta di GroupMarker al menu in una posizione appropriata per l'inserimento.

Un oggetto del workbench che costituisce la selezione in un menu di scelta rapida può definire un org.eclipse.ui.IActionFilter. Si tratta di una strategia di filtro in base al tipo. Il workbench recupererà il filtro per la selezione verificando che implementi IActionFilter. In caso contrario, il workbench richiederà un filtro attraverso il meccanismo IAdaptable.

Azioni ed etichette possono contenere caratteri speciali che codificano i tasti di scelta i quali 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 &amp;.

Se due o più azioni sono fornite a un menu 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>

Nelle viste del workbench sono incorporati menu di scelta rapida che hanno in dotazione un certo numero di azioni. I plugin possono contribuire a questi menu. Se un visualizzatore è fornito di slot riservati a questi contributi, i nomi degli slot possono essere utilizzati come percorsi al momento della relativa pubblicazione. In caso contrario, le azioni e i sottomenu vengono aggiunti alla fine del menu di scelta rapida.