Akční sady

org.eclipse.ui.actionSets

Tento bod rozšíření se používá k přidávání nabídek, položek nabídek a tlačítek panelu nástrojů do běžných oblastí okna pracovní plochy. Tyto příspěvky se společně nazývají akční sada a objevují se v okně pracovní plochy podle uživatele, který přizpůsobuje perspektivu.

Zpřístupnění nebo viditelnost zvolené akce lze nastavit pomocí příslušného prvku enablement nebo visibility. Tyto dva prvky obsahují logický výraz, který je vyhodnocen pro stanovení zpřístupnění (enablement) anebo viditelnosti (visibility).

Syntaxe je stejná jak pro prvek enablement, tak i pro prvek visibility. Oba obsahují pouze jeden dílčí prvek logického výrazu. V nejjednodušším případě to bude prvek objectClass, objectState, pluginState nebo systemProperty. V komplexnějších případech mohou být kombinovány prvky and, or a not pro vytvoření logického výrazu. Prvky and a or musí obsahovat 2 dílčí prvky. Prvek not musí obsahovat pouze 1 dílčí prvek.

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

Tento prvek se používá k definování skupiny akcí anebo nabídek.



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

Tento prvek definuje akci, kterou může uživatel vyvolat v uživatelském rozhraní.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Tento prvek se používá pro definování nové nabídky.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Tento prvek se používá pro vytváření oddělovače nabídky v nové nabídce.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Tento prvek se používá pro vytváření pojmenované skupiny v nové nabídce. Na rozdíl od prvku separator nemá žádné vizuální znázornění v nové nabídce.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Tento prvek se používá pro usnadnění zjištění, zda je akce zpřístupněna na základě aktuálního výběru. Prvek je ignorován, pokud je zadán prvek enablement.



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

Tento prvek se používá k definování zpřístupnění pro rozšíření.



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

Tento prvek se používá k definování viditelnosti pro rozšíření.



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

Tento prvek představuje logickou operaci AND na výsledku vyhodnocení dvou výrazů jeho dílčích prvků.



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

Tento prvek představuje logickou operaci OR na výsledku vyhodnocení dvou výrazů jeho dílčích prvků.



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

Tento prvek představuje logickou operaci NOT na výsledku vyhodnocení výrazů jeho dílčích prvků.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení třídy nebo rozhraní každého objektu v aktuálním výběru. Pokud každý objekt ve výběru implementuje zadanou třídu nebo rozhraní, je výraz vyhodnocen jako true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení stavu atributu každého objektu v aktuálním výběru. Pokud má každý objekt ve výběru zadaný stav atributu, je výraz vyhodnocen jako pravdivý (true). Aby bylo možné vyhodnotit tento typ výrazu, musí se každý objekt ve výběru implementovat nebo přizpůsobit rozhraní org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Tento prvek se používá pro vyhodnocení stavu modulu plug-in. Stav modulu plug-in může být jeden z následujících: instalován (ekvivalentní stavu "vyřešený" v rámci konceptu OSGi) nebo aktivován (ekvivalentní stavu "aktivní" v rámci konceptu OSGi).



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení stavu některé vlastnosti systému. Hodnota vlastnosti je získána z java.lang.System.



V následujícím je uveden příklad akční sady (všimněte si podřízených prvků a způsobu použití atributů):

    

<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;Run XYZ Tool"

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>

Ve výše uvedeném příkladu zadaná akční sada, pojmenovaná "My Actions", není zpočátku viditelná v každé perspektivě, protože není zadán atribut visible.

Akce XYZ se objeví jako zaškrtávací políčko položky nabídky, původně nezaškrtnuté. Je aktivní pouze, pokud je počet výběrů 1 a pokud výběr obsahuje prostředek souboru Java.

Akce ABC se objeví v nabídce i na panelu nástrojů. Je aktivní pouze, pokud výběr neobsahuje žádné prostředky souboru Java. Všimněte si také, že se jedná o akci přecílení štítku, proto nedodává atribut class.

Akce DEF, GHI a JKL se objevují jako výběrová tlačítka položek nabídky. Jsou aktivní vždy, nezávisle na stavu aktuálního výběru.

Hodnota atributu třídy musí být plně kvalifikovaný název třídy, která implementuje org.eclipse.ui.IWorkbenchWindowActionDelegate nebo org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Druhá z obou možností by měla být implementována v případech, kdy má atribut style hodnotu pulldown. Tato třída je popisovač odpovědný za provádění akce. Pokud je atribut retarget true, je tento atribut ignorován a neměl by být poskytnut. Tato třída bude načtena co možná nejpozději, aby se zabránilo načtení celého modulu plug-in, dokud není skutečně potřebný.

Kritérium zpřístupnění rozšíření akce je zpočátku definováno parametrem enablesFor, a rovněž buď parametrem selection, nebo enablement. Jakmile je ovšem konkretizován delegát akce, může tento delegát řídit stav zpřístupnění akce přímo v rámci své metody selectionChanged.

Je důležité si povšimnout, že pracovní plocha negeneruje nabídky v zastoupení modulu plug-in. Cesty nabídek musí odkazovat na nabídky, které už existují.

Štítky akcí a nabídek mohou obsahovat speciální znaky se zakódovanou mnemotechnikou, pomocí následujících pravidel:

  1. Mnemotechnické informace jsou specifikovány pomocí znaku ampersand ('&') před vybraným znakem v přeloženém textu. Jelikož znak ampersand není v řetězcích XML povolen, použijte znakovou entitu &amp;.
Pokud jedno rozšíření přispívá do nabídky nebo do panelu nástrojů dvěma nebo více akcemi, budou tyto akce zobrazeny v opačném pořadí, než v jakém jsou uvedeny v souboru plugin.xml. Toto chování je takto navrženo. Nicméně bylo objeveno až po zafixování rozhraní API platformy Eclipse. Změna tohoto chování by tuto chvíli narušila všechny moduly plug-in, které jsou závislé na současném chování.

Prvky selection a enablement se navzájem vylučují. Prvek enablement může nahradit prvek selection pomocí dílčích prvků objectClass a objectState. Například následující:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

lze vyjádřit pomocí:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Moduly plug-in mohou použít tento bod rozšíření k přidání nových nabídek nejvyšší úrovně. Moduly plug-in mohou také definovat pojmenované skupiny, které umožní jiným modulům plug-in přispět k nim své akce.

Nabídky nejvyšší úrovně jsou vytvářeny použitím následujících hodnot atributu cesty (path):

Pokud není atribut cesty (path) zadán, bude nová nabídka přidána do skupiny pruhu nabídky přidání.

Výchozí skupiny v okně pracovní plochy jsou definovány v rozhraní IWorkbenchActionConstants. Tyto konstanty mohou být použity v kódu pro dynamický příspěvek. Hodnoty mohou být také zkopírovány do souboru XML pro jemně členěnou integraci s existujícími nabídkami a panelem nástrojů pracovní plochy.

Různé položky nabídek a panelu nástrojů v okně pracovní plochy jsou definovány algoritmicky. V těchto případech musí být k rozšíření okna použit oddělený mechanizmus. Například přidání nového pohledu pracovní plochy má za následek objevení nové položky nabídky v nabídce Perspektiva. Rozšíření Import, Export a Noví průvodci jsou do okna také přidána automaticky.