Voorgrondmenu's

org.eclipse.ui.popupMenus

Dit extensiepunt wordt gebruikt om nieuwe acties aan voorgrondmenu's van andere plugins toe te voegen. U kunt acties aanleveren in een bepaald objecttype (objectContribution) of in een specifiek voorgrondmenu van een view of een editoronderdeel (viewerContribution). Acties die met objectContribution worden aangeleverd, verschijnen in alle voorgrondmenu's van views of editoronderdelen wanneer objecten van het opgegeven type worden geselecteerd. Acties die daarentegen met viewerContribution worden aangeleverd, verschijnen alleen in het voorgrondmenu van de opgegeven view of het opgegeven editoronderdeel, ongeacht de selectie.

Bestaat de selectie uit objecten van meerdere typen, dan wordt de aanlevering indien mogelijk toegepast als deze voor een algemeen type uit de selectie is geregistreerd. Als van een rechtstreekse overeenkomst geen sprake is, wordt geprobeerd een overeenkomst op basis van superklassen en superinterfaces te zoeken.

De selectie kan verder worden beperkt met behulp van een naamfilter. Alle objecten in de selectie moeten dan overeenkomen met de filter om in combinatie met de aanlevering te kunnen worden gebruikt.

Voor afzonderlijke acties van objectaanleveringen kunt u het kenmerk enablesFor gebruiken om aan te geven of de aanlevering moet worden toegepast op enkelvoudige, meervoudige of andere selectietypen.

Als deze filtermechanismen niet toereikend zijn, kunt u voor actieaanleveringen ook filter gebruiken. De kenmerken van de doelobjecten worden dan in een reeks naam/waarde-paren toegevoegd. De kenmerken die op de selectie van toepassing zijn, zijn typespecifiek en vallen buiten het domein van de workbench zelf. De workbench delegeert het filteren op dit niveau feitelijk naar de selectie.

U kunt het inschakelen of zichtbaar maken van een actie definiëren met de elementen enablement en visibility. Deze twee elementen bevatten een booleaanse expressie die wordt geëvalueerd om de inschakeling en/of zichtbaarheid vast te stellen.

De syntaxis is voor de elementen enablement en visibility dezelfde. Beide bevatten slechts één booleaanse expressie als subelement. In het eenvoudigste geval is dit een element van het type objectClass, objectState, pluginState of systemProperty. In ingewikkelder gevallen kunnen de elementen and, or en not worden gecombineerd tot booleaanse expressie. De elementen and en or moeten twee subelementen bevatten. Het element not mag slechts één subelement bevatten.

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

Dit element wordt gebruikt om een groep acties en/of menu's te definiëren voor de voorgrondmenu's van de viewers waarin de objecten van het opgegeven type worden geselecteerd.



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Dit element wordt gebruikt om een groep acties en/of menu's te definiëren voor een bepaald voorgrondmenu van een specifieke view of een specifiek editoronderdeel.



<!ELEMENT action (selection* , enablement?)>

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

