Menu's

org.eclipse.ui.menus

3.2

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.



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



<!ELEMENT group (location*)>

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



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



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



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



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Het element class met ondersteuning voor de ontledingssyntaxis van uitvoerbare extensies voor de elementen widget en dynamic.



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



<!ELEMENT part (popup | bar)>

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



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

Voor het registreren van een voorgrondmenu kunt u de methoden van IWorkbenchPartSite.registerContextMenu gebruiken.