Wiele występujących do tej pory elementów wnoszonych akcji określało ścieżkę do położenia swojej akcji. Warto przyjrzeć się bliżej znaczeniu tych ścieżek.
Poniższy opis ścieżek menu oparto na przykładzie menu Pomoc środowiska roboczego.
Położenia, w których mają zostać wstawione nowe menu i pozycje menu, definiuje się za pomocą nazwanych grup. Nazwaną grupę można sobie wyobrazić jako sekcję lub obiekt zastępczy, który umożliwia wstawienie pozycji menu w pewnych punktach na pasku menu lub w menu rozwijanym.
Środowisko robocze definiuje wszystkie nazwy swoich sekcji grup w klasach IWorkbenchActionConstants i IIDEActionConstants. Używane są dwie różne klasy, ponieważ pozycje menu dotyczące zasobów są fabrykowane w ogólnym środowisku roboczym. Dla każdego menu środowiska roboczego nazwane grupy są umieszczane w tym menu w miejscach oczekiwanego wstawienia nowych akcji przez moduły dodatkowe.
Poniższy opis menu pomocy został zaadaptowany z definicji klasy IWorkbenchActionConstants.
Standardowe akcje menu Pomoc Start group - HELP_START - "start" End group - HELP_END - "end"
Standardowe menu pomocy środowiska roboczego definiuje nazwaną grupę "start", po której występuje nazwana grupa "end". Zdefiniowanie tych dwóch grup daje modułom dodatkowym pewien wpływ na to, gdzie zostaną umieszczone pozycje wnoszone do menu pomocy przez te moduły. Po zdefiniowaniu menu można zdefiniować dowolną liczbę sekcji. Dodanie większej liczby sekcji daje innym modułom dodatkowym większą kontrolę nad tym, gdzie zostaną umieszczone elementy wnoszone przez te moduły względem już istniejących elementów wnoszonych.
Moduły dodatkowe, które dodają pozycję do menu pomocy, mogą używać tych nazw grup, aby zdecydować, gdzie ma się znaleźć dodawana pozycja menu. Na przykład moduł dodatkowy ściągawki dodaje do środowiska roboczego zbiór akcji zawierający menu "Ściągawki". Oto kod znaczników z pliku plugin.xml modułu dodatkowego org.eclipse.ui.cheatsheets.
<extension point="org.eclipse.ui.actionSets"> <actionSet label="%CHEAT_SHEETS" visible="true" id="org.eclipse.ui.cheatsheets.actionSet"> <action label="%CHEAT_SHEETS_MENU" class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction" menubarPath="help/helpStart" id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction"> </action> </actionSet> </extension>
Nowa akcja w menu pomocy zostanie umieszczona wewnątrz grupy helpStart.
Kompletna ścieżka menu to po prostu "nazwa menu/nazwa grupy". Większość nazw menu dla środowiska roboczego jest definiowanych w klasie IWorkbenchActionConstants. Nazwy menu dotyczących zasobów są definiowane w klasie IIDEActionConstants. Gdyby poszukać nazwy menu pomocy w tej klasie, można by się przekonać, że pełna nazwa ścieżki dla wniesionej akcji to "help/helpEnd".
Niektóre menu mają zagnieżdżone podmenu. To tam można znaleźć dłuższe ścieżki. Gdyby w menu pomocy było zdefiniowane podmenu o nazwie "submenu" z nazwaną grupą "submenuStart", wówczas pełna nazwa ścieżki dla akcji w nowym podmenu byłaby następująca "help/submenu/submenuStart".
Powyższy przykład demonstruje technikę eksternalizacji łańcuchów występujących w interfejsie użytkownika. Eksternalizowane łańcuchy pozwalają uprościć proces tłumaczenia interfejsu użytkownika modułu dodatkowego na inne języki. Łańcuchy w plikach plugin.xml można eksternalizować, zastępując łańcuch kluczem (na przykład %CHEAT_SHEETS_MENU) i tworząc wpisy w pliku plugin.properties, które mają postać:
CHEAT_SHEETS_MENU = Ściągawki...
Plik plugin.properties można przetłumaczyć na różne języki, przy czym plik plugin.xml nie musi być wcale modyfikowany.
W wielu omawianych do tej pory przykładach akcje wnoszone przez przykładowe moduły dodatkowe były dodawane do nazwanych grup już istniejących w różnych menu.
Punkty rozszerzeń actionSets, viewActions, editorActions i popupMenus umożliwiają także definiowanie nowych menu i grup w ramach elementów wnoszonych. Oznacza to, że można definiować nowe podmenu lub nowe menu rozwijane i wnosić akcje do tych nowych menu. W takim przypadku ścieżka dla nowej akcji będzie zawierać nazwę nowo zdefiniowanego menu.
Technika ta została użyta w definicji nowego menu dla zbioru akcji wnoszonego przez narzędzie readme. Teraz, gdy już więcej wiadomo o ścieżkach menu, warto ponownie przyjrzeć się temu kodowi znaczników.
<extension point = "org.eclipse.ui.actionSets"> <actionSet id="org_eclipse_ui_examples_readmetool_actionSet" label="%ActionSet.name" visible="true"> <menu id="org_eclipse_ui_examples_readmetool" label="%ActionSet.menu" path="window/additions"> <separator name="slot1"/> <separator name="slot2"/> <separator name="slot3"/> </menu> <action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="readme" label="%ReadmeAction.label" tooltip="%ReadmeAction.tooltip" helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context" icon="icons/ctool16/openbrwsr.png" class="org.eclipse.ui.examples.readmetool.WindowActionDelegate" enablesFor="1"> <selection class="org.eclipse.core.resources.IFile" name="*.readme"> </selection> </action> ...
W kodzie tym dodano nowe menu o nazwie "org_eclipse_ui_examples_readmetool", którego etykieta jest określona przy użyciu klucza "%ActionSet.name" w pliku właściwości. W tym menu zdefiniowano trzy nazwane grupy: "slot1," "slot2" i "slot3". To nowe menu zostało dodane w miejscu określonym ścieżką "window/additions".
Gdyby wrócić do opisu klasy IWorkbenchActionConstants, taką definicję menu Okna byłoby widać w komentarzu Javadoc:
* <h3>Standardowe akcje menu Okna</h3> * <ul> * <li>Dodatkowa grupa akcji typu Okna (<code>WINDOW_EXT</code>)</li>
Szukając dalej w definicji klasy, można znaleźć definicje pokrewne:
public static final String MENU_PREFIX = ""; ... public static final String M_WINDOW = MENU_PREFIX+"window"; ... public static final String MB_ADDITIONS = "additions"; // Grupa. ... public static final String WINDOW_EXT = MB_ADDITIONS; // Grupa.
Na podstawie tych informacji można odtworzyć ścieżkę dodawania pozycji do menu "Okna" środowiska roboczego. Samo menu nazywa się "window" i definiuje jedną sekcję o nazwie "additions". Aby dodać nowe menu, należy użyć ścieżki "window/additions".
W deklaracji zbioru akcji do nowo zdefiniowanego menu dodawana jest akcja przy użyciu ścieżki "window/org_eclipse_ui_examples_readmetool/slot1".
Inne moduły dodatkowe mogą dodawać do tego menu własne menu przy użyciu tej samej ścieżki (lub na przykład jednej z pozostałych sekcji).
W przykładzie z narzędziem readme do identyfikacji nazw grup używany jest atrybut separator. Spowoduje to wyświetlenie linii oddzielającej między tymi grupami, gdy będą one zawierać pozycje menu. Zamiast niego można użyć atrybutu groupMarker, gdy chce się zdefiniować nazwaną grupę bez żadnych separatorów w menu oddzielających grupy.
Ścieżki pasków narzędzi działają podobnie do ścieżek menu.
Pasek narzędzi środowiska roboczego składa się z pasków narzędzi wnoszonych przez różne moduły dodatkowe, w tym przez samo środowisko robocze. W obrębie każdego paska narzędzi występują nazwane grupy, czyli sekcje, których można użyć do wstawienia nowych pozycji paska narzędzi.
Poniższy opis pasków narzędzi środowiska roboczego został zaadaptowany z definicji klasy IWorkbenchActionConstants.
// Identyfikatory pasków narzędzi środowiska roboczego public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file" public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; // Identyfikatory grup pasków narzędzi środowiska roboczego. Aby dodać pozycję na początku grupy, // użyj identyfikatora GROUP. Aby dodać pozycję na końcu grupy, użyj identyfikatora EXT. public static final String PIN_GROUP = "pin.group"; public static final String HISTORY_GROUP = "history.group"; public static final String NEW_GROUP = "new.group"; public static final String SAVE_GROUP = "save.group"; public static final String BUILD_GROUP = "build.group";
W najprostszym przypadku moduł dodatkowy może wnieść pozycję do swojego paska narzędzi. Na przykład akcjom narzędzia readme wnoszonym do menu są także przypisane ścieżki paska narzędzi:
<action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="readme" ...
Ponieważ nie ma odwołania do ścieżek ani grup paska narzędzi środowiska roboczego, akcje narzędzia readme są wyświetlane w swojej własnej grupie na pasku narzędzi. Określenie poniższej ścieżki spowodowałoby natomiast umieszczenie pozycji na pasku narzędzi Plik w grupie Zapisz:
... <action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="org.eclipse.ui.workbench.file/save.group" ...
Ścieżki zdefiniowane w klasie IWorkbenchActionConstants mogą być przywoływane w ścieżkach pasków narzędzi innych modułów dodatkowych.
W tej sekcji opisano sposób integracji pozycji paska narzędzi jednego modułu dodatkowego z akcjami z innego modułu dodatkowego. Przykład dotyczy integracji akcji modułu dodatkowego narzędzi zewnętrznych (org.eclipse.ui.externaltools) z paskiem narzędzi debugera. Debuger (org.eclipse.debug.ui) definiuje swój pasek narzędzi w następujący sposób:
<extension point="org.eclipse.ui.actionSets"> <actionSet label="%LaunchActionSet.label" visible="false" id="org.eclipse.debug.ui.launchActionSet"> ... <action toolbarPath="debug" id="org.eclipse.debug.internal.ui.actions.RunDropDownAction" hoverIcon="icons/full/ctool16/run_exc.png" class="org.eclipse.debug.internal.ui.actions.RunToolbarAction" disabledIcon="icons/full/dtool16/run_exc.png" icon="icons/full/etool16/run_exc.png" helpContextId="run_action_context" label="%RunDropDownAction.label" pulldown="true"> </action> ...
Podobnie jak narzędzie readme, moduł dodatkowy debugera definiuje własny pasek narzędzi, co oznacza, że jego pozycje paska narzędzi znajdą się na własnym pasku narzędzi tego modułu w środowisku roboczym. Co robi moduł dodatkowy narzędzi zewnętrznych?
<extension point="org.eclipse.ui.actionSets"> <actionSet id="org.eclipse.ui.externaltools.ExternalToolsSet" label="%ActionSet.externalTools" visible="true"> ... <action id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar" definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar" label="%Action.externalTools" toolbarPath="org.eclipse.debug.ui.launchActionSet/debug" disabledIcon="icons/full/dtool16/external_tools.png" icon="icons/full/etool16/external_tools.png" hoverIcon="icons/full/ctool16/external_tools.png" tooltip="%Action.externalToolsTip" pulldown="true" class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate"> </action> </actionSet> </extension>
Należy zwrócić uwagę na użycie identyfikatora zbioru akcji debugera w ścieżce paska narzędzi. Użycie identyfikatora zbioru akcji w ścieżce oznacza, że dana pozycja paska narzędzi powinna zostać umieszczona na pasku narzędzi używanym przez przywoływany zbiór akcji. W obrębie grupy paska narzędzi pozycje są uporządkowane według identyfikatora zbioru akcji, a więc w tym przykładzie akcje narzędzi zewnętrznych wystąpią po akcjach debugera.
Podczas dodawania pozycji do paska narzędzi danego zbioru akcji można także definiować nowe grupy. Gdyby w module dodatkowym narzędzi zewnętrznych atrybut toolbarpath został zdefiniowany jako "org.eclipse.debug.ui.launchActionSet/external", dla akcji na pasku narzędzi zostałaby utworzona nowa grupa. Podobnie jak w przypadku menu, grupy paska narzędzi są rozdzielane separatorami.
W ogólności nie jest dobrym zwyczajem wnoszenie pozycji do menu lub paska narzędzi innego modułu dodatkowego na podstawie nazwy ścieżki odczytanej z pliku plugin.xml, chyba że została ona specjalnie oznaczona jako dostępna dla klientów. Jest możliwe, że w przyszłej wersji modułu dodatkowego nazwy ścieżek mogą się zmienić. Dwa typowe sposoby poprawnego oznaczania identyfikatorów i ścieżek dla akcji modułu dodatkowego to: