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.
org.eclipse.ui
potrebbe avere nome org.eclipse.ui.item1
.<!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.
org.eclipse.ui
potrebbe avere nome org.eclipse.ui.menu1
.<!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.
org.eclipse.ui
potrebbe avere nome org.eclipse.ui.group1
.<!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.
org.eclipse.ui
potrebbe avere nome org.eclipse.ui.widget1
.IWorkbenchWidget
. I clienti possono decidere di utilizzare l'implementazione predefinita AbstractWorkbenchTrimWidget
. Questa implementazione gestisce il metodo 'init' e rileva il risultato da utilizzare mediante il metodo getWorkbenchWindow
.<!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
.
false
.false
.<!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.
menu
o
trim
. Se il contributo viene aggiunto al menu, l'elemento verrà associato ad una struttura widget. In generale, in questo caso non ha molto senso utilizzare gli elementi e l'icona per il comando di un elemento
non è strettamente necessaria. Il valore predefinito è menu
.
Se contribuisce al trim
, allora la barra non richiederà un comando o un'icona ma dovrà essere completata con un widget che visualizza le informazioni trim.
Nell'area di selezione, il workbench definisce cinque gruppi generici che corrispondono a diverse parti della finestra:
vertical1
nel workbench.'/'
come carattere di separazione.<!ATTLIST class
class CDATA #REQUIRED>
Un elemento classe che supporta la sintassi di analisi estensioni eseguibili sia per gli elementi widget
che dynamic
.
IExecutableExtension
.<!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.
true
, non vi saranno elementi secondari. L'attributo controlla solo se il comando è abilitato e rende l'elemento corrispondente visibile
se il comando è abilitato.<!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.
Questo attributo 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.
In caso di conflitti, Eclipse sceglierà un ordine arbitrario. Come unica garanzia, in caso di conflitti, l'ordine rimarrà lo stesso se:
position
è before
o after
.<!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>
IWorkbenchPartSite.registerContextMenu
.
Copyright (c) 2005 IBM Corporation e altri.
Tutti i diritti riservati. Questo programma e il materiale di accompagnamento sono
disponibili secondo i termini della Eclipse Public License v1.0 che sono distribuiti con il prodotto, e disponibili all'indirizzo
http://www.eclipse.org/legal/epl-v10.html