Menu

org.eclipse.ui.menus

3.2

Questo punto di estensione consente allo sviluppatore di plugin, di definire menu, separatori, gruppi logici e voci di menu in qualsiasi punto dell'applicazione, dalle righe di stato ai menu di scelta rapida. Inoltre consente di impostare la definizione di alcuni contributi (ad esempio, insiemi di azioni); questi insiemi possono essere attivati e disattivati dall'utente finale. In breve, il punto di estensione dei menu conterrà tutti gli elementi della presentazione (eccetto le icone) per contribuire a qualsiasi menu o area selezionata di Eclipse.

Qualsiasi elemento presente in questo punto di estensione, avrà un identificativo univoco. In questo modo questi elementi possono essere utilizzati altrove senza dover reimpostare l'elemento. Ad esempio, l'identificativo potrebbe essere richiesto per ordinare o per definire un insieme di azioni. Inoltre, consente agli sviluppatori di plugin di altri fornitori, di inserire questi elementi in nuovi percorsi dell'interfaccia.

Nota: per la 3.2 l'unica parte di questo meccanismo di estensione che è stata implementata è la parte associata ai contributi 'trim'. Il tentativo di aggiunta di menu, barra degli strumenti o voci di linee di stato funzionerà come NO-OP.

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

Un elemento può essere una voce di menu o un elemento di una selezione, in base all'ubicazione. Il testo e l'immagine associata all'elemento verrà trascinato dal comando.



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

