Door middel van dit extensiepunt kunnen pluginontwikkelaars menu's, scheidingslijnen, logische groepen en menuopties definiëren en overal in de toepassing inzetten, uiteenlopend van statusregels tot voorgrondmenu's. Bovendien kunnen er verzamelingen van acties (actiesets) worden gedefinieerd, die de eindgebruiker kan in- of uitschakelen. Kortom, dit extensiepunt bevat alle presentatie-elementen (met uitzondering van de pictogrammen) voor het verstrekken van aanleveringen voor menu's of beelduitsneden in Eclipse.
Elk element in dit extensiepunt krijgt een unieke identificatie. Er kan zo elders naar de elementen worden verwezen, zonder dat deze opnieuw gedefinieerd moeten worden. De identificatie is bijvoorbeeld nodig voor het sorteren of het definiëren van een actieset. Bovendien kunnen andere pluginontwikkelaars op deze manier waar nodig elementen in de nieuwe locaties van de interface opnemen.
Opmerking: voor 3.2 is het enige gedeelte van dit extensiemechanisme dat wordtgeïmplementeerd het gedeelte dat wordt gekoppeld aan trim-bijdragen. Pogingen om items, menu's, werkbalken of statusregelgegevens toe te voegen dienen als een 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>
Of een item een menuoptie of een beeldoptie wordt, is afhankelijk van de locatie waar het geplaatst wordt.De tekst en de afbeelding voor het item worden van de opdracht afgeleid.
org.eclipse.ui
is aangeleverd, kan bijvoorbeeld org.eclipse.ui.item1
heten. <!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
U kunt een menu aan een toolitem koppelen of in een viewmenu, voorgrondmenu of het hoofdmenu bovenaan opnemen. Een pluginontwikkelaar kan er vanuit gaan dat elke view van een menu en een werkbalk is voorzien en dat het hoofdmenu bovenaan bestaat. Voorgrondmenu's kunnen pas worden gebruikt als ze programmatisch zijn geregistreerd (zie de API-informatie).
Een menu kan alleen groepen bevatten.
org.eclipse.ui
is aangeleverd, kan bijvoorbeeld org.eclipse.ui.menu1
heten. <!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
Een logische groep. De groep kan zichtbaar (waarbij scheidingslijnen waar nodig vóór en achter de groep worden geplaatst) en onzichtbaar zijn. Logische groepen zijn standaard zichtbaar.
Een groep kan menu's, menuopties en andere groepen bevatten.
org.eclipse.ui
is aangeleverd, kan bijvoorbeeld org.eclipse.ui.group1
heten. <!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
Een menu- of trim-element dat rechtstreeks toegang tot de widgets wordt verleend. Hiermee kan bijvoorbeeld een keuzelijst met invoervak worden weergegeven. Het is wel zo dat het zichtbaar maken van een widget-element in de gebruikersinterface ertoe leidt dat de bijbehorende plugins worden geladen. Gebruik dit element verstandig in verband met prestatieproblemen. Dit heeft ook gevolgen voor macro-ondersteuning, scripting en vrijwel iedere andere op opdrachten gebaseerde techniek. Als de widget als uitsnede wordt gebruikt, wordt de plugin pas geladen zodra deze in de gebruikersinterface zichtbaar wordt.
org.eclipse.ui
is aangeleverd, kan bijvoorbeeld org.eclipse.ui.widget1
heten. IWorkbenchWidget
implementeren. Clients kunnen ervoor kiezen om de standaardimplementatie te gebruiken; AbstractWorkbenchTrimWidget
. Deze implementatie hanteert de methode init en slaat het resultaat in de cache op zodat het kan worden gebruikt voor de methode getWorkbenchWindow
. <!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
Met dit element kunnen diverse layout-opties worden opgegeven voor elementen die in trim
-locaties worden geplaatst.
false
. false
. <!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
Een locatie waarin de elementen menu
, group
, item
en widget
kunnen voorkomen. Dit element bepaalt locatiespecifieke informatie.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
Een eindpuntelement in een locatie. Dit kan de menubalk of het beelduitsnedegebied zijn. Als u niets opgeeft, geeft dit kenmerk de hoofdmenubalk bovenaan of de hoofdbeelduitsnede aan. Als u dit kenmerk met het element part
kwalificeert, geeft het kenmerk het menu of de uitsnede van het element aan.
menu
of trim
gebruiken. Als u een aanlevering voor een menu verstrekt, wordt een widgetstructuur als bovenliggend item van het item gebruikt. Over het algemeen zijn widget-elementen dus vrij zinloos en hoeft u niet per se een pictogram voor de opdracht van een item op te geven. De standaardwaarde is menu
.
Als u aanleveringen verstrekt voor trim
, hoeft u voor de balk doorgaans geen opdracht of pictogram op te geven. Er wordt namelijk een widget gegenereerd die de trim-gegevens weergeeft.
In de beelduitsnede hanteert de workbench vijf algemene groepen die betrekking op diverse posities rond het venster hebben:
vertical1
. '/'
als scheidingsteken in het pad. <!ATTLIST class
class CDATA #REQUIRED>
Het element class met ondersteuning voor de ontledingssyntaxis van uitvoerbare extensies voor de elementen widget
en dynamic
.
IExecutableExtension
moet worden geladen. <!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Bestuurt de zichtbaarheid van het opgegeven element.
true
instelt, kunt u geen subelementen definiëren. Hiermee wordt alleen gecontroleerd of de opdracht is ingeschakeld en aan de hand hiervan wordt bepaald of het bijbehorende element zichtbaar moet zijn. <!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
Een element in een locatie. Hiermee wordt de locatie gekwalificeerd om naar een bepaald workbenchonderdeel te verwijzen. Dit kan een view of een editor zijn. Voor de kwalificatie kunt u de klassennaam van het onderdeel (inclusief overname) gebruiken of u kunt de kwalificatie naar de identificatie van de view of editor laten verwijzen.
U kunt id
en class
niet samen opgeven.
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Een parameter voor een uitvoerbare extensie of een opdracht, afhankelijk van de locatie waarin deze in de extensie wordt gebruikt.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Bestuurt de positie van een menu, groep, item of widget in een bepaalde locatie.
Voor dit kenmerk kunt u de volgende waarden opgeven:start
(element aan begin van container plaatsen)end
(element aan einde van container plaatsen)after
(element plaatsen achter element op hetzelfde niveau waarvan het ID overeenkomt met ref
)before
(element plaatsen vóór element op hetzelfde niveau waarvan het ID overeenkomt met ref
).
U kunt de relatieve rangschikking of ieder type menu-element toepassen.
Indien er een conflict optreedt, kiest Eclipse een willekeurige volgorde.Er kan in een dergelijke situatie alleen worden gegarandeerd dat de volgorde intact blijft als er sprake is van het volgende:
position
op before
of after
hebt ingesteld. <!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Een onderdeel van een locatie. Dit geeft aan dat de menu, de groep, het item of de widget in het voorgrondmenu moet voorkomen.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Een generiek hoofdelement. U kunt het element in een extensiepunt gebruiken om de beschikbaarheidsexpressie ervan te definiëren. De criteria van een beschikbaarheidsvoorwaarde worden gecombineerd met de operator AND.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Dit element is een NOT-bewerking op het evaluatieresultaat van de bijbehorende subexpressie.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Dit element is een AND-bewerking op het evaluatieresultaat van alle bijbehorende subexpressies.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Dit element is een OR-bewerking op het evaluatieresultaat van alle bijbehorende subexpressies.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Dit element wordt gebruikt om een instanceof-controle uit te voeren op het object dat de focus heeft. De expressie retourneert EvaluationResult.TRUE als het objecttype een subtype is van het type dat voor de kenmerkwaarde is opgegeven. Anders retourneert de expressie EvaluationResult.FALSE.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Dit element wordt gebruikt om de eigenschapsstatus te evalueren van het object dat de focus heeft. De testbare eigenschappen kunnen worden uitgebreid met het extensiepunt van de eigenschapstester. De testexpressie retourneert EvaluationResult.NOT_LOADED als de eigenschapstester nog niet is geladen.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Vraagt een systeemeigenschap op met de methode System.getProperty en vergelijkt het resultaat daarvan met de waarde die voor het kenmerk value is opgegeven.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Dit element wordt gebruikt om een equals-controle uit te voeren op het object dat de focus heeft. De expressie retourneert EvaluationResult.TRUE als het object gelijk is aan de waarde die voor de kenmerkwaarde is opgegeven. Anders retourneert de expressie EvaluationResult.FALSE.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Dit element wordt gebruikt om het aantal elementen van een collectie op te vragen.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
Dit element wijzigt het te inspecteren object voor alle subelementen in het object waarnaar door de opgegeven variabele wordt verwezen. Als de variabele niet kan worden omgezet, verwerpt de expressie de uitzondering ExpressionException tijdens de evaluatie. De onderliggende items van een with-expressie worden gecombineerd met de operator AND.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
Dit element wijzigt het te inspecteren object voor alle subelementen in het object waarnaar door de opgegeven variabele wordt verwezen. Als de variabele niet kan worden omgezet, verwerpt de expressie de uitzondering ExpressionException tijdens de evaluatie. De onderliggende items van een with-expressie worden gecombineerd met de operator AND.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Dit element wordt gebruikt om het focusobject aan te passen aan het type dat voor het kenmerk type is opgegeven. De expressie retourneert 'not loaded' als de adapter of het type nog niet is geladen. Als de typenaam helemaal niet bestaat, wordt de uitzondering ExpressionException verworpen tijdens de evaluatie. De criteria van een adapt-expressie worden gecombineerd met de operator AND.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Dit element wordt gebruikt om een variabele van het type java.util.Collection te doorlopen. Als het focusobject niet van het type java.util.Collection is, wordt de uitzondering ExpressionException verworpen tijdens de evaluatie.
Een gewone menudefinitie ziet er als volgt uit:
<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 dit voorbeeld wordt de aanlevering toegevoegd aan alle onderdelen die het opgegeven type implementeren of als subklasse bevatten. Hierdoor kunnen sommige aanleveringen aan alle teksteditors worden toegevoegd.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Tekstopdrachten"
>
<location mnemonic=
"k"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
U kunt Help aan een menu koppelen.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Uitvoeren met configuratie"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
In een menu kunt u logische groepen definiëren. Deze groepen kunnen zichtbaar (waarbij scheidingslijnen waar nodig vóór en achter de groep worden geplaatst) en onzichtbaar zijn. Logische groepen zijn standaard zichtbaar.
<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>
U kunt menu's, groepen, items en widgets op meerdere locaties laten voorkomen.
<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>
Als het element popup zonder ID en bovenliggend onderdeel wordt opgegeven, is het van toepassing op alle voorgrondmenu's die in de workbench zijn geregistreerd. Dit gedrag is vergelijkbaar met het gedrag van de ouderwetse objectaanleveringen. Een popup-element van het hoogste niveau dat van een ID is voorzien, is van toepassing op ieder voorgrondmenu dat met de opgegeven naam is geregistreerd.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Soms moet de zichtbaarheid van een item worden geregeld. Het is normaal gesproken raadzaam de stabiliteit van de layout van menu's en werkbalken te behouden, maar soms kunt u beter items verbergen die niet direct relevant zijn. Dit geldt vooral voor voorgrondmenu's, waarin de ruimte beperkt is. U kunt in een dergelijke situatie het element visibleWhen
instellen. Dit element is vrijwel identiek aan de elementen activeWhen
en enabledWhen
in het extensiepunt voor 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=
"selectie"
>
<iterate operator=
"and"
>
<not>
<instanceof value=
"IWatchExpression"
/>
</not>
<instanceof value=
"IExpression"
/>
</iterate>
</with>
</visibleWhen>
</item>
Meestal zult u een item zichtbaar maken wanneer de bijbehorende handler is ingeschakeld. U kunt hiervoor enige code gebruiken. Het element visibleWhen
bevat het kenmerk 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>
Elk item dat aan een opdracht is toegewezen, kan parameterwaarden bevatten. Als de parameter van de opgegeven identificatie niet is gedefinieerd, wordt er een foutbericht gegenereerd. Als het item geen opdracht heeft, levert dit eveneens een foutbericht op.
<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>
U kunt verder de relatieve rangschikking specificeren. Hiervoor kunt u het kenmerk order van het element location gebruiken. Voor het kenmerk order kunt u de volgende waarden opgeven:start
(element aan begin van container plaatsen)end
(element aan einde van container plaatsen)after
(element plaatsen achter element op hetzelfde niveau waarvan het ID overeenkomt met ref
)before
(element plaatsen vóór element op hetzelfde niveau waarvan het ID overeenkomt met ref
).
U kunt de relatieve rangschikking of ieder type menu-element toepassen.
<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>
Als u direct met de widgets wilt kunnen werken (bijvoorbeeld voor het weergeven van een keuzelijst met invoervak), kunt u het element widget
gebruiken. Het is wel zo dat het zichtbaar maken van een widget-element in de gebruikersinterface tot het laden van gekoppelde plugins leidt.
<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>
U kunt de widgets bovendien gebruiken om aanleveringen voor het workbenchgebied te verstrekken. In het onderstaande voorbeeld wordt een nieuwe widget, "HeapStatus", gedefinieerd die standaard direct achter de statusregel (dus onder aan het workbenchvenster) moet worden geplaatst. Zie de beschrijving van het element bar voor meer informatie over de vooraf gedefinieerde groepen.
U kunt group-elementen in een andere locatie onderbrengen. Het kenmerk relativeTo
van de locatie gaat er vanuit dat de groep waarnaar wordt verwezen zich op de standaardpositie bevindt bij het bepalen van de nieuwe locatie. Over het algemeen wordt verwacht dat contribuanten van dit type een eigen groep voor het herbergen van de nieuwe widget maken, zodat het element onafhankelijk van de andere elementen kan worden verplaatst. Eén belangrijke uitzondering hierop is de groep '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
gebruiken.
Copyright (c) 2005 IBM Corporation en anderen.
Alle rechten voorbehouden. Dit programma en het begeleidende materiaal zijn beschikbaar gesteld onder de voorwaarden van de Eclipse Public License v1.0 die bij deze distributie is geleverd en beschikbaar is op http://www.eclipse.org/legal/epl-v10.html.