Menyer

org.eclipse.ui.menus

3.2

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.



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



<!ELEMENT group (location*)>

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



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



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



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



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Et klasseelement som støtter den utførbare utvidelsen som analyserer syntaksen for både widget- og dynamic-elementet.



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



<!ELEMENT part (popup | bar)>

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



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

Du registrerer en hurtigmeny ved hjelp av IWorkbenchPartSite.registerContextMenu-metoder.