Beschreibung: An diesem Erweiterungspunkt können neue Aktionen zu Kontextmenüs hinzugefügt werden, deren Eigner andere Plug-ins sind. Die Aktionsergänzung kann für einen spezifischen Objekttyp (objectContribution) oder für ein spezifisches Kontextmenü vorgenommen werden. Bei der Registrierung für einen Objekttyp wird die Ergänzung in allen Anzeigefunktionen angezeigt, in denen Objekte des angegebenen Typs ausgewählt sind. Im Gegensatz hierzu bewirkt die Registrierung für ein Kontextmenü, dass die Aktion - unabhängig von der Auswahl - nur im angegebenen Menü angezeigt wird.
Bei einer heterogenen Auswahl wird die Ergänzung angewendet, wenn sie für einen allgemeinen Typ der Auswahl registriert wurde (sofern möglich). Falls eine direkte Übereinstimmung nicht vorhanden ist, wird versucht, in Superklassen und Superschnittstellen eine Übereinstimmung zu finden.
Die Auswahl kann durch die Verwendung eines Namensfilters weiter eingeschränkt werden. In diesem Fall müssen alle Objekte in der Auswahl mit dem Filter übereinstimmen, damit die Ergänzung angewendet wird.
Einzelne Aktionen in einer Objektergänzung können mit dem Attribut enablesFor angeben, ob sie nur bei einer einzelnen Auswahl, bei einer Mehrfachauswahl oder bei einem anderen Auswahltyp gültig sein sollen.
Wenn diese Filtermechanismen ungeeignet sind, kann eine Aktionsergänzung den Mechanismus filter verwenden. In diesem Fall werden die Attribute des Zielobjekts in einer Reihe von Schlüssel-/Wertpaaren beschrieben. Die auf die Auswahl angewendeten Attribute sind typspezifisch und gelten über die Domäne der Workbench selbst hinaus. Die Workbench delegiert die Filterung auf dieser Stufe daher an die tatsächliche Auswahl.
Konfigurationsbefehle:
<!ELEMENT objectContribution (filter | menu | action)*>
<!ATTLIST objectContribution
id
CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
>
<!ELEMENT action EMPTY>name: Der Name des Trennzeichens, auf das später als letztes Token im Aktionspfad verwiesen werden kann. Trennzeichen dienen daher als benannte Gruppen, in denen Aktionen hinzugefügt werden können.
Aktions- und Menübezeichnungen können Sonderzeichen enthalten, die mnemonische Zeichen und Direktaufrufzeichen gemäß den folgenden Regeln codieren:
Das folgende Beispiel ist ein Erweiterungspunkt für ein Kontextmenü:
<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="&XYZ-Java-Tools">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&XYZ-Tool ausführen"
menubarPath="com.xyz.xyzMenu/group1"
icon="icons/runXYZ.gif"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.XYZToolActionDelegate"
enablesFor="1">
</action>
</objectContribution>
<viewerContribution
id="com.xyz.C2"
targetID="org.eclipse.ui.views.TaskList">
<action
id="com.xyz.showXYZ"
label="&XYZ anzeigen"
menubarPath="additions"
icon="icons/showXYZ.gif"
helpContextId="com.xyz.show_action_context"
class="com.xyz.actions.XYZShowActionDelegate">
</action>
</viewerContribution>
</extension>
Im oben dargestellten Beispiel wird die angegebene Aktion nur bei einer Einzelauswahl aktiviert (Attribut enablesFor). Außerdem muss jedes Objekt in der Auswahl die angegebene Schnittstelle (IFile) implementieren und eine Java-Datei sein. Diese Aktion wird zu einem zuvor erstellten Untermenü hinzugefügt. Die Ergänzung ist in allen Sichten wirksam, in denen die erforderliche Auswahl vorhanden ist.
Im Gegensatz dazu wird die oben dargestellte Ergänzung der Anzeigefunktion nur in der Sicht "Tasks" angezeigt und durch die Auswahl in der Sicht nicht beeinflusst.
Das folgende Beispiel veranschaulicht den Filtermechanismus. In diesem Fall wird die Aktion nur für Objekte des Typs "IMarkers" angezeigt, die als abgeschlossen und mit hoher Priorität definiert wurden.
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
objectClass="org.eclipse.core.resources.IMarker">
<filter name="done"
value="true"/>
<filter name="priority"
value="2"/>
<action id="com.xyz.runXYZ"
label="Tool für abgeschlossene Aktion mit hoher Priorität"
icon="icons/runXYZ.gif"
class="com.xyz.actions.MarkerActionDelegate">
</action>
</objectContribution>
</extension>
API-Informationen: Der Wert des Aktionsattributs class muss der vollständig qualifizierte Klassenname einer Java-Klasse sein, die org.eclipse.ui.IObjectActionDelegate (bei Objektergänzungen), org.eclipse.ui.IViewActionDelegate (bei Ergänzungen für Anzeigefunktionen, die zu Sichten gehören) oder org.eclipse.ui.IEditorActionDelegate (bei Ergänzungen für Anzeigefunktionen, die zu Editoren gehören) implementieren. In allen Fällen wird die implementierende Klasse so spät wie möglich geladen, damit das gesamte Plug-in erst dann geladen wird, wenn es wirklich benötigt wird.
Hinweis: Um eine Abwärtskompatibilität zu ermöglichen, kann org.eclipse.ui.IActionDelegate für Objektergänzungen implementiert werden.
Die Kontextmenüerweiterung in einer Komponente ist nur dann möglich, wenn die Zielkomponente ein Menü zur Erweiterung publiziert. Dies wird dringend empfohlen, da es die Erweiterbarkeit des Produkts verbessert. Zu diesem Zweck sollte jede Komponente alle definierten Kontextmenüs durch einen Aufruf von IWorkbenchPartSite#registerContextMenu publizieren. Sobald dies ausgeführt wurde, fügt die Workbench automatisch alle vorhandenen Aktionserweiterungen ein.
Für jedes registrierte Menü muss eine Menü-ID angegeben werden. Damit eine komponentenübergreifende Konsistenz gewährleistet wird, sollten alle Implementierungselemente die folgende Strategie verwenden:
Ein Objekt in der Workbench, das die Auswahl in einem Kontextmenü ist, kann ein Element org.eclipse.ui.IActionFilter definieren. Diese Filterungsstrategie kann typspezifische Filterungen ausführen. Die Workbench ruft den Filter für die Auswahl ab, indem sie testet, ob die Schnittstelle IActionFilter implementiert ist. Verläuft dieser Versuch erfolglos, fordert die Workbench über den Mechanismus IAdaptable einen Filter an.
Bereitgestellte Implementierung: Die Workbench-Sichten enthalten integrierte Kontextmenüs, die bereits mit einer Reihe von Aktionen ausgeliefert werden. Plug-ins können Ergänzungen für diese Menüs definieren. Wenn eine Anzeigefunktion Segmente für diese Ergänzungen reserviert hat und diese publiziert werden, können die Namen der Segmente als Pfadwerte verwendet werden. Andernfalls werden Aktionen und Untermenüs am Ende des Kontextmenüs hinzugefügt.