Ved hjelp av dette utvidelsespunktet kan plugin-utvikleren definere menyer, skilletegn, logiske grupper og menyelementer, som kan vises hvor som helst i applikasjonen, fra statuslinjer til hurtigmenyer. Det gjør det også mulig å definere sett av slike bidrag (dvs. handlingssett). Disse handlingssettene kan slås på eller av av sluttbrukeren. Kort sagt inneholder menyutvidelsespunktene alt av presentasjonselementer (unntatt ikoner) for å bidra til enhver meny eller kuttingsområde i Eclipse.
Hvert element i dette utvidelsespunktet er gitt en unik ID. Dette er for at det skal være mulig å referere til disse elementene andre steder uten å måtte oppgi elementet på nytt. For eksempel kan IDen være nødvendig for bestilling eller for å definere et handlingssett. Dette gjør det også mulig for utviklere av tredjeparts plugin-moduler å plassere disse elementene på nye steder innen grensesnittet etter behov.
Merk: For 3.2 er den eneste delen av denne utvidelsesmekanismen som er implementert, den delen som er knyttet til 'trim'-bidrag. Forsøk på å legge til elementer, menyer, verktøylinjer eller statuslinjeoppføringer vil fungere som en 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>
Et element (item) kan være et menyelement eller et kuttet element, avhengig av hvor det er plassert. Teksten og bildet som er knyttet til elementet, vil bli tatt fra kommandoen.
org.eclipse.ui
, kalles org.eclipse.ui.item1
.<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
En meny kan bli vist enten koblet til et verktøyelement eller en sted i en visningsmeny, hurtigmeny eller toppnivåmenylinje. Plugin-utvikleren kan anta at det er en meny- og verktøylinke for hver visning, og at toppnivåmenylinjen finnes. Hurtigmenyer må registreres programmatisk før de kan brukes (se API-informasjon).
En meny kan bare inneholde grupper.
org.eclipse.ui
, kalles org.eclipse.ui.menu1
.<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
En logisk gruppering. Den kan være synlig (f.eks. tegnes skilletegn før og etter) eller usynlig. Som standard er logiske grupper synlige.
En gruppe kan inneholde menyer, elementer eller andre grupper.
org.eclipse.ui
, kalles org.eclipse.ui.group1
.<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
Et meny- eller kuttelement som gis direkte tilgang til widgeter. Dette kan for eksempel brukes til å gjengitt en kombinasjonsboks. Dessverre betyr det at hvis et widgetelement blir synlig i brukergrensesnittet, vil det føre til innlasting av plugin-modul. Bruk dette elementet med forsiktighet, ofr det kan gi ytelsesproblemer. Det vil også forårsake problemer for ting som makrostøtte, skripting og det meste annet av kommandobaserte mekanismer. Ved bruk som kutting vil widgeten bare få plugin-modellen til å lastes inn når den blir synlig i brukergrensesnittet.
org.eclipse.ui
, kalles org.eclipse.ui.widget1
.IWorkbenchWidget
. Klienter kan velge å
bruke standardimplementeringen AbstractWorkbenchTrimWidget
. Denne implementeringen
håndterer 'init'-metoden og hurtigbufrer resultatet til bruk gjennom getWorkbenchWindow
-metoden.<!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
Dette elementet kan brukes til å spesifisere forskjellige layoutalternativer for elementer som legges til i trim
-plasseringer.
false
.false
.<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
En plassering der det kan vises en meny
, en gruppe
, et element
eller en widget
. Dette elementet brukes til å styre plasseringsspesifikk informasjon.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
Et bladelement innen en plassering. Dette kan være menylinjen eller kuttingsområdet. Hvis det er ukvalifisert, angir det øverste menylinje eller kutting. Hvis det er kvalifisert en et part
-element, angir det delens meny eller kutting.
menu
eller trim
. Hvis det bidras til menyen, blir dette elementet overordnet en widget-struktur. Generelt betyr det at at bruk av widget-elementer ikke gir særlig mening, og et ikon for et elements kommando er ikke strengt tatt nødvendig. Standardverdien er menu
.
Ved bidrag til kuttingen
vil linjen generelt ikke kreve en kommando eller et ikon. Den bør fylles med en widget som viser kuttingsinformasjon.
Innenfor kuttingen definerer arbeidsbenken fem generelle grupper som tilsvarer forskjellige posisjoner rundt vinduet.
vertical1
.'/'
som skilletegn.<!ATTLIST class
class CDATA #REQUIRED>
Et klasseelement som støtter den utførbare utvidelsen som analyserer syntaksen for både widget
- og dynamic
-elementet.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Kontrollerer synligheten til det gitte elementet.
true
, kan det ikke være underelementer. Dette kontrollerer vare kommandoens aktiverte tilstand, og og gjør tilsvarende element synlig hvis kommandoen er aktivert.<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
Et element innen en plassering. Dette kvalifiserer plasseringen til å referere til en bestemt arbeidsbenkdel. Denne kan være en visning eller et redigeringsprogram. Kvalifikasjonen kan bruke klassenavnet til delen (herunder arv) eller referere til IDen for visningen eller redigeringsprogrammet.
Bare en av id
og class
kan spesifiseres.
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
En parameter til en utførbar utvidelse eller en kommando -- avhengig av hvor den vises i utvidelsen.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Kontrollerer posisjonen til en meny, en gruppe, et element eller en widget innen en plassering.
Dette attributtet godtar følgende verdier: start
(sett elementet først i containeren), end
(sett elementet sist i containeren), after
(sett elementet etter det sideordnede elementet med ID som samsvarer med ref
) og before
(sett elementet før det sideordnede elementet med ID som samsvarer med ref
). Relativ sortering kan brukes på enhver type menyelement.
Ved konflikter velger Eclipse en vilkårlig rekkefølge. Dette sikrer bare at rekkefølgen i tilfelle av en konflikt forblir den samme så lenge følgende er sant:
position
er before
eller after
.<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Deler av en plassering. Den viser at menyen, gruppen, elementet eller widgeten skal vises i hurtigmenyen.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Et generisk rotelement. Elementet kan brukes i et utvidelsespunkt til å definere aktiveringsuttrykket. Underordnede under et aktiveringsuttrykk kombineres med operatoren AND.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Dette elementet representerer en NOT-operasjon på resultatet av evalueringen av underelementuttrykket.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Dette elementet representerer en AND-operasjon på resultatet av evalueringen av alle dets underelementuttrykk.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Dette elementet representerer en OR-operasjon på resultatet av evalueringen av alle tilhørende underelementuttrykk.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Dette elementet brukes til å utføre en instanceof-kontroll av objektet i fokus. Uttrykket returnerer EvaluationResult.TRUE hvis objektets type er en subtype under typen som er spesifisert ved attributtverdien. Ellers returneres EvaluationResult.FALSE.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Dette elementet brukes til å evaluere egenskapstilstanden til objektet i fokus. Settet med prøvbare egenskaper kan utvides ved hjelp av utvidelsespunktet for egenskapstesting. Testuttrykket returnerer EvaluationResult.NOT_LOADED hvis egenskapstesteren som utfører den faktiske testingen, ennå ikke er lastet inn.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Tester en systemegenskap ved å kalle opp metoden System.getProperty, og sammenlikner resultatet med verdien spesifisert gjennom value-attributtet.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Dette elementet brukes til å utføre en equals-kontroll av objektet i fokus. Uttrykket returnerer EvaluationResult.TRUE hvis objektet er lik verdien som er oppgitt av value-attributtet. Ellers returneres EvaluationResult.FALSE.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Dette elementet brukes til å teste antallet elementer i en samling.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
Dette elementet endrer objektet som skal inspiseres, for alle underordnede elementer under objektet som refereres med den gitte variabelen. Hvis variabelen ikke kan behandles, vil uttrykket kaste et ExpressionException ved evaluering. Underordnede under et with-uttrykk kombineres ved hjelp av operatoren AND.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
Dette elementet endrer objektet som skal inspiseres, for alle underordnede elementer under objektet som refereres med den gitte variabelen. Hvis variabelen ikke kan behandles, vil uttrykket kaste et ExpressionException ved evaluering. Underordnede under et with-uttrykk kombineres ved hjelp av operatoren AND.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Dette elementet brukes til å tilpasse objektet i fokus til typen spesifisert ved attributtypen. Uttrykket returnerer ikke innlastet hvis adapteren eller typen det refereres til, ennå ikke er lastet inn. Det kaster et ExpressionException under evaluering hvis typenavnet ikke finnes i det hele tatt. Underordnede til et adapt-uttrykk kombineres ved hjelp av operatoren AND.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Dette elementet brukes til å gjenta en variabel som er av typen java.util.Collection. Hvis objektet i fokus ikke er av typen java.util.Collection, kastes et ExpressionException ved evaluering av uttrykket.
En grunnleggende menydefinisjon ser slik ut:
<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>
I dette eksempelet bidrar plugin-modulutvikleren til alle deler som subklassifiserer eller implementerer den gitte typen. Dette gjør det for eksempel mulig å legge til enkelte bidrag til alle tekstredigeringsprogrammer.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Text Commands"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
Det er mulig å knytte hjelp til en meny.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Run With Configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
Innen en meny er det mulig å definere logiske grupper. Disse logiske gruppene kan være synlige (f.eks. skilletegn før og etter, etter behov) eller usynlige. Som standard er logiske grupper synlige.
<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>
Det er mulig å plassere menyer, grupper og widgets på flere steder.
<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>
Hvis hurtigelementet er spesifisert uten ID og under overordnet delelement, gjelder det for enhver hurtigmeny som er registrert på arbeidsbenken. Dette likner på virkemåten til de gamle objektbidragene. Likeledes vil et hurtigelement på toppnivået påvirke enhver hurtigmeny som er registrert med det gitte navnet.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Noen ganger kan du ønske å kontrollere synligheten til et element. Selv om det normalt er å foretrekke at stabiliteten i layouten i menyer og verktøylinjer opprettholdes, er det noen ganger ønskelig å skjule elementer som ikke er umiddelbart relevante. Dette er særlig tilfellet i hurtigmenyer, der plassen er begrenset. I et slikt tilfelle definerer du et visibleWhen
-element. Dette elementet er nesten identisk med elementene activeWhen
og enabledWhen
, som er definert i utvidelsespunktet 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>
Det vanligste er bare å lage noe synlig når behandleren aktiveres. Dette håndteres med syntaktisk sukker. Det er et checkEnabled
-attributt på visibleWhen
-elementet.
<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>
Ethvert element som er knyttet til en kommando, kan ha parameterverdier. Hvis parameteren til den gitte IDen ikke er definert, er dette en feil. Hvis elementet ikke har en kommando, er dette også en feil.
<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>
Det er også mulig å oppgi relativ rekkefølge. Dette gjøres ved hjelp av order-attributtet på location-elementet. Order-attributtet godtar følgende verdier: start
(sett elementet først i containeren), end
(sett elementet sist i containeren), after
(sett elementet etter det sideordnede elementet med ID som samsvarer med ref
) og before
(sett elementet før det sideordnede elementet med ID som samsvarer med ref
). Relativ sortering kan brukes på enhver type menyelement.
<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>
Hvis du trenger direkte tilgang til widgets (f.eks. for å gjengi en kombinasjonsboks), kan du bruke et widget
-element. Dessverre betyr det at hvis et widgetelement blir synlig i brukergrensesnittet, vil det føre til innlasting av plugin-modul.
<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>
Du kan også bruke widgets for å bidra til arbeidsbenkens kutting. Eksempelet nedenfor definerer en ny "HeapStatus"-widget som som standard plasseres umiddelbart etter linjekuttingen (dvs. nederst i arbeidsbenkvinduet). Se beskrivelsen for "bar"-elementet hvis du vil ha flere opplysninger om de forhåndsdefinerte gruppene.
Merk av kuttingsgrupper kan omplasseres til andre kuttingsområder. Plasseringsinformasjonens relativeTo
vil anta at gruppen som refereres, er i standardposisjonen når den bestemmer den nye kuttings plassering. Generelt forventes det at bidragsytere av denne typen oppretter sin egen gruppe som vert til den nye widgeten, slik at kuttingselementet kan omplasseres uavhengig av de andre kuttingselementene. Et viktig unntak fra dette er "status"-gruppen.
<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
-metoder.
Copyright (c) 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html