Menu podręczne

org.eclipse.ui.popupMenus

Ten punkt rozszerzenia umożliwia dodawanie nowych akcji do menu kontekstowych należących do innych modułów dodatkowych. Dodawane akcje mogą dotyczyć określonego typu obiektu (objectContribution) lub określonego menu kontekstowego części widoku lub edytora (viewerContribution). Jeśli używany jest element objectContribution, dodana akcja będzie wyświetlana we wszystkich menu kontekstowych części widoku lub edytora, w których wybrane są obiekty podanego typu. Natomiast użycie elementu viewerContribution spowoduje, że dodana akcja będzie wyświetlana tylko w podanym menu kontekstowym części widoku lub edytora, niezależnie od wyboru.

Jeśli wybór jest heterogeniczny, zarejestrowany dodany obiekt zostanie w miarę możliwości zastosowany do wspólnego typu występującego w wyborze. Jeśli bezpośrednie dopasowanie nie będzie możliwe, nastąpi próba dopasowania do nadklas i nadinterfejsów.

Wybór można dodatkowo ograniczyć przy użyciu filtru nazw. Jeśli użyto filtru, zastosowanie dodanego obiektu wymaga, aby do filtru pasowały wszystkie obiekty występujące w wyborze.

W poszczególnych akcjach dodawanego obiektu można użyć atrybutu enablesFor, aby określić, czy dana akcja dotyczy wyboru pojedynczego, wielokrotnego czy też innego typu.

