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 die Delegierung
ü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 Textmarke für das neue Menü. Diese Marke 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)*>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
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 übersetzbarer 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).
-
menubarPath: Ein durch Schrägstrich (/) begrenzter 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
in der Menüleiste 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.
-
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.
Die in der Anfangseinstellung geltenden Aktivierungskriterien für
eine Aktionserweiterung werden durch enablesFor und
selection definiert. Sobald die Aktionsdelegierung jedoch
als Exemplar erstellt wurde, kann sie den Aktivierungsstatus
einer Aktion
direkt mit ihrer 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 übersetzbaren 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 Änderungswerten und das eigentliche Direktaufrufzeichen folgen
(Beispiel: &Speichern@Strg+S). Änderungswerte können
mit dem Zeichen + als Begrenzer verkettet werden (Beispiel.
@Strg+Umschalt+S).
Beispiele:
Im Folgenden ist ein Beispiel eines Erweiterungspunkts für
eine Editoraktion dargestellt:
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu
id="com.xyz.xyzMenu" label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
state="true"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ">
</action>
</editorContribution>
</extension>
In diesem Beispiel wird die angegeben Aktion im Menü durch ein
Markierungsfeldelement und in der Symbolleiste durch eine
Umschaltfläche 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.