Actiesets

org.eclipse.ui.actionSets

Dit extensiepunt wordt gebruikt om menu's, menuopties en werkbalkknoppen toe te voegen aan de algemene velden van het Workbenchvenster. Deze bijdragen worden gezamenlijk een actieset genoemd en verschijnen binnen het Workbenchvenster wanneer de gebruiker een perspectief aanpast.

Er is een implementatiebeperking van kracht die van invloed is op actiesets. In de actieset moet u de volledige menustructuur definiëren waarnaar verwezen moet worden. Als in een andere actieset het menu "voorbeeld" is gedefinieerd, kan "voorbeeld" niet als bestaand menu worden gehanteerd. Het menu "voorbeeld" moet opnieuw worden gedefinieerd in elke actieset waarin het menu nodig is.

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 (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT actionSet (menu* , action*)>

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

visible     (true | false)

description CDATA #IMPLIED>

Dit element wordt gebruikt om een groep acties en/of menu's te definiëren.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

accelerator      CDATA #IMPLIED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

toolbarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

disabledIcon     CDATA #IMPLIED

hoverIcon        CDATA #IMPLIED

tooltip          CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown) "push"

state            (true | false)

pulldown         (true | false)

class            CDATA #IMPLIED

retarget         (true | false)

allowLabelUpdate (true | false)

enablesFor       CDATA #IMPLIED>

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



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



Een voorbeeld van een actieset (let op de subelementen en de manier waarop de kenmerken worden gebruikt):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"My Actions"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"XYZ-tool uitvoe&amp;ren"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

enablesFor=

"1"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

<action id=

"com.xyz.runABC"

label=

"&amp;Run ABC Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Run ABC Tool"

helpContextId=

"com.xyz.run_abc_action_context"

retarget=

"true"

allowLabelUpdate=

"true"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

<action id=

"com.xyz.runDEF"

label=

"&amp;Run DEF Tool"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Run DEF Tool"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Run GHI Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Run GHI Tool"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Run JKL Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Run JKL Tool"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

In bovenstaand voorbeeld is de opgegeven actieset "My Actions" niet binnen elk perspectief meteen zichtbaar omdat het kenmerk visible niet is opgegeven.

De XYZ-actie verschijnt als selectievakje-menuoptie die eerst niet is geselecteerd. Deze optie is alleen ingeschakeld wanneer het selectieaantal 1 is en de selectie een Java-bestandenresource bevat.

De ABC-actie wordt zowel in het menu als in de werkbalk afgebeeld. Deze wordt alleen ingeschakeld als de selectie geen Java-bestandenresources bevat. Merk op dat dit een actie is voor het opnieuw richten van het label en dat deze daarom geen kenmerk class levert.

De acties DEF, GHI en JKL verschijnen als keuzerondje-menuopties. Deze zijn altijd ingeschakeld, onafhankelijk van de huidige selectiestatus.

De waarde van het kenmerk class moet de volledig gekwalificeerde naam zijn van een klasse die org.eclipse.ui.IWorkbenchWindowActionDelegate of org.eclipse.ui.IWorkbenchWindowPulldownDelegate implementeert. De laatste moet worden geïmplementeerd wanneer het kenmerk style de waarde pulldown heeft. Deze klasse is de afhandelingsroutine die de actie uitvoert. Als het kenmerk retarget waar is, wordt dit kenmerk genegeerd en moet het niet worden verstrekt. Deze klasse wordt zo laat mogelijk geladen om te voorkomen dat de gehele plugin wordt geladen voordat het nodig is.

De inschakelingscriteria van een actie-extensie worden in eerste instantie gedefinieerd door enablesFor en verder door selection of enablement. Als de gemachtigde van de actie echter is geïnstantieerd, kan deze de inschakelingsstatus van de actie beheren in de methode selectionChanged.

Het is belangrijk dat u zich realiseert dat de workbench geen menu's genereert ten behoeve van plugins. Menupaden moeten verwijzen naar menu's die al bestaan.

Labels van acties en menu's kunnen speciale tekens bevatten die als keuzeletter fungeren volgens de volgende regels:

  1. Keuzeletters worden opgegeven door het en-teken ('&') voor het geselecteerde teken te plaatsen in de vertaalde tekst. 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 of werkbalk zijn aangeleverd door één extensie, worden de acties 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>

Dit extensiepunt kan door de plugins worden gebruikt om nieuwe toplevelmenu's toe te voegen. De plugins kunnen ook benoemde groepen definiëren die andere plugins toestaan hun acties hierin aan te leveren.

Toplevelmenu's worden gemaakt met behulp van de volgende waarden voor het padkenmerk:

Als dit padkenmerk wordt weggelaten, wordt het nieuwe menu in de menubalkgroep toevoegingen toegevoegd.

De standaardgroepen in een workbenchvenster worden gedefinieerd in de IWorkbenchActionConstants-interface. Deze constanten kunnen worden gebruikt in een code voor dynamische aanlevering. De waarden kunnen ook naar een XML-bestand worden gekopieerd voor een verfijnde integratie met de bestaande workbench-menu's en -werkbalk.

Verschillende menu- en werkbalkopties worden binnen het workbenchvenster algoritmisch gedefinieerd. In die gevallen moet een apart mechanisme worden gebruikt om het venster uit te breiden. Als bijvoorbeeld een nieuwe workbenchview wordt toegevoegd, verschijnt een nieuwe menuoptie in het perspectiefmenu. Ook worden automatisch extensies voor Importeren, Exporteren en Nieuwe wizards aan het venster toegevoegd.