Menuer

org.eclipse.ui.menus

3.2

Dette udvidelsespunkt tillader plugin-udviklere at definere menuer, separatorer, logiske grupper og menupunkter, der vises over alt i programmet fra statuslinjer til kontekstmenuer. Det tillader også sæt af sådanne leveringer at blive defineret, f.eks. funktionssæt. Funktionssættene kan aktiveres eller deaktiveres af slutbrugeren. Kort sagt indeholder menuudvidelsespunktet alle præsentationselementer undtagen ikoner til alle menuer eller trimområder i Eclipse.

Ethvert element i dette udvidelsespunkt har en entydig id. Der kan henvises til disse elementer til et andet sted uden at erklære elementet igen. F.eks. kan id'en være påkrævet til sortering eller til at definere et funktionssæt. Det tillader også tredjeparts plugin-udviklere at placere disse elementer på nye placeringer i grænsefladen.

Bemærk: For 3.2 er den eneste del af denne udvidelsesmekanisme, der er implementeret, den del, der er knyttet til trim-leveringer. Forsøg på at tilføje indgange for elementer, menuer, værktøjslinjer eller statuslinjeindgange fungerer som INGEN OP.

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

navn  CDATA #IMPLIED>


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

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

Et element kan være et menu- eller trim-element, der afhænger af, hvor det er placeret. Teksten og billedet, der er knyttet til element, hentes fra kommandoen.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

En menu kan vises tilknyttet et værktøjselement eller i en oversigtsmenu, kontekstmenu eller på øverste niveau i en menulinje. Plugin-udvikleren kan frit antage, at der er en menu eller værktøjslinje for hver oversigt, og at menulinjen på øverste niveau findes. Kontekstmenuer skal registreres via programmering, før de kan anvendes. Se API-oplysninger.

En menu kan kun indeholde grupper.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

En logisk gruppe. Den kan enten være synlig - f.eks. kan skilletegn hentes før og efter, som det passer - eller usynlige. Som standard er logiske grupper usynlige.

En gruppe kan indeholde menuer, elementer og andre grupper.



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

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

En menu eller et trim-element giver direkte adgang til widgets. Dette kan anvendes til at give adgang til en kombinationsboks. Desværre betyder dette, at hvis et widget-element bliver synligt i brugergrænsefladen, medfører det plugin-indlæsning. Brug elementet med forsigtighed, da det kan medføre problemer med ydeevnen. Det kan også medføre problemer for f.eks. makrounderstøttelse, scripts og en del andre kommandobaserede mekanismer. Når widgets anvendes som trim, forårsager de kun plugin-indlæsning, når de bliver synlige i UI.



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Dette element kan anvendes til at angive forskellige layoutindstillinger for elementer, der føjes til placeringer i trim.



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

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

En placering i en menu, gruppe, element eller widget kan forekomme. Elementet kan anvendes til at kontrollere placeringsspecifikke oplysninger.



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

Et bladelement på en placering. Det kan være en menulinje eller et trim-område. Hvis det ikke er kvalificeret, angiver det det øverste niveau på menuen eller trim'et. Hvis det er kvalificeret med et delelement, angiver det delens menu eller trim.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Et klasseelement, der understøtter den eksekvérbare udvidelses analysesyntaks for elementer af typen widget og dynamic.



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

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Styrer synligheden af det givne element.



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

Et element inden for placeringen. Dette kvalificerer placeringen til at henvise til en bestemt del af arbejdsbænken. Det kan enten være en oversigt eller en editor. Kvalifikationen kan anvende klassenavnet på delen (herunder overtagelsen), eller den kan henvise til id'en på oversigten eller editoren.

Der kan kun angives en id og class.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

En parameter for den eksekvérbare udvidelse eller en kommando - afhængig af, om den vises i udvidelsen.



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

Styrer placeringen af en menu, gruppe, et element eller en widget inden for en bestemt position.



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

Del af en placering. Det angiver, at menuen, gruppen, elementet eller widget'en skal vises på en pop op-menu.



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

Et generisk rodelement. Elementet kan anvendes i et udvidelsespunkt for at angive dets aktiveringsudtryk. Underordnede til et aktiveringsudtryk kombineres vha. en operator.



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

Dette element repræsenterer en NOT-funktion på resultatet af evalueringen af dets underelementudtryk.



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

Dette element repræsenterer en AND-funktion på resultatet af evalueringen af dets underelementudtryk.



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

Dette element repræsenterer en OR-funktion på resultatet af evalueringen af alle dets underelementudtryk.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Dette element anvendes til at udføre et instanceof-check af objektet i fokus. Udtrykket returnerer EvaluationResult.TRUE, hvis objektets type er en undertype der er angivet af attributværdien. Ellers returneres EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Dette element anvendes til evaluere egenskabstilstanden for objektet i fokus. Sættet af egenskaber, der kan testes, kan udvides vha. udvidelsespunktet egenskabstester. Testudtrykket returnerer EvaluationResult.NOT_LOADED, hvis egenskabstester, der udfører den aktuelle test, ikke er indlæst endnu.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Tester en systemegenskab ved at kalde metoden System.getProperty og sammenligner resultatet med den værdi, der er angivet via værdiattributten.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Dette element anvendes til at udføre en sammenligningskontrol af objektet i fokus. Udtrykket returnerer EvaluationResult.TRUE, hvis objektet er lig med værdiudbyderen for attributværdien. Eller returneres EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Dette element anvendes til at teste antallet af elementer i en samling.



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

<!ATTLIST with

variable CDATA #REQUIRED>

Dette element ændrer det objekt, der skal undersøges for alle underordnede elementer, til et objekt, der henvises til fra en given variabel. Hvis variablen ikke kan opløses, vil udtrykket sende en ExpressionException, når den evalueres. En underordnet med et with-udtryk kombineres ved at bruge 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 element ændrer det objekt, der skal undersøges for alle underordnede elementer, til et objekt, der henvises til fra en given variabel. Hvis variablen ikke kan opløses, vil udtrykket sende en ExpressionException, når den evalueres. En underordnet med et with-udtryk kombineres ved at bruge operatoren and.



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

<!ATTLIST adapt

type CDATA #REQUIRED>

Dette element anvendes til at tilpasse objekter i fokus til den type, der er angivet af attributtypen. Udtrykket returnerer ikke indlæst, hvis adapteren eller den type, der henvises til, ikke er indlæst endnu. Det sender en ExpressionException under evalueringen, hvis typenavnet slet ikke findes. Underordnede til et tilpasset udtryk kombineres vha. operatoren AND.



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

<!ATTLIST iterate

operator (or|and) >

Dette element anvendes til gentagelser for en variabel, der har typen java.util.Collection. Hvis objektet i fokus ikke er af typen java.util.Collection, sendes der en ExpressionException, når udtrykket evalueres.



En grundlæggende menudefinition ser sådan ud:

< menu id=

"com.mitfirma.minplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

I dette eksempel leverer pluginudvikleren til alle dele, der underklasserer eller implementerer den givne type. Det tillader f.eks. at nogle bidrag tilføjes til alle teksteditorer.

< menu id=

"com.mitfirma.minplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

Det er muligt at knytte hjælp til en menu.

< menu id=

"com.mitfirma.minplugin.RunWithConfigurationAction"

label=

"Udfør med konfiguration"

helpContextId=

"kontekst_til_udfør_med_konfiguration"

>

<location>

<bar />

</location>

</menu>

I en menu er det muligt at definere logiske grupper. Disse logiske grupper kan være synlige, dvs. at skilletegn tegnes før og efter, som det er relevant, eller usynlige. Som standard er logiske grupper synlige.

<group id=

"com.mitfirma.minplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mitfirma.minplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

Det er muligt at placere menuer, grupper, elementer og widgets på flere placeringer.

<item id=

"com.mitfirma.minplugin.ToggleStepFilters"

commandId=

"com.mitfirma.minplugin.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 pop op-elementet er angivet uden id og uden overordnet element, anvendes den til enhver kontekstmenu, der er registreret på arbejdsbænken. Det svarer til funktionsmåden for gamle objektbidrag. Tilsvarende vil et pop op-element på øverste niveau med en id påvirke enhver kontekstmenu, der er registreret med et angivet navn.

<item id=

"com.mitfirma.minplugin.ObjectContribution"

commandId=

"com.mitfirma.minplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

Undertiden kan du have behov for at styre synligheden af et element. Mens det normalt er at foretrække at vedligeholde stabiliteten af layoutet for menuer og værktøjslinjer, er det undertiden ønskværdigt at skjule elementer, der ikke umiddelbart er relevante. Det gælder især for kontekstmenuer, hvor pladsen er begrænset. I så fald kan du definere et visibleWhen-element. Dette element er næsten identisk med activeWhen- og enabledWhen-elementer, der er defineret i behandleres udvidelsespunkt.

<item id=

"com.mitfirma.minplugin.ConvertToWatchExpression"

commandId=

"com.mitfirma.minplugin.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 mest almindelige tilfælde er at gøre noget synligt, når dets behandlere er aktiveret. Det håndteres med noget syntetisk sukker. Der er attributten checkEnabled på elementet visibleWhen.

<item id=

"com.mitfirma.minplugin.compareWithPatch"

commandId=

"com.mitfirma.minplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

Alle elementer, der er knyttet til en kommando, kan indeholde parameterværdier. Hvis parameteren på en given id ikke er defineret, er der en fejl. Hvis elementet ikke har en kommando, er der også en fejl.

<item id=

"com.mitfirma.minplugin.RunHistory"

commandId=

"com.mitfirma.minplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"Stikordsregister"

value=

"1"

/>

</item>

Det er også muligt at angive en relativ rækkefølge. Det gøres ved at anvende rækkefølgeattributten på placeringselementet. Denne attribut accepterer følgende værdier: start (lægger elementet i begyndelsen af opbevaringsstedet), end (lægger elementet i slutningen af opbevaringsstedet), after (lægger elementet efter det sideordnede element, hvis id matcher ref), og before (lægger elementet før det sideordnede element, hvis id matcher ref). Relativ rækkefølge kan anvendes på enhver type menuelement.

<item id=

"com.mitfirma.minplugin.MyFirstItem"

commandId=

"com.mitfirma.minplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mitfirma.minplugin.MySecondItem"

commandId=

"com.mitfirma.minplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mitfirma.minplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

Hvis du skal have direkte adgang til widgets, f.eks. for at præsentere en kombinationsboks, kan du anvende elementet widget. Desværre betyder det, at hvis et widget-element bliver synligt i brugergrænsefladen, medfører det indlæsning af plugins.

<widget id=

"com.mitfirma.minplugin.MyComboBoxSimple"

class=

"com.mitfirma.minplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mitfirma.minplugin.MyComboBoxParameterized1"

class=

"com.mitfirma.minplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mitfirma.minplugin.MyComboBoxParameterized2"

>

<class class=

"com.mitfirma.minplugin.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å anvende widgets til leveringer til arbejdsbænkens trim. Følgende eksempel definerer en ny 'HeapStatus'-widget, der som standard skal placeres umiddelbart efter statuslinjetrimningen, dvs. nederst i arbejdsbænkvinduet. Se beskrivelsen af elementet 'bar' for at få flere oplysninger om foruddefinerede grupper.

Bemærk, at trim-'grupper' kan genplaceres i andre trimningsområder. Placeringsoplysningens relativeTo antager, at gruppen, der henvises til, er på standardplaceringen, når den nye trims placering bestemmes. Generelt forventes det, at leverandører af denne type opretter deres egen gruppe for at være vært for den nye widget og tillader, at trim-elementet kan genplaceres uafhængigt af andre trim-elementer. En bemærkelsesværdig undtagelse til dette er gruppen '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>

For at registrere en kontekstmenu skal du bruge metoderneIWorkbenchPartSite.registerContextMenu.