Åtgärdsuppsättningar

org.eclipse.ui.actionSets

Den här utökningspunkten används för att lägga till menyer, menyalternativ och verktygsknappar i de gemensamma områdena i arbetsmiljöns fönster. Detta innehåll kallas gemensamt för en åtgärdsuppsättning och visas i arbetsmiljöns fönster genom att användaren anpassar ett perspektiv.

Det finns en implementeringsgräns som för närvarande påverkar åtgärdsuppsättningar. Det är viktigt att definiera hela menystrukturen som refereras till i åtgärdsuppsättningen. Det innebär att om till exempel en annan åtgärdsuppsättning definierar en meny med namnet "exempel" går det inte att förlita sig på att "exempel" finns. Menyn "exempel" måste definieras om i varje åtgärdsuppsättning där den används.

Aktivering och/eller synlighet för en åtgärd kan definieras med hjälp av elementen enablement respektive visibility. Dessa två element innehåller ett booleskt uttryck som utvärderas för att fastställa aktivering och/eller synlighet.

Syntaxen är densamma för elementen enablement och visibility. Båda innehåller endast ett underelement med ett booleskt uttryck. I det enklaste fallet är det något av elementen objectClass, objectState, pluginState eller systemProperty. I det mer komplicerade fallet kombineras elementen and, or och not så att ett booleskt uttryck skapas. Både and och or måste innehålla två underelement. Elementet not får bara innehålla ett underelement.

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

Det här elementet används för att definiera en grupp åtgärder och/eller menyer.



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

Med det här elementet definieras en åtgärd som användaren kan anropa i användargränssnittet.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Elementet används för att definiera en ny meny.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Elementet används till att skapa en menyavgränsare på den nya menyn.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Elementet används till att skapa en namngiven grupp på den nya menyn. Den saknar visuell representation på den nya menyn i motsats till elementet separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Elementet används för att hjälpa till att bestämma aktivering av åtgärden, baserat på aktuellt urval. Ignoreras om elementet enablement anges.



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

Elementet används för att definiera aktivering av utökningen.



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

Elementet används för att definiera synligheten för utökningen.



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

Elementet representerar ett booleskt AND-uttryck för resultatet från utvärderingen av de två underelementuttrycken.



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

Elementet representerar ett booleskt OR-uttryck för resultatet från utvärderingen av de två underelementuttrycken.



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

Elementet representerar ett booleskt NOT-uttryck för resultatet från utvärderingen av underelementuttrycken.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Elementet används för att utvärdera klassen eller gränssnittet för varje objekt i det aktuella urvalet. Om varje objekt i urvalet implementerar angiven klass eller angivet gränssnitt utvärderas uttrycket till sant.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Elementet används för att utvärdera attributläget för varje objekt i det aktuella urvalet. Om varje objekt i urvalet har angivet attributläge utvärderas uttrycket till sant. För att utvärdera den här typen av uttryck måste varje objekt i urvalet implementera eller anpassas till gränssnittet org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Elementet används för att utvärdera insticksprogrammets läge. Läget för insticksprogrammet kan vara ett av följande:installed (motsvarar OSGi-begreppet "löst") eller activated (motsvarar OSGi-begreppet "aktiv").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Elementet används för att utvärdera läget för vissa systemegenskaper. Egenskapsvärdet hämtas från java.lang.System.



Här följer ett exempel på en åtgärdsuppsättning (lägg märke till underelementen och på vilket sätt attribut används):

    

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

"&amp;Kör XYZ-verktyget"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Kör XYZ-verktyget"

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>

I exemplet ovan är den angivna åtgärdsuppsättningen med namnet "My Actions", initialt inte synlig inom varje perspektiv eftersom attributet visible inte har angetts.

Åtgärden XYZ visas som ett menyalternativ med kryssruta, initialt inte markerad. Den aktiveras endast om antalet markeringar är 1 och om markeringen innehåller en Java-filresurs.

Åtgärden ABC visas både på menyn och i verktygsfältet. Den aktiveras endast om markeringen inte innehåller några Java-filresurser. Lägg också märke till att detta är åtgärd för nytt mål för etikett och därför tillhandahåller den inte attributet class.

Åtgärderna DEF, GHI och JKL visas som menyalternativ med radioknappar. De är alltid aktiverade, oberoende av den aktuella markeringens läge.

Värdet för attributet class måste vara det fullständiga namnet för en klass som implementerar org.eclipse.ui.IWorkbenchWindowActionDelegate eller org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Det senare ska implementeras i de fall attributet style har värdet pulldown. Den här klassen är den hanterare som ansvarar för att utföra åtgärden. Om attributet retarget har värdet true ignoreras det här attributet och ska inte tillhandahållas. Klassen läses in så sent som möjligt för att undvika inläsning av hela insticksprogrammet, innan det verkligen behövs.

Aktiveringsvillkoret för en åtgärdsutökning definieras initialt med enablesFor och antingen selection eller enablement. När åtgärdsdelegeringen har instantierats kan den dock styra åtgärdens aktiveringsläge direkt i dess selectionChanged-metod.

Det är viktigt att lägga märke till att menyer inte genereras i arbetsmiljön för ett insticksprogram räkning. Menysökvägar måste referera till menyer som redan finns.

Åtgärds- och menyetiketter kan innehålla specialtecken för kodning av snabbtangenter med hjälp av följande regler:

  1. Snabbtangenter anges med hjälp av et-tecknet ('&') före ett valt tecken i översatt text. Eftersom et-tecknet inte tillåts i XML-strängar används teckenentiteten &amp;.
Om två eller flera åtgärder läggs till på en meny eller i ett verktygsfält av en enda utökning, visas åtgärderna i motsatt ordning till hur de visas i filen plugin.xml. Det här funktionssättet är inte särskilt intuitivt, det medges. Detta upptäcktes emellertid sedan koden för Eclipse-plattformens API hade avslutats. Om funktionen ändras i nuläget skulle det innebära att varje insticksprogram som förlitar sig på befintliga funktioner bryts.

Elementen selection och enablement utesluter varandra. Elementet enablement kan ersätta elementet selection med hjälp av underelementen objectClass och objectState. Till exempel följande:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

kan uttryckas med:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

I insticksprogram kan den här utökningspunkten användas till att lägga till nya menyer på den översta nivån. I insticksprogram kan även namngivna grupper definieras som gör det möjligt att tillhandahålla andra insticksprograms åtgärder till dem.

Menyer på den översta nivån skapas med hjälp av följande värden för attributet path:

Om attributet path utelämnas resulterar det i att den nya menyn läggs till i menyradsgruppen additions.

Standardgrupperna i ett fönster i arbetsmiljön definieras i gränssnittet IWorkbenchActionConstants. Dessa konstanter kan användas i kod för dynamiskt tillhandahållande. Värdena kan också kopieras till en XML-fil för finmalen integrering med befintliga menyer och verktygsfält i arbetsmiljön.

Olika meny- och verktygsfältsalternativ i fönstret i arbetsmiljön definieras algoritmiskt. I dessa fall måste en separat mekanism användas till att utöka fönstret. Om du till exempel lägger till en ny vy i arbetsmiljön resulterar det i att ett nytt menyalternativ visas på menyn Perspektiv. Utökningarna Importera, Exportera och Nya guider läggs också till automatiskt i fönstret.