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.
org.eclipse.ui
, kaldes org.eclipse.ui.item1
.<!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.
org.eclipse.ui
, kaldes org.eclipse.ui.menu1
.<!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.
org.eclipse.ui
, kaldes org.eclipse.ui.group1
.<!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.
org.eclipse.ui
, kaldes org.eclipse.ui.widget1
.IWorkbenchWidget
. Klienter kan vælge at bruge standardimplementeringen AbstractWorkbenchTrimWidget
. Denne implementering håndterer init-metoden og placerer resultatet i cache til brug for metoden getWorkbenchWindow
. <!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
.
false
.false
.<!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 del
element, angiver det delens menu eller trim.
menu
eller trim
. Hvis der bidrages til menuen, er elementet sideordnet med en widget-struktur. Generelt betyder det, at brug af widget-elementer ikke giver meget mening, og en ikon for elementets kommando er ikke strengt nødvendig. Standardværdien er menu
.
Hvis der leveres til trim
, kræver linjen ikke generelt en kommando eller en ikon, den bør udfyldes med en widget, der viser trim-oplysninger.
I trim definerer arbejdsbænken fem generelle grupper, der svarer til forskellige placeringer rundt omkring i vinduet:
vertical1
.'/'
som skilletegn. <!ATTLIST class
class CDATA #REQUIRED>
Et klasseelement, der understøtter den eksekvérbare udvidelses analysesyntaks for elementer af typen widget
og dynamic
.
IExecutableExtension
.<!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.
true
, skal der ikke være nogen underordnede elementer. Dette kontrollerer kun aktiveringstilstanden for kommandoen og gør det tilsvarende element synligt, hvis kommandoen er aktiveret. <!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.
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.
I tilfælde af konflikter kan Eclipse vælge en vilkårlig rækkefølge. Den eneste garanti er, at rækkefølgen bevares i tilfælde af konflikter, så længe følgende holder:
position
er before
eller after
.<!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>
IWorkbenchPartSite.registerContextMenu
.
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