Un menu può essere sia collegato ad un elemento della strumentazione, o in qualsiasi punto di un menu di visualizzazione, un menu di scelta rapida o nella barra di menu superiore. Lo sviluppatore di plugin potrebbe ritenere che vi sia un menu e una barra degli strumenti in qualsiasi vista e che la barra di menu di livello superiore esiste già. I menu di scelta rapida devono essere registrati programmaticamente per poter essere utilizzati (fare riferimento alle informazioni sull'API).

Un menu può contenere solo gruppi.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

Un gruppo logico. Può essere visibile (ad esempio con separatori prima e dopo) o invisibile. Per impostazione predefinita, i gruppi logici sono visibili.

Un gruppo può contenere menu, elementi ed altri gruppi.



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

Un elemento di menu o trim con accesso diretto ai widget. Ad esempio, può essere utilizzato per visualizzare una casella combinata. Sfortunatamente, ciò significa che se un elemento widget diventa visibile nell'interfaccia utente, verrà caricato un plugin. Utilizzare questo elemento con precauzione, in quanto può causare problemi alle prestazioni. Inoltre potrebbero verificarsi problemi per il supporto di macro, script e altri meccanismi basati sui comandi. Se utilizzato come trim il widget causerà il caricamento da parte del plug-in quando diventa visibile nell'interfaccia utente.



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Questo elemento può essere utilizzato per specificare diverse opzioni di layout per gli elementi aggiunti nei percorsi trim.



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

Un percorso in cui possono essere visualizzati menu, group, item o widget. Questo elemento è utilizzato per controllare le informazioni specifiche del percorso.



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

Un elemento secondario in un percorso. Potrebbe essere la barra dei menu o l'area di selezione. Se non qualificato, indica il menu o l'area di selezione superiori. Se qualificato con un elemento part, indica una parte del menu o dell'area di selezione.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Un elemento classe che supporta la sintassi di analisi estensioni eseguibili sia per gli elementi widget che dynamic.



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

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Controlla la visibilità dell'elemento dato.



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

Un elemento in un percorso. Qualifica il percorso per far riferimento ad una determinata parte del workbench. Può essere una vista o un editor. La qualifica può utilizzare il nome classe della parte (inclusa l'eredità) o può fare riferimento all'identificativo della vista o dell'editor.

È possibile specificare solo uno tra id e class.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Un parametro per un'estensione eseguibile o un comando, in base a se viene visualizzato nell'estensione.



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

Controlla la posizione di un menu, gruppo, elemento o widget in un determinato percorso.



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

Parte di un percorso. Indica che il menu, il gruppo, l'elemento o il widget devono apparire nel menu a comparsa.



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

Un elemento principale generico. L'elemento può essere utilizzato in un punto di estensione per definire la relativa espressione di attivazione. Gli elementi secondari di un'espressione di attivazione vengono associati utilizzando 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 relativa espressione dell'elemento secondario.



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

Questo elemento rappresenta un'operazione AND sul risultato della valutazione di tutte le espressioni dei relativi elementi secondari.



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

Questo elemento rappresenta un'operazione OR sul risultato della valutazione di tutte le espressioni dei relativi elementi secondari.



<!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. In caso contrario, viene restituito EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Questo elemento viene utilizzato per valutare lo stato della proprietà dell'oggetto in questione. L'insieme di proprietà verificabili può essere esteso utilizzando il punto di estensione del 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. In caso contrario, 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 per tutti i relativi elementi secondari indicati da una determinata variabile. 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 per tutti i relativi elementi secondari indicati da una determinata variabile. 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 non caricato se l'adattatore o il tipo indicato non è stato ancora caricato. 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 è riportata la definizione di un menu di base.

Menu < id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

In questo esempio, lo sviluppatore di plugin, contribuisce a tutte le parti con sottoclassi o implementazioni del tipo dato. In tal modo, ad esempio, è possibile aggiungere alcuni contributi a tutti gli editor di testo.

Menu < id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

È possibile associare la guida a un menu.

Menu < id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

In un menu, è possibile definire gruppi logici. Questi gruppi logici possono essere visibili (ad esempio, vengono inseriti separatori prima e dopo) o invisibili. Per impostazione predefinita, i gruppi logici sono visibili.

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

È possibile inserire menu, gruppi, elementi e widget in più percorsi.

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

Se l'elemento a comparsa viene specificato senza ID e senza elemento parte principale, verrà applicato a qualsiasi menu di scelta rapida registrato nel workbench. Questa condizione è simile al comportamento dei vecchi contributi degli oggetti. Allo stesso modo, un elemento a comparsa di livello superiore, con un ID, influenzerà tutti i menu di scelta rapida registrati con tale nome.

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

È possibile controllare la visibilità degli elementi. Se normalmente è preferibile mantenere una certa stabilità nel layout di menu e barre degli strumenti, a volte è preferibile nascondere gli elementi che non sono immediatamente rilevanti. Questa situazione si verifica soprattutto nei menu di scelta rapida, dove lo spazio è limitato. In questo caso, definire un elemento visibleWhen. Questo elemento è quasi identico agli elementi activeWhen e enabledWhen definiti nel punto di estensione handlers.

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

Il caso più comune consiste nel rendere un elemento visibile quando il gestore è abilitato. Questa situazione viene gestita con elementi di sintassi. L'elemento visibleWhen contiene l'attributo checkEnabled.

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

Qualsiasi elemento associato ad un comando può includere valori di parametri. Se il parametro dell'identificativo dato non è definito, verrà prodotto un errore. Se l'elemento non ha un comando, anche in questo caso verrà prodotto un errore.

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

È anche possibile specificare l'ordinamento relativo. A tale scopo è necessario utilizzare l'attributo order sull'elemento di percorso. L'attributo order accetta i seguenti valori: start (inserisce l'elemento all'inizio del contenitore); end (inserisce l'elemento alla fine del contenitore); after (inserisce l'elemento dopo l'elemento di pari livello il cui ID corrisponde a ref); e before (inserisce l'elemento prima dell'elemento di pari livello il cui ID corrisponde a ref). L'ordinamento relativo può essere applicato a qualsiasi tipo di elemento del menu.

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

Se si desidera accesso diretto ai widget (ad esempio, per la visualizzazione di una casella combinata), è possibile utilizzare l'elemento widget. Sfortunatamente, ciò significa che se un elemento widget diventa visibile nell'interfaccia utente, verrà caricato un plugin.

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

È anche possibile utilizzare i widget per aggiungere contributi all'area del workbench. Il seguente esempio definisce un nuovo widget 'HeapStatus' che dovrebbe essere inserito, per impostazione predefinita, subito dopo la riga di stato (nella parte inferiore della finestra del workbench). Per ulteriori informazioni sui gruppi predefiniti, fare riferimento alla descrizione dell'elemento 'bar'.

Osservare che i gruppi delle sezioni possono essere riposizionati in altre aree. Il relativeTo delle informazioni sul percorso presume che il gruppo è indicato come riferimento nel proprio percorso predefinito quando si determina il nuovo percorso dell'area. In generale si presume che i contributor di questo tipo creino il proprio gruppo che conterrà il nuovo widget, consentendo all'elemento trim di essere riposizionato a prescindere dagli altri elementi trim. Un'eccezione importante è rappresentata dal gruppo 'status'.

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

Per registrare un menu di scelta rapida, utilizzare i metodi IWorkbenchPartSite.registerContextMenu.