Menü- und Symbolleistenpfade

Sie haben bereits viele Aktionsergänzungen kennen gelernt, die den Pfad für die Position der Aktion angeben. Die Bedeutung dieser Pfade soll im Folgenden näher erläutert werden.  

Menüpfade

Zunächst werden die Menüpfade anhand des Workbenchmenüs Hilfe erläutert.

Benannte Gruppen in der Workbench

Die Positionen für das Einfügen neuer Menüs und Menüoptionen werden durch benannte Gruppen definiert. Eine benannte Gruppe ist mit einem Segment oder einem Platzhalter vergleichbar, mit dessen Hilfe die Menüoptionen an einer bestimmten Stelle in einer Menüleiste oder einem Pulldown-Menü eingefügt werden können.

Die Workbench definiert alle Namen von Gruppensegmenten in den Klassen IWorkbenchActionConstants und IIDEActionConstants. (Zwei verschiedene Klassen werden verwendet, da ressourcenbezogene Menüpunkte aus der generischen Workbench herausfaktoriert werden). In allen Workbench-Menüs werden benannte Gruppen an den Stellen platziert, an denen zu erwarten ist, dass Plug-ins neue Aktionen einfügen.

Die folgende Beschreibung des Menüs "Hilfe" stammt aus der Klassendefinition IWorkbenchActionConstants.

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

Das Workbench-Menü "Hilfe" definiert in der Standardeinstellung eine benannte Gruppe namens "start", auf die eine benannte Gruppe namens "end" folgt. Durch die Definition von zwei Gruppen erhalten die Plug-ins ein höheres Maß an Steuerungsmöglichkeiten über die Positionierung der ergänzten Elemente innerhalb des Hilfemenüs. Wenn Sie ein Menü definieren, können Sie beliebig viele Segmente angeben. Durch das Hinzufügen weiterer Platzhalter können andere Plug-ins besser steuern, wo deren Ergänzungen in Bezug auf vorhandene Ergänzungen angezeigt werden sollen.

Plug-ins, die dem Menü "Hilfe" einen Menüpunkt hinzufügen, können diese Gruppennamen verwenden, um zu entscheiden, an welcher Stelle ihr Menüpunkt eingefügt werden soll. Das Spickzettel-Plug-in fügt beispielsweise in die Workbench ein Aktionsset ein, das das Menü "Spickzettel..." enthält.  Das folgende Befehlformat stammt aus org.eclipse.ui.cheatsheets aus der Datei plugin.xml des Plug-ins.

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

Die neue Hilfeaktion wird in die Gruppe helpStart des Hilfemenüs gestellt.

Vollständig qualifizierte Menüpfade

Eine vollständige Menüpfadangabe hat folgendes Format: "menu name/group name."  Die meisten Menünamen für die Workbench werden unter IWorkbenchActionConstants definiert. (Ressourcenbezogene Menünamen werden in IIDEActionConstants definiert.) Eine Untersuchung des Namens des Hilfemenüs in dieser Klasse ergibt, dass der vollständig qualifizierter Pfadname für die Hilfeaktion "help/helpEnd" lautet.

Manche Menüs enthalten verschachtelte Untermenüs. An dieser Stelle kommen längere Pfade ins Spiel. Wenn im Hilfemenü ein Untermenü namens Untermenü mit einer benannten Gruppe namens submenuStart definiert wäre, würde der vollständig qualifizierte Menüpfad für eine Aktion im neuen Untermenü help/submenu/submenuStart lauten.

Bezeichnungen von Benutzerschnittstellen auslagern

Das oben beschriebene Beispiel zeigt ein Verfahren, mit dem Zeichenfolgen, die in der Benutzerschnittstelle angezeigt werden, ausgelagert werden können.  Das Auslagern von Zeichenfolgen vereinfacht das Übersetzen der Benutzerschnittstelle des Plug-ins in andere Sprachen. Die Zeichenfolgen in der Datei plugin.xml können ausgelagert werden, indem die Zeichenfolgen durch einen Schlüssel (z. B. %CHEAT_SHEETS_MENU) ersetzt und in der Datei plugin.properties Einträge mit dem folgenden Format erstellt werden:

	CHEAT_SHEETS_MENU = Cheat Sheets...

Auf diese Weise kann die Datei plugin.properties in unterschiedliche Sprachen übersetzt werden, ohne dass die Datei plugin.xml geändert werden muss.

Neue Menüs und Gruppen hinzufügen

In vielen der bislang dargestellten Beispiele wurden die Aktionen, die durch die Beispiel-Plug-ins ergänzt wurden, zu vorhandenen benannten Gruppen in Menüs hinzugefügt.

Über die Erweiterungspunkte actionSets, viewActions, editorActions und popupMenus können außerdem neue Menüs und Gruppen in einer Ergänzung definiert werden. Das bedeutet, dass Sie neue Untermenüs oder neue Pull-down-Menüs definieren und Ihre Aktionen zu diesen Menüs hinzufügen können. In diesem Fall enthält der Pfad für die neue Aktion den Namen des neu definierten Menüs.

Diese Technik wurde bereits angewandt, als das Tool für Readme-Dateien ein neues Menü für sein Aktionsset definierte. Da Sie sich jetzt ausführlicher mit Menüpfaden beschäftigt haben, soll die entsprechende Befehlsdatei hier noch einmal betrachtet werden.

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

Wir haben ein neues Menü mit dem Namen  "org_eclipse_ui_examples_readmetool" hinzugefügt, dessen Bezeichnung in der Eigenschaftsdatei mit dem Schlüssel "%ActionSet.name" definiert wird. In diesem Menü werden die drei benannten Gruppen  "slot1", "slot2" und "slot3" definiert.  Das neue Menü wird zum Pfad "window/additions" hinzugefügt.

Wenn Sie zu IWorkbenchActionConstants zurückgehen, wird diese Definition des Fenstermenüs (window) im Javadoc angezeigt:

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

Bei genauerer Betrachtung der Klassendefinition können diese zugehörigen Definitionen festgestellt werden:

   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.

Aus diesen Informationen können Sie den Pfad zusammensetzen, den Sie beim Hinzufügen einer Option zum Workbench-Menü "Fenster" benötigen. Das Menü selbst heißt window, es definiert ein Segment namens additions. Daher wird zum Hinzufügen eines eigenen neuen Menüs der Pfad window/additions verwendet.

In der Deklaration des Aktionsset wird unter Verwendung des Pfads window/org_eclipse_ui_examples_readmetool/slot1 eine Aktion zum neu definierten Menü hinzugefügt.

Andere Plug-ins könnten dieses Menü durch die Verwendung desselben Pfads (oder auch über eines der anderen Segmente) um ein eigenes Menü ergänzen.  

Im Beispiel des Tools für Readme-Dateien wird das Attribut separator verwendet, um die Gruppennamen anzugeben. Dies bewirkt, dass zwischen diesen Gruppen eine Trennlinie angezeigt wird, wenn sie Optionen enthalten. Wenn stattdessen eine benannte Gruppe ohne das Anzeigen einer Trennung im Menü zur Unterscheidung der Gruppen erstellt werden soll, kann zu diesem Zweck das Attribut groupMarker verwendet werden.

Symbolleistenpfade

Symbolleistenpfade funktionieren ähnlich wie Menüpfade.  

Benannte Symbolleisten in der Workbench

Die Workbench-Symbolleiste besteht aus Symbolleisten, die durch unterschiedliche Plug-ins ergänzt werden, zu denen auch die Workbench selbst gehört.  In jeder Symbolleiste gibt es benannte Gruppen oder Segmente, in die neue Symbolleistenoptionen eingefügt werden können.    

Die folgende Beschreibung der Workbench-Symbolleisten stammt aus der Klassendefinition IWorkbenchActionConstants.

// Workbench toolbar ids
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; 

// Workbench toolbar group ids.  To add an item at the beginning of the group, 
// use the GROUP id.  To add an item at the end of the group, use the 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"; 

Im einfachsten Fall kann ein Plug-in eine Symbolleistenoption als eigene Symbolleiste ergänzen. Beispielsweise werden auch die Aktionen des Tools für Readme-Dateien, die das Menü ergänzen, mit einem Symbolleistenpfad versehen:

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

Da es keinen Verweis auf die Symbolleistenpfade oder -gruppen der Workbench gibt, werden die Aktionen für Readme-Dateien in einer eigenen Gruppe auf der Symbolleiste angezeigt. Wenn stattdessen der folgenden Pfad angegeben würde, befände sich die Option in der Gruppe "Speichern" der Symbolleiste für Dateien:

...
<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 den Symbolleistenpfaden anderer Plug-ins kann auf die Pfade verwiesen werden, die in IWorkbenchActionConstants definiert sind.

Aktionssets zu anderem Plug-in hinzufügen

Im Folgenden wird davon ausgegangen, dass ein Plug-in seine Symbolleistenoptionen besser in die Aktionen eines anderen Plug-ins integrieren soll. Am Beispiel des Plug-ins für externe Tools (org.eclipse.ui.externaltools) wird veranschaulicht, wie dessen Aktionen in die Symbolleiste des Debuggers integriert werden.  Der Debugger (org.eclipse.debug.ui) definiert eigene Symbolleistenaktionen wie die Folgenden:

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

Wie auch das Tool für Readme-Dateien definiert das Debugger-Plug-in einen eigenen Symbolleistenpfad. Dies bedeutet, dass seine Symbolleistenoptionen in der Workbench in einer eigenen Symbolleiste angezeigt werden. Der folgende Ausschnitt zeigt, wie dieser Aspekt vom Plug-in für externe Tools realisiert wird:

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

Bitte beachten Sie die Verwendung der Aktionsset-ID des Debuggers im Pfad der Symbolleiste. Durch die Verwendung einer Aktionsset-ID im Pfad wird angegeben, dass die Symbolleistenoption in diejenige Symbolleiste gestellt werden soll, die durch das Aktionsset verwendet wird, auf das verwiesen wird.  Innerhalb einer Symbolleistengruppe werden die Optionen anhand der Aktionsset-ID sortiert. Im vorliegenden Beispiel werden daher die Aktionen für externe Tools nach den Debuggeraktionen angezeigt. 

Wenn Sie Optionen zur Symbolleiste eines Aktionssets hinzufügen, können außerdem neue Gruppen definiert werden. Falls das Plug-in für externe Tools sein Attribut toolbarpath mit "org.eclipse.debug.ui.launchActionSet/external" definieren würde, würde für die Aktion eine neue Gruppe in der Symbolleiste erstellt werden. Symbolleistengruppen werden wie Menüs durch Trennzeichen voneinander getrennt. 

Pfade aus anderem Plug-in verwenden

Im Allgemeinen ist es nicht besonders sinnvoll, ein Menü oder eine Symbolleiste eines anderen Plug-ins zu ergänzen, indem der Pfadname aus der Datei plugin.xml abgeleitet wird (es sei denn, dass dieser speziell als für Clients verfügbar gekennzeichnet wurde), denn es ist möglich, dass die Namen der Pfade in einer zukünftigen Version des Plug-ins geändert werden.  Es gibt jedoch zwei Möglichkeiten, mit denen Sie die Aktionsset-IDs und Pfade Ihres Plug-ins so kennzeichnen können, dass sie von anderen Plug-ins verwendet werden dürfen: