Paden van menu's en werkbalken

In eerdere onderwerpen zijn al tal van acties aan bod gekomen waarvoor een pad is opgegeven. In dit onderwerp wordt uitgelegd wat de betekenis van deze paden is.

Menupaden

Eerst worden menupaden uitgelegd aan de hand van het menu Help in de workbench.

Benoemde groepen in de workbench

De locaties voor het invoegen van nieuwe menu's en menu-items worden middels benoemde groepen gedefinieerd. U kunt een benoemde groep beschouwen als een plaatshouder waarmee u menu-items kunt invoegen op bepaalde posities van een menubalk of keuzemenu.

In de workbench worden alle groepsnamen gedefinieerd in de klassen IWorkbenchActionConstants en IIDEActionConstants. (Er worden twee klassen gebruikt om aan resources verwante menu-items van de generieke workbench-items te scheiden.) Voor elk workbenchmenu worden benoemde groepen in het menu geplaatst op de posities waar plugins nieuwe acties zullen toevoegen.

De volgende beschrijving van het helpmenu is aangepast van de klassendefinitie IWorkbenchActionConstants.

   Standard Help menu actions
   Start group - HELP_START - "start"
   End group - HELP_END - "end"

Het standaard helpmenu van de workbench definieert de benoemde groepen "start" en "end,". Als u twee groepen definieert, kunnen plugins beter bepalen waar de toegevoegde acties in het helpmenu worden geplaatst. Het aantal gedefinieerde groepen voor een gedefinieerd menu is onbeperkt. Voegt u meer groepen toe, dan kunnen plugins beter bepalen op welke relatieve posities de items worden geplaatst ten opzichte van bestaande items.

Een plugin waarmee een menu-item wordt toegevoegd aan het helpmenu, kan deze groepsnamen gebruiken om de positie van het menu-item te bepalen. De hulpbladplugin voegt bijvoorbeeld een actieset met het menu "Hulpbladen..." toe aan de workbench. De markup van het bestand plugin.xml uit de plugin org.eclipse.ui.cheatsheets is als volgt:

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

De nieuwe helpactie wordt in de groep helpStart van het menu Help geplaatst.

Volledig gekwalificeerde menupaden

Een volledig menupad bestaat uit een "menunaam/groepsnaam". De meeste menunamen voor de workbench worden gedefinieerd in IWorkbenchActionConstants. (De aan resources verwante menunamen worden gedefinieerd in IIDEActionConstants.) Als we bijvoorbeeld de naam van het menu Help opzoeken in deze klasse, blijkt dat de volledig gekwalificeerde padnaam van de helpactie "help/helpEnd" is.

Voor menu's met geneste submenu's zijn langere paden nodig. Als voor het menu Help een submenu met de naam "submenu" en de benoemde groep "submenuStart" was gedefinieerd, zou het volledig gekwalificeerde pad van een actie in het nieuwe submenu "help/submenu/submenuStart" zijn.

Gebruikersinterfacelabels externaliseren

Het bovenstaande voorbeeld biedt een methode voor het externaliseren van tekenreeksen die in de gebruikersinterface worden gebruikt. Door middel van geëxternaliseerde tekenreeksen wordt het vertalen van gebruikersinterfacetekst van de plugin eenvoudiger. U kunt een tekenreeks in het bestand plugin.xml externaliseren door deze te vervangen door een sleutel (%CHEAT_SHEETS_MENU) en een vermelding in het bestand plugin.properties op te nemen:

	CHEAT_SHEETS_MENU = Hulpbladen...

Ook als u het bestand plugin.properties in meerdere talen vertaalt, hoeft u het bestand plugin.xml niet te wijzigen.

Nieuwe menu's en groepen toevoegen

De acties van een groot aantal eerder besproken voorbeeldplugins zijn aan bestaande benoemde groepen in menu's toegevoegd.

De extensiepunten actionSets, viewActions, editorActions en popupMenus stellen u in staat ook nieuwe menu's en groepen te definiëren. Met andere woorden: U kunt nieuwe sub- of keuzemenu's definiëren en er acties aan toevoegen. Het pad van de nieuwe acties moet de naam van het nieuwe menu bevatten.

Deze techniek is al eerder aan bod gekomen tijdens het definiëren van een nieuw menu voor de actieset van de readme-tool. Hieronder volgt de markup nogmaals:

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

Het label van het menu "org_eclipse_ui_examples_readmetool" is gedefinieerd onder de sleutel "%ActionSet.name" in het eigenschappenbestand. Voor het menu zijn drie benoemde groepen gedefinieerd: "slot1," "slot2" en "slot3". Het nieuwe menu wordt toegevoegd aan het pad "window/additions".

Als u IWorkbenchActionConstants raadpleegt, vindt u deze definitie van het menu Venster in Javadoc:

    * <h3>Standard Window menu actions</h3>
    * <ul>
    * <li>Extra Window-like action group (<code>WINDOW_EXT</code>)</li>

De klassendefinitie bevat bovendien deze verwante definities:

   public static final String MENU_PREFIX = "";
   ...
   public static final String M_WINDOW = MENU_PREFIX+"window";
   ...
   public static final String MB_ADDITIONS = "additions";  // Group.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Group.

Aan de hand van deze gegevens kan het pad worden samengesteld voor het toevoegen van nieuwe items aan het menu "Venster" van de workbench. De naam van het menu luidt "window" en bevat één groep met de naam "additions". Het pad voor het toevoegen van items aan dit nieuwe menu luidt "window/additions".

In de declaratie van de actieset wordt een actie toegevoegd aan het nieuwe menu met het pad "window/org_eclipse_ui_examples_readmetool/slot1".

Dit pad (of een andere groep) kan ook door andere plugins worden gebruikt voor het toevoegen van menu's.

Het kenmerk separator is in het voorbeeld van de readme-tool gebruikt voor het identificeren van de groepsnamen. Zo wordt een scheidingslijn tussen de groepen geplaatst (mits deze items bevatten). Als u het kenmerk groupMarker gebruikt, kunt u ook benoemde groepen definiëren, maar wordt de scheidingslijn niet afgebeeld.

Werkbalkpaden

Werkbalkpaden zijn vergelijkbaar met menupaden.

Benoemde werkbalken in de workbench

De algehele werkbalk van de workbench bestaat uit werkbalken die door diverse plugins en de workbench zelf worden aangeleverd. Een werkbalk bevat benoemde groepen waarin nieuwe werkbalkitems kunnen worden geplaatst.

De volgende beschrijving van de workbenchwerkbalken is aangepast van de klassendefinitie IWorkbenchActionConstants.

// ID's van workbenchwerkbalken
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate";

// ID's van groepen van workbenchwerkbalken. Voor het toevoegen van een item aan het begin van de groep,
// gebruikt u het GROUP-ID. Voor het toevoegen van een item aan het einde van de groep, gebruikt u het EXT-ID.
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"; 

In het eenvoudigste scenario wordt een werkbalkitem door een plugin aan de werkbalk van de plugin toegevoegd. De acties van de readme-tool die aan het menu worden toegevoegd, bevatten ook een werkbalkpad:

<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="readme"
...

Er is echter geen verwijzing naar de paden of groepen van de workbenchwerkbalk en daarom worden de acties in een eigen groep op de werkbalk geplaatst. Als u het volgende pad had opgegeven, zouden de items in de groep save van de werkbalk file zijn geplaatst:

...
<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="org.eclipse.ui.workbench.file/save.group"
...

In de werkbalkpaden of in andere plugins kunnen verwijzingen bestaan naar de paden die zijn gedefinieerd in IWorkbenchActionConstants.

Items toevoegen aan actiesets van andere plugins

Het kan wenselijk zijn een betere integratie te realiseren van de werkbalkitems van de ene plugin met de acties van een andere plugin. In het onderstaande fragment ziet u hoe de actie van de plugin voor externe tools (org.eclipse.ui.externaltools) wordt geïntegreerd met het foutopsporingsprogramma. De werkbalkacties van het foutopsporingsprogramma (org.eclipse.debug.ui) worden als volgt gedefinieerd:

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

Voor het foutopsporingsprogramma wordt net als voor de readme-tool een apart werkbalkpad gedefinieerd. Werkbalkitems worden dus op een afzonderlijke werkbalk in de workbench geplaatst. Hoe werkt de plugin voor externe tools?

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

Merk op hoe het actieset-ID van het foutopsporingsprogramma wordt gebruikt in het werkbalkpad. Doordat het ID van een actieset is ingesteld, wordt het werkbalkitem op de werkbalk geplaatst die wordt gebruikt door de actieset waarnaar wordt verwezen. De items worden in werkbalkgroepen op het actieset-ID gegroepeerd. In het bovenstaande voorbeeld wordt de actie voor externe tools dus achter de acties van het foutopsporingsprogramma geplaatst.

Als u items toevoegt aan de werkbalk van een actieset, kunt u ook nieuwe groepen definiëren. Als in de plugin voor externe tools het kenmerk toolbarpath was ingesteld op "org.eclipse.debug.ui.launchActionSet/external",zou een nieuwe groep voor de actie zijn gemaakt op de werkbalk. Net zoals menu's worden ook werkbalkgroepen van elkaar gescheiden door een lijn.

Paden uit andere plugins gebruiken

Over het algemeen is het niet verstandig menu's of werkbalken van andere plugins uit te breiden door het pad af te leiden uit plugin.xml, tenzij voor het pad expliciet is aangegeven dat het beschikbaar is voor clients. De paden kunnen namelijk gewijzigd worden in nieuwere versies van de plugins. Er zijn twee gangbare manieren om de ID's en paden van actiesets te markeren als 'gedeeld':