Met dit element wordt de actie gedefinieerd die de gebruiker in de gebruikersinterface kan oproepen.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dit element wordt gebruikt om de kenmerkstatus van alle objecten in de huidige selectie te evalueren. Er wordt alleen een overeenkomst gevonden als ieder object in de selectie de opgegeven kenmerkstatus heeft. Elk object in de selectie moet org.eclipse.ui.IActionFilter implementeren of eraan aangepast zijn.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Dit element wordt gebruikt om een nieuw menu te definiëren.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Dit element wordt gebruikt om een menuscheidingsteken in het nieuwe menu te maken.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Dit element wordt gebruikt om een benoemde groep in het nieuwe menu te maken. Er is geen visuele voorstelling in het nieuwe menu, in tegenstelling tot het element separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Dit element wordt gebruikt om vast te stellen of de actie wordt ingeschakeld op basis van de huidige selectie. Wordt genegeerd als het element enablement is opgegeven.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dit element wordt gebruikt om het inschakelen voor de extensie te definiëren.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dit element wordt gebruikt om de zichtbaarheid voor de extensie te definiëren.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dit element is een booleaanse AND-bewerking, de evaluatie van twee subelementexpressies.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dit element is een booleaanse OR-bewerking, de evaluatie van twee subelementexpressies.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dit element is een booleaanse NOT-bewerking, de evaluatie van de subelementexpressies.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Dit element wordt gebruikt om de klasse of interface van alle objecten in de huidige selectie te evalueren. Als ieder object in de selectie de opgegeven klasse of interface implementeert, wordt de expressie als waar (true) beschouwd.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dit element wordt gebruikt om de kenmerkstatus van alle objecten in de huidige selectie te evalueren. Als ieder object in de selectie de opgegeven kenmerkstatus heeft, wordt de expressie als waar (true) beschouwd. Om dit type expressie te evalueren, moet elk object in de selectie de interface org.eclipse.ui.IActionFilter implementeren of eraan aangepast zijn.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Dit element wordt gebruikt om de status van een plugin te evalueren. Een plugin kan een van de volgende statussen hebben: installed (equivalent van het OSGi-concept "resolved") of activated (equivalent van het OSGi-concept "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dit element wordt gebruikt om de status van een systeemeigenschap te evalueren. De waarde van de eigenschap wordt opgehaald uit java.lang.System.



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



Dit is een voorbeeld van de extensie popupMenus:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

<menu id=

"com.xyz.xyzMenu"

path=

"additions"

label=

"&amp;XYZ Java-tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"XYZ-tool uitvoe&amp;ren"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.XYZToolActionDelegate"

enablesFor=

"1"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"XYZ af&amp;beelden"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</viewerContribution>

</extension>

In het bovenstaande voorbeeld wordt de opgegeven actie van de objectaanlevering alleen ingeschakeld voor een selectie van één item (kenmerk enablesFor). Verder moet elk object in de selectie de opgegeven interface (IFile) implementeren en een Java-bestand zijn. Deze actie wordt toegevoegd aan een eerder gemaakt submenu. De aanlevering wordt toegepast op alle views waarin de vereiste selectie wordt aangetroffen.

De vieweraanlevering daarentegen wordt alleen afgebeeld in het voorgrondmenu van de view Taken en wordt niet beïnvloed door de selectie in de view.

Hieronder ziet u een voorbeeld van het filtermechanisme. De actie wordt alleen afgebeeld voor IMarkers-objecten die voltooid zijn en een hoge prioriteit hebben.

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C3"

objectClass=

"org.eclipse.core.resources.IMarker"

>

<filter name=

"done"

value=

"true"

/>

<filter name=

"priority"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"Actietool voor voltooide merktekens met hoge prioriteit"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Dit is nog een voorbeeld van het element visibility:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<viewerContribution id=

"com.xyz.C4"

targetID=

"org.eclipse.ui.views.TaskList"

>

<visibility>

<and>

<pluginState id=

"com.xyz"

value=

"activated"

/>

<systemProperty name=

"ADVANCED_MODE"

value=

"true"

/>

</and>

</visibility>

<action id=

"com.xyz.showXYZ"

label=

"XYZ af&amp;beelden"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

De opgegeven actie uit het bovenstaande voorbeeld wordt alleen als menuoptie afgebeeld in het voorgrondmenu van de view Taken als de plugin "com.xyz" actief is en de opgegeven systeemeigenschap is ingesteld.

De waarde van het actie-kenmerk class moet de volledig gekwalificeerde naam zijn van de Java-klasse waarmee org.eclipse.ui.IObjectActionDelegate wordt geïmplementeerd voor objectaanleveringen, org.eclipse.ui.IViewActionDelegate voor voorgrondmenu's van views of org.eclipse.ui.IEditorActionDelegate voor voorgrondmenu's van editors. De implementerende klasse wordt in alle gevallen zo laat mogelijk geladen om te voorkomen dat de gehele plugin wordt geladen voordat het nodig is.

Opmerking: U kunt org.eclipse.ui.IActionDelegate implementeren voor compatibiliteit met eerdere versies.

U kunt een voorgrondmenu-extensie alleen aan een onderdeel toevoegen wanneer er een uitbreidbaar menu beschikbaar wordt gesteld door het doelonderdeel. Het gebruik van dergelijke menu's wordt ten zeerste aanbevolen, zodat het product verder kan worden uitgebreid. U moet dan alle menu's van onderdelen publiceren die door IWorkbenchPartSite.registerContextMenu worden gedefinieerd. Vervolgens worden alle bestaande actie-extensies automatisch ingevoegd door de workbench.

Voor elk geregistreerd menu moet u een ID opgeven. Omwille van de consistentie tussen de onderdelen moet u als volgt te werk gaan:

Alle voorgrondmenu's die met de workbench worden geregistreerd, moeten ook een standaardinvoegpunt bevatten met het ID IWorkbenchActionConstants.MB_ADDITIONS. Deze waarde wordt door andere plugins gebruikt als verwijzingspunt voor invoegingen. Het invoegpunt kunt u definiëren door een GroupMarker aan het menu toe te voegen op een door u gekozen positie.

Een workbenchobject dat in een voorgrondmenu is geselecteerd, kan een filter (org.eclipse.ui.IActionFilter) definiëren. Zo kunt u typespecifieke filters instellen. De workbench controleert of IActionFilter wordt geïmplementeerd door de selectie om de filter op te halen. Blijkt dit niet het geval te zijn, dan wordt de filter opgevraagd via IAdaptable.

De labels van acties en menu's kunnen speciale tekens bevatten voor het instellen van keuzeletters door het en-teken ('&') voor een geselecteerd teken in de vertaalde tekst te plaatsen. Omdat het en-teken niet is toegestaan in XML-reeksen, moet u de tekencode &amp; gebruiken.

Als er twee of meer acties aan een menu worden aangeleverd door één extensie, worden ze afgebeeld in de omgekeerde volgorde van hoe ze in het bestand plugin.xml zijn opgenomen. Dit gedrag werkt niet erg intuïtief. Dit werd echter pas ontdekt nadat geen wijzigingen meer konden worden doorgevoerd in de API van het Eclipse-platform. Als u nu het gedrag wijzigt, levert dit problemen op voor alle plugins die op het bestaande gedrag zijn gebaseerd.

De elementen selection en enablement zijn onderling uitwisselbaar. Het element enablement kan het element selection vervangen als u de subelementen objectClass en objectState gebruikt. De code

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

kan bijvoorbeeld worden gecodeerd als:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

De workbenchviews bevatten ingebouwde voorgrondmenu's die al een aantal vooraf gedefinieerde acties bevatten. De menu's kunnen worden uitgebreid met plugins. Als een viewer gereserveerde groepen heeft die openbaar zijn gemaakt, kunnen deze als paden worden gebruikt. Anders worden acties en submenu's aan het einde van een voorgrondmenu toegevoegd.