Menüs, Symbolleisten und Aktionen in Editoren
Kennung: org.eclipse.ui.editorActions
Beschreibung: An diesem Erweiterungspunkt können
Aktionen zu den Menü- und Symbolleisten von Editoren hinzugefügt
werden, die durch andere Plug-ins definiert werden.
Die anfängliche Ergänzungsgruppe für einen Editor wird durch einen
anderen Erweiterungspunkt
(org.eclipse.ui.editors)
definiert.
Ein Aktionsset wird erstellt und von allen Exemplaren desselben
Editortyps gemeinsam verwendet. Wenn sie aufgerufen wird, bezieht
sich diese Aktion auf den aktiven Editor.
Dieser Erweiterungspunkt folgt demselben Muster. Jede
Aktionserweiterung wird erstellt und von allen Exemplaren desselben
Editortyps gemeinsam benutzt. Die
Aktionsklasse muss
org.eclipse.ui.IEditorActionDelegate implementieren.
Der aktive Editor wird durch den Aufruf von
IEditorActionDelegate#setActiveEditor an den Stellvertreter
übergeben.
Konfigurationsbefehle:
<!ELEMENT editorContribution (menu | action)*>
<!ATTLIST editorContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - Eine eindeutige Kennung, mit der auf diese Ergänzung
verwiesen werden kann.
editorID: Die eindeutige Kennung eines zuvor registrierten
Editors, der das Ziel dieser Ergänzung ist.
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - Eine eindeutige Kennung, mit der auf dieses Menü
verwiesen werden kann.
-
label - Eine Textbezeichnung für das neue Menü. Diese Bezeichnung sollte
mnemonische Informationen enthalten.
-
path: Eine Position des Menüs, die von der Stammposition der
Menüleiste ausgeht. Wird dieses Attribut übergangen, wird das Menü
in der Menüleiste im Segment additions
eingefügt. Jedes Token im Pfad muss ein vorhandenes Menü in der
Workbench angeben. Hiervon ausgenommen ist das letzte Token, das eine
benannte Gruppe im letzten Menü im Pfad darstellt.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name: Ein Name des Trennzeichens, auf das später im
Aktionspfad als letztes Token verwiesen werden kann.
Trennzeichen
dienen daher als benannte Gruppen, in denen Aktionen
hinzugefügt werden können.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id: Eine eindeutige ID, mit der auf diese Aktion verwiesen
werden kann.
-
label: Ein umsetzbarer Name, der abhängig vom Kontext zu
unterschiedlichen Zwecken eingesetzt wird.
In Menüs wird er als Menütext verwendet. In Symbolleisten dient er
als Beschriftung für die Schaltfläche.
Die Beschriftung kann in JFace codierte mnemonische Informationen
sowie Angaben zum Direktaufruf enthalten (siehe Beispiel).
-
accelerator: Der Direktaufruf für die Aktion. Dieser wird als Kombination der
Tasten STRG, UMSCHALT und ALT sowie einer Direktaufruftaste angegeben. Diese Werte sind nicht
international verwendbar und dürfen nicht übersetzt werden. Die Spezifikation des Direktaufrufs
für den Eingangstitel muss in der Bezeichnung erfolgen - dieser Wert wird nicht zur Erstellung
eine Menüeintrags verwendet.
-
menubarPath: Ein durch Schrägstrich (/) begrenzter absoluter Pfad, mit
dem die Position der Aktion in der Menüleiste angegeben wird.
Der Pfad kann nur auf Menüs verweisen, die zum Zieleditor gehören.
Das letzte Token
stellt die benannte Trennzeichengruppe dar, in der die Aktion
hinzugefügt wird. Wenn der Pfad übergangen wird, wird die
Aktion nicht in der Menüleiste angezeigt.
-
toolbarPath: Ein durch Schrägstrich (/) begrenzter Pfad, mit
dem die Position der Aktion in der Symbolleiste angegeben wird. Das
erste Token stellt die ID der Symbolleiste dar (der Wert "Normal"
gibt die Standardsymbolleiste an). Das zweite Token ist die benannte
Gruppe in der Symbolleiste.
Wenn die Gruppe in der Symbolleiste nicht vorhanden ist, wird
sie erstellt.
Wenn das Attribut "toolbarPath" übergangen wird, wird die Aktion nicht angezeigt.
-
icon: Der relative Pfad eines Symbols, mit dem die Aktion in
ihrem Kontext optisch dargestellt wird.
Wenn dieses Attribut übergangen wird und die Aktion in der
Symbolleiste angezeigt werden soll, verwendet
die Workbench ein Platzhaltersymbol.
Der Pfad bezieht sich auf die
Position der Datei "plugin.xml" des Plug-ins, das die
Ergänzung bereitstellt.
-
disabledIcon: Der relative Pfad eines Symbols, mit dem die Aktion in
ihrem Kontext optisch dargestellt wird, wenn die Aktion inaktiviert wird.
Falls ausgelassen, wird das normale Symbol einfach nur abgeblendet (grau) dargestellt.
Der Pfad bezieht sich auf die
Position der Datei "plugin.xml" des Plug-ins, das die
Ergänzung bereitstellt.
-
hoverIcon: Der relative Pfad eines Symbols, mit dem die Aktion in
ihrem Kontext optisch dargestellt wird, wenn sich die Maus über dem Symbol befindet.
Falls ausgelassen, wird das normale Symbol verwendet.
Der Pfad bezieht sich auf die
Position der Datei "plugin.xml" des Plug-ins, das die
Ergänzung bereitstellt.
-
tooltip: Wird verwendet, falls die Aktion
in der Symbolleiste angezeigt werden soll. Andernfalls wird dieses
Attribut ignoriert.
-
helpContextId: Eine eindeutige Kennung, mit der die ID des
Hilfekontextes für diese Aktion angegeben wird. Wenn die Aktion als Menüoption angezeigt wird und hervorgehoben ist,
wird durch das Drücken der Taste F1 der Hilfetext für die
gegebene Kontext-ID aufgerufen.
-
state: Ein optionales Attribut, mit dem angegeben wird, dass
die Aktion eine Umschaltaktion sein soll.
Wenn eine solche Aktion zu einem Menü hinzugefügt wird,
manifestiert sie sich selbst mit einem Markierungsfeldelement.
Beim Hinzufügen zu einer Symbolleiste, wird sie als
Umschaltfläche dargestellt.
Wenn dieses Attribut definiert ist, wird der Attributwert als
Anfangsstatus (entweder true oder false) verwendet.
-
class: Der Name der vollständig qualifizierten Klasse, die org.eclipse.ui.IEditorActionDelegate implementiert.
-
enablesFor: Ein Wert für die Auswahlanzahl, die erreicht
werden muss, damit die Aktion aktiviert wird. Wenn dieses Attribut
angegeben ist und die Bedingung erfüllt wird, wird die Aktion
aktiviert. Wird die Bedingung nicht erfüllt, ist die Aktion
inaktiviert. Falls kein Attributwert angegeben wird, wird die Aktion
bei jeder beliebigen Anzahl von ausgewählten Elementen
aktiviert. Das Attribut unterstützt die folgenden Formate:
! - 0 ausgewählte Elemente
? - 0 oder 1 ausgewählte Elemente
+ - 1 oder mehr ausgewählte Elemente
multiple, 2+ - 2 oder mehr ausgewählte Elemente
n - Eine exakte Anzahl von ausgewählten Elementen (z. B.
4)
* - Eine beliebige Anzahl von ausgewählten Elementen
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class: Der vollständig qualifizierte Name einer Klasse oder
Schnittstelle, die jedes Objekt in der Auswahl als Unterklasse
enthalten oder implementieren muss, damit die Aktion aktiviert wird.
-
name: Ein Filter mit Platzhalterzeichen, der auf die Objekte
in der Auswahl optional angewendet werden kann. Wenn dieser Filter angegeben wird und keine Übereinstimmung vorliegt,
ist die Aktion inaktiviert.
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty
| pluginState)>
<!ATTLIST enablement EMPTY>
In Version 2.0 von Eclipse kann das Element enablement
verwendet werden, um die Aktivierung für die Aktion zu definieren. Weitere Informationen
zur Verwendung des Elements enablement finden Sie unter
actionExpressions.html.
Die in der Anfangseinstellung geltenden Aktivierungskriterien für
eine Aktionserweiterung werden durch
enablesFor,
selection und enablement definiert. Sobald der
Aktionsstellvertreter jedoch als Exemplar erstellt wurde, kann
er den Aktivierungsstatus einer Aktion direkt mit seiner Methode
selectionChanged steuern.
Aktions- und Menübezeichnungen können Sonderzeichen enthalten, die
mnemonische Zeichen und Direktaufrufzeichen gemäß
den folgenden Regeln codieren:
-
Mnemonische Zeichen werden angegeben, indem ein Et-Zeichen (&)
vor ein ausgewähltes Zeichen des umsetzbaren Textes gesetzt wird.
Da
das Et-Zeichen in XML-Zeichenfolgen nicht zulässig ist, muss
die Zeichenentität & verwendet werden.
-
Optionale Direktaufrufzeichen werden am Ende der Namenszeichenfolge
mit dem Zeichen @ angegeben, auf das eine Reihe von
Änderungswerte und das eigentliche Direktaufrufzeichen folgen
(Beispiel: &Speichern@Strg+S). Änderungswerte können
mit dem Zeichen + als Begrenzer verkettet werden (Beispiel.
@Strg+Umschalt+S).
Wenn zwei oder mehr Aktionen einem Menü oder einer Symbolleiste
durch eine einzige Erweiterung hinzugefügt werden sollen,
werden die Aktion in umgekehrter Reihenfolge (als in der Datei
plugin.xml aufgelistet) angezeigt. Dieses Verhalten ist nicht sehr intuitiv, wurde jedoch erst nach dem
Code-Freeze der Eclipse-Plattform-API festgestellt.
Würde dieses Verhalten jetzt geändert, wäre jedes Plug-in, das auf dem vorhandenen Verhalten aufbaut,
nicht funktionsfähig.
Beispiele:
Das folgende Beispiel stellt einen Erweiterungspunkt für eine
Editoraktion dar:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu id="XYZ"
label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="XYZ/group1"
toolbarPath="Normal/additions"
state="true"
icon="icons/runXYZ.gif"
tooltip="XYZ-Tool ausführen"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ">
</action>
</editorContribution>
</extension>
In diesem Beispiel wird die angegebene Aktion im neuen Menü der obersten Ebene namens "XYZ Menü" durch ein Markierungsfeldelement und in der Symbolleiste durch eine Umschaltfläche dargestellt.
Das folgende Beispiel stellt einen Erweiterungspunkt für eine
Editoraktion dar:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyz2Contribution"
targetID="com.ibm.XMLEditor">
<menu
id="XYZ2"
label="&XYZ2 Menu"
path="edit/additions">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ2"
label="&Run XYZ2 Tool"
menubarPath="edit/XYZ2/group1"
state="true"
icon="icons/runXYZ2.gif"
tooltip="Run XYZ2 Tool"
helpContextId="com.xyz.run_action_context2"
class="com.xyz.actions.RunXYZ2">
</action>
</editorContribution>
</extension>
In diesem Beispiel wird die angegebene Aktion im Untermenü namens "XYZ2 Menü" im Menü der obersten Ebene "Bearbeiten" durch ein Markierungsfeldelement dargestellt.
API-Informationen: Der Wert des Attributs
class muss der vollständig qualifizierte Name einer
Java-Klasse sein,
die org.eclipse.ui.IEditorActionDelegate implementiert.
Diese Schnittstelle wird so spät wie möglich geladen, um ein Laden
des Plug-ins zu verhindern, bevor es wirklich benötigt wird. Die Methode
setActiveEditor wird immer dann aufgerufen, wenn ein Editor
des angegebenen Typs aktiviert wird.
Für alle Exemplare des angegebenen Editortyps wird - ungeachtet der
Anzahl von Editorexemplaren, die gegenwärtig in der Workbench
geöffnet sind - nur 1 Set mit Aktionen und Menüs erstellt.
An diesem Erweiterungspunkt können Menüs, die zuvor durch den
Zieleditor erstellt wurden, durch Aktionen ergänzt werden.
Außerdem kann das Workbench-Fenster durch Aktionen und Menüs ergänzt
werden. Die Kennungen für die Aktionen und Hauptgruppen im
Workbench-Fenster sind
in org.eclipse.ui.IWorkbenchActionConstants definiert.
Sie sollten als Verweispunkt für das Hinzufügen neuer Aktionen
verwendet werden.
Menüs der höchsten Ebene werden erstellt, indem die folgenden Werte
für das Attribut path verwendet werden:
-
additions: Stellt eine Gruppe links neben dem Menü "Fenster"
dar.
Aktionen und Menüs, die zu diesen Pfaden hinzugefügt werden, werden
nur dann angezeigt, wenn der zugeordnete Editor aktiv ist.
Beim Schließen des Editors werden die Menüs und Aktionen entfernt.
Bereitgestellte Implementierung: Die Workbench
stellt einen integrierten Standardtexteditor zur Verfügung.
Plug-ins können diesen Standardeditor ergänzen wie auch Editoren, die
durch andere Plug-ins bereitgestellt werden.