Jeśli te mechanizmy filtrowania nie wystarczą, w dodawanej akcji można użyć mechanizmu filter. W takim przypadku atrybuty obiektu docelowego są opisane serią par nazwa-wartość. Atrybuty dające się zastosować do wyboru zależą od typu i wykraczają poza środowisko robocze, dlatego filtrowanie na tym poziomie jest delegowane przez środowisko robocze do bieżącego wyboru.

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 (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

Ten element służy do definiowania grupy akcji i/lub menu dla dowolnych menu kontekstowych przeglądarki, dla których wybierane są obiekty podanego typu.



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Ten element służy do definiowania grupy akcji i/lub menu dla określonego menu kontekstowego widoku lub edytora.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

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



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ten element służy do wartościowania stanu atrybutu każdego obiektu w bieżącym wyborze. Zgodność występuje tylko w przypadku, gdy każdy obiekt w wyborze ma określony stan atrybutu. Każdy obiekt w wyborze musi implementować interfejs org.eclipse.ui.IActionFilter lub przystosowywać się do niego.



<!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 punkt rozszerzenia menu podręcznego:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

<menu id=

"com.xyz.xyzMenu"

path=

"additions"

label=

"Narzędzia Java &amp;XYZ"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Uruchom narzędzie XYZ"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.XYZToolActionDelegate"

enablesFor=

"1"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Pokaż XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</viewerContribution>

</extension>

W powyższym przykładzie podana akcja uzupełnienia obiektu zostanie włączona tylko przy wyborze pojedynczym (atrybut enablesFor). Ponadto każdy obiekt w wyborze musi implementować podany interfejs (IFile) i być plikiem Java. Akcja ta zostanie dodana do wcześniej utworzonego podmenu. Uzupełnienie będzie obowiązywać w każdym widoku zawierającym wymagany wybór.

Natomiast przedstawione powyżej uzupełnienie przeglądarki będzie wyświetlane tylko w menu kontekstowym widoku Czynności i nie będzie zależeć od wyboru dokonanego w widoku.

Poniżej przedstawiono przykład mechanizmu filtru. W tym przypadku akcja będzie wyświetlana tylko dla ukończonych obiektów IMarkers o wysokim priorytecie.

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C3"

objectClass=

"org.eclipse.core.resources.IMarker"

>

<filter name=

"done"

value=

"true"

/>

<filter name=

"priority"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"Narzędzie akcji zakończenia z wysokim priorytetem"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Poniżej przedstawiono inny przykład, ilustrujący zastosowanie elementu visibility:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<viewerContribution id=

"com.xyz.C4"

targetID=

"org.eclipse.ui.views.TaskList"

>

<visibility>

<and>

<pluginState id=

"com.xyz"

value=

"activated"

/>

<systemProperty name=

"ADVANCED_MODE"

value=

"true"

/>

</and>

</visibility>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Pokaż XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

W powyższym przykładzie określona akcja zostanie wyświetlona jako element menu kontekstowego w widoku Czynności, ale tylko wtedy, gdy aktywny jest moduł dodatkowy com.xyz, a w określonej właściwości systemowej jest ustawiona wartość true.

Wartość atrybutu class elementu action musi być pełną nazwą klasy Java implementującej interfejs org.eclipse.ui.IObjectActionDelegate w przypadku uzupełniania obiektów, interfejs org.eclipse.ui.IViewActionDelegate w przypadku uzupełniania menu kontekstowych należących do widoków lub interfejs org.eclipse.ui.IEditorActionDelegate w przypadku uzupełniania menu kontekstowych należących do edytorów. We wszystkich przypadkach klasa implementująca jest ładowana możliwie najpóźniej, co pozwala uniknąć ładowania całego modułu dodatkowego, zanim będzie naprawdę potrzebny.

Uwaga: Aby zachować zgodność z wcześniejszymi wersjami, w przypadku uzupełniania obiektów można implementować interfejs org.eclipse.ui.IActionDelegate.

Rozszerzenie menu kontekstowego w określonej części jest możliwe tylko wtedy, gdy docelowa część publikuje menu do rozszerzenia. Jest to zdecydowanie zalecane, ponieważ poprawia rozszerzalność produktu. W tym celu każda część powinna publikować zdefiniowane menu kontekstowe przez wywołanie interfejsu IWorkbenchPartSite.registerContextMenu. Po wykonaniu tej czynności środowisko robocze automatycznie wstawi wszystkie istniejące rozszerzenia akcji.

Dla każdego zarejestrowanego menu należy podać jego identyfikator. Aby zachować spójność różnych części, wszystkich implementatorów części powinna obowiązywać poniższa strategia.

Każde menu kontekstowe rejestrowane w środowisku roboczym powinno także zawierać standardowy punkt wstawiania z identyfikatorem IWorkbenchActionConstants.MB_ADDITIONS. Inne moduły dodatkowe będą używać tej wartości jako punktu odwołania przy wstawianiu. Punkt wstawiania można zdefiniować przez dodanie znacznika GroupMarker do menu w odpowiednim położeniu wstawiania.

Obiekt w środowisku roboczym stanowiący wybór w menu kontekstowym może definiować interfejs org.eclipse.ui.IActionFilter. Jest to strategia umożliwiająca filtrowanie w oparciu o typ. Środowisko robocze pobiera filtr właściwy dla wyboru przez sprawdzenie, czy wybór ten implementuje interfejs IActionFilter. W przypadku niepowodzenia środowisko robocze zgłosi zapotrzebowanie na filtr przy użyciu mechanizmu IAdaptable.

Etykiety akcji i menu mogą zawierać znaki specjalne służące do kodowania mnemoników, które określa się przez umieszczenie znaku ampersand ('&') przed wybranym znakiem w przetłumaczonym tekście. Ponieważ znak ten jest niedozwolony w łańcuchach XML, należy skorzystać z encji &amp;.

Jeśli jedno rozszerzenie dodaje do menu dwie lub więcej akcji, akcje te są wyświetlane w kolejności odwrotnej niż wymieniono je 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 widokach środowiska roboczego znajdują się wbudowane menu kontekstowe, które zawierają już pewną liczbę akcji. Moduły dodatkowe mogą uzupełniać te menu. Jeśli w przeglądarce są zarezerwowane sekcje na takie obiekty uzupełniające i zostaną one upublicznione, nazw sekcji można użyć jako ścieżek. W przeciwnym razie akcje i podmenu zostaną dodane na końcu menu podręcznego.