Menu, paski narzędzi i akcje edytora

org.eclipse.ui.editorActions

Ten punkt rozszerzenia umożliwia dodawanie akcji do menu i paska narzędzi w edytorach zarejestrowanych przez inne moduły dodatkowe.

Początkowy zestaw elementów dodatkowych dla edytora jest zdefiniowany w innym punkcie rozszerzenia (org.eclipse.ui.editors). Tworzony jest jeden zestaw akcji współużytkowany przez wszystkie instancje tego samego typu edytora. Po wywołaniu akcje te działają w aktywnym edytorze. Prawidłowość ta obowiązuje również w tym punkcie rozszerzenia. Każde utworzone rozszerzenie akcji jest współużytkowane przez wszystkie wystąpienia tego samego typu edytora. Klasa akcji musi implementować interfejs org.eclipse.ui.IEditorActionDelegate. Aktywny edytor jest przekazywany do delegata przez wywołanie metody IEditorActionDelegate.setActiveEditor.

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

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



<!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) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      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ład rozszerzenia akcji edytora:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"Menu &amp;XYZ"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Uruchom narzędzie XYZ"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Uruchom narzędzie XYZ"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</editorContribution>

</extension>

W powyższym przykładzie określona akcja zostanie wyświetlona jako pole wyboru w menu najwyższego poziomu o nazwie Menu XYZ oraz jako przycisk przełącznika na pasku narzędzi. Akcja jest włączana tylko wtedy, gdy w wyborze znajdują się wyłącznie zasoby plików Java.

Poniżej przedstawiono inny przykład rozszerzenia akcji edytora:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"Menu &amp;XYZ2"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Uruchom narzędzie XYZ2"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Uruchom narzędzie XYZ2"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</editorContribution>

</extension>

W powyższym przykładzie określona akcja zostanie wyświetlona jako element podmenu o nazwie Menu XYZ2, znajdującego się w menu najwyższego poziomu o nazwie Edycja. Akcja jest włączana, gdy wybór nie zawiera zasobów plików Java.

Wartość atrybutu class musi być pełną nazwą klasy Java implementującej interfejs org.eclipse.ui.part.IEditorActionDelegate. Klasa ta jest ładowana możliwie najpóźniej, co pozwala uniknąć ładowania całego modułu dodatkowego, zanim będzie naprawdę potrzebny. Metoda setActiveEditor będzie wywoływana za każdym razem, gdy aktywowany będzie edytor podanego typu. Dla wszystkich instancji podanego typu edytora tworzony jest tylko jeden zestaw akcji i menu, niezależnie od liczby instancji edytora otwartych aktualnie w środowisku roboczym.

Ten punkt rozszerzenia umożliwia dodawanie akcji do menu utworzonych uprzednio przez edytor docelowy. Dodatkowo możliwe jest dodawanie menu i akcji do okna środowiska roboczego. Identyfikatory akcji i ważniejszych grup w oknie środowiska roboczego są zdefiniowane w interfejsie org.eclipse.ui.IWorkbenchActionConstants. Należy ich używać jako punktu odniesienia przy dodawaniu nowych 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.

Akcje i menu dodane do tych ścieżek będą widoczne tylko wtedy, gdy aktywny jest powiązany z nimi edytor. Po zamknięciu edytora menu i akcje zostaną usunięte.

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.

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>

W środowisku roboczym udostępniany jest wbudowany Domyślny edytor tekstu. Moduły dodatkowe mogą uzupełniać ten edytor domyślny lub edytory udostępniane przez inne moduły dodatkowe.