Zbiory akcji

org.eclipse.ui.actionSets

Ten punkt rozszerzenia umożliwia dodawanie menu, opcji menu i przycisków paska narzędzi do wspólnych obszarów okna środowiska roboczego. Elementy te określa się zbiorczo jako zbiory akcji. Zbiory akcji są wyświetlane w oknie środowiska roboczego przez dostosowanie perspektywy przez użytkownika.

Dostępność i widoczność akcji można odpowiednio zdefiniować przy użyciu elementów enablement oraz visibility. Te dwa elementy zawierają wyrażenie boolowskie, od którego wartości zależy dostępność i/lub widoczność.

Składnia dla elementów enablement oraz visibility jest taka sama. Oba zawierają tylko jeden podelement w formie wyrażenia boolowskiego. W najprostszym przypadku będzie to element objectClass, objectState, pluginState lub systemProperty. W bardziej złożonych przypadkach można łączyć elementy and, or oraz not w celu utworzenia wyrażenia boolowskiego. Element and i element or muszą zawierać dwa podelementy. Element not musi zawierać tylko jeden podelement.

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

Ten element służy do definiowania grupy akcji i/lub menu.



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

Ten element definiuje akcję, którą można wywołać w interfejsie użytkownika.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Ten element służy do definiowania nowego menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Ten element służy do tworzenia separatora w nowym menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Ten element służy do tworzenia nazwanej grupy w nowym menu. W przeciwieństwie do elementu separator nie ma wizualnej reprezentacji w nowym menu.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Ten element służy do określania stanu akcji (włączona/wyłączona) na postawie bieżącego wyboru. Element ten jest ignorowany w razie podania elementu enablement.



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

Ten element służy do definiowania włączenia rozszerzenia.



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

Ten element służy do definiowania widoczności rozszerzenia.



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

Ten element reprezentuje boolowską operację AND wykonywaną na wyniku wartościowania wyrażeń stanowiących jego dwa podelementy.



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

Ten element reprezentuje boolowską operację OR wykonywaną na wyniku wartościowania wyrażeń stanowiących jego dwa podelementy.



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

Ten element reprezentuje boolowską operację NOT wykonywaną na wyniku wartościowania wyrażeń stanowiących jego podelementy.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Ten element służy do wartościowania klasy lub interfejsu każdego obiektu w bieżącym wyborze. Jeśli każdy obiekt w wyborze implementuje określoną klasę lub interfejs, wyrażenie otrzyma wartość true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ten element służy do wartościowania stanu atrybutu każdego obiektu w bieżącym wyborze. Jeśli każdy obiekt w wyborze ma określony stan atrybutu, wyrażenie otrzyma wartość true. Aby można było przeprowadzić wartościowanie tego typu wyrażenia, każdy obiekt w wyborze musi implementować interfejs org.eclipse.ui.IActionFilter lub dostosować się do niego.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Ten element służy do wartościowania stanu modułu dodatkowego. Stan modułu dodatkowego może mieć jedną z następujących wartości: installed (odpowiednik "resolved" w środowisku OSGi) lub activated (odpowiednik "active" w środowisku OSGi).



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ten element służy do wartościowania stanu wybranej właściwości systemowej. Wartość właściwości jest pobierana z obiektu typu java.lang.System.



Poniżej przedstawiono przykładowy zbiór akcji (należy zwrócić uwagę na podelementy oraz na sposób użycia atrybutów):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"Moje akcje"

>

<menu id=

"com.xyz.xyzMenu"

label=

"Menu XYZ"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Uruchom narzędzie XYZ"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Uruchom narzędzie XYZ"

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;Uruchom narzędzie ABC"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Uruchom narzędzie ABC"

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;Uruchom narzędzie DEF"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Uruchom narzędzie DEF"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Uruchom narzędzie GHI"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Uruchom narzędzie GHI"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Uruchom narzędzie JKL"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Uruchom narzędzie JKL"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

W powyższym przykładzie podany zbiór akcji o nazwie "Moje akcje" nie jest początkowo widoczny w każdej perspektywie, ponieważ atrybut visible nie jest określony.

Akcja XYZ będzie wyświetlana jako opcja menu w formie pola wyboru, początkowo niezaznaczonego. Będzie włączona tylko wtedy, gdy licznik wyboru wynosi 1, a wybór zawiera zasób pliku Java.

Akcja ABC pojawi się zarówno w menu, jak i na pasku narzędzi. Będzie włączona tylko wtedy, gdy wybór nie zawiera zasobu pliku Java. Należy również zauważyć, że jest to akcja umożliwiająca ponowne określenie celu etykiety, dlatego nie dostarcza atrybutu class.

Akcje DEF, GHI oraz JKL są wyświetlane jako opcje menu w formie przełączników. Są zawsze włączone, niezależnie od stanu bieżącego wyboru.

Wartość atrybutu klasy musi być pełną nazwą klasy Java implementującej interfejs org.eclipse.ui.IWorkbenchWindowActionDelegate lub org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Ten drugi powinien być zaimplementowany w przypadku, gdy atrybut style ma wartość pulldown. Ta klasa odpowiada za wykonanie akcji. Jeśli atrybut retarget ma wartość true, atrybut ten jest ignorowany i nie należy go podawać.Klasa ta jest ładowana możliwie najpóźniej, co pozwala uniknąć ładowania całego modułu dodatkowego, zanim będzie naprawdę potrzebny.

Kryteria decydujące o włączeniu lub wyłączeniu akcji są początkowo definiowane przez atrybuty enablesFor, a także przez selection albo enablement. Po utworzeniu instancji metody delegowanej akcji można jednak kontrolować stan włączenia akcji bezpośrednio w obrębie metody selectionChanged.

Należy zauważyć, że środowisko robocze nie generuje menu w zastępstwie modułu dodatkowego. Ścieżki menu muszą odwoływać się do menu, które już istnieją.

Etykiety akcji i menu mogą zawierać znaki specjalne, które umożliwiają kodowanie mnemoników przy użyciu następujących zasad:

  1. Mnemoniki określa się za pomocą znaku ampersand ("&") umieszczanego przed wybranym znakiem w przetłumaczonym tekście. Ponieważ znak ten jest niedozwolony w łańcuchach XML, należy skorzystać z encji &amp;.
W przypadku wprowadzenia dwóch lub większej liczby akcji do menu lub paska narzędzi przy użyciu pojedynczego rozszerzenia akcje te będą wyświetlane w kolejności odwrotnej do tej, w której są wymienione w pliku plugin.xml. To zachowanie jest nieintuicyjne. Niestety, zostało wykryte po "zamrożeniu" interfejsu API platformy Eclipse. Zmiana tego zachowania zakłóciłaby działanie wszystkich modułów dodatkowych, które polegają na obecnym zachowaniu.

Elementy selection i enablement wzajemnie się wykluczają. Element enablement może zastąpić element selection za pomocą podelementów objectClass oraz objectState. Na przykład wyrażenie:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

można oddać przy użyciu następującego wyrażenia:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Moduły dodatkowe mogą korzystać z tego punktu rozszerzenia w celu dodania nowych menu najwyższego poziomu. W modułach dodatkowych można także definiować nazwane grupy, które pozwalają innym modułom na dostarczanie do nich akcji.

Menu najwyższego poziomu tworzy się przy użyciu następujących wartości atrybutu ścieżki:

Pominięcie tego atrybutu ścieżki spowoduje dodanie nowego menu do grupy dodatków paska menu.

Domyślne grupy w oknie środowiska roboczego są zdefiniowane w ramach interfejsu IWorkbenchActionConstants. Stałe te mogą być używane w kodzie w sposób dynamiczny. Wartości można również kopiować do pliku XML w celu uzyskania precyzyjnej integracji z istniejącymi menu i paskiem narzędzi środowiska roboczego.

Różne opcje menu i paska narzędzi w obrębie okna środowiska roboczego definiuje się algorytmicznie. W takich sytuacjach do rozszerzenia okna wymagany jest oddzielny mechanizm. Przykładowo dodanie nowego widoku środowiska roboczego spowoduje wyświetlenie nowej opcji menu w menu Perspektywa. Do okna zostaną również automatycznie dodane rozszerzenia importu, eksportu i nowych kreatorów.