Aktionssets
Kennung: org.eclipse.ui.actionSets
Beschreibung: An diesem Erweiterungspunkt können
Menüs, Menüoptionen und Symbolleistenschaltflächen zu den gemeinsamen
Bereichen im Workbench-Fenster hinzugefügt werden.
Diese Ergänzungen werden zusammengefasst als Aktionsset
bezeichnet. Ihre Anzeige im Workbench-Fenster ist von den
Benutzervorgaben abhängig.
Konfigurationsbefehle:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id: Ein eindeutiger Name, der dieses Aktionsset kennzeichnet.
-
label: Ein umsetzbarer Name, der dieses Aktionsset im Menü des
Workbench-Fensters darstellt.
-
visible: Ein wahlfreies Attribut, mit dem angegeben wird, ob
das Aktionsset in der Anfangseinstellung in allen Perspektives. Diese Option
tritt nur dann in Kraft, wenn der Benutzer eine neue Perspektive, die noch nicht angepasst wurde,
öffnet. Der Benutzer kann diese Option im Dialog
"Perspektive anpassen" außer Kraft setzen.
-
description: Ein optionales Unterelement, dessen Hauptteil
einen Text als Kurzbeschreibung des Aktionsset enthalten sollte.
<!ELEMENT menu (separator)+ (groupMarker)*>
<!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 vor dem MEnü "Fenster" 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 sein sollte.
<!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 und
Untermenüs hinzugefügt werden können.
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name: Ein Name für die Gruppenmarkierung, auf den später im
Aktionspfad als letztes Token verwiesen werden kann.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
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
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
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: Eine ganze Zahl (Integer), die dazu verwendet wird, den Schlüsselcode
des Direktaufrufs für die Aktion anzugeben. Dies ist der Integer-Wert, der aus einem
bitweisen OR von null oder mehr SWT-Schlüsseländerungsmasken (d.h. SWT.CTRL oder SWT.ALT)
und einem Zeichencode resultiert. Beispiel: für Strg+Z verwenden Sie SWT.CTRL | 'Z' =
(1<<18)|'Z' = 262234.
-
definitionId - Die in der Aktionsdefinition angegebene ID. Nur dann erforderlich, wenn ein Aktionsset Direktaufrufe über den Tastenbelegungsservice angibt. Siehe
the extension points Aktionsdefinitionen
und Direktaufrufsets
-
menubarPath: Ein durch Schrägstrich (/) begrenzter Pfad, mit
dem die Position der Aktion in der Menüleiste angegeben wird.
Jedes Token im Pfad muss - mit Ausnahme des letzten Tokens - die
gültige ID eines in der Hierarchie vorhandenen Menüs angeben.
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.
Wird das Attribut "toolbarPath" übergangen, wird die Aktion nicht in
der Symbolleiste 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.
Dieses Symbol erscheint in Symbolleisten, aber nicht in Menüs. Aktivierte Aktionen werden
in Menüs durch hoverIcon dargestellt.
-
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.
Das inaktivierte Symbol erscheint in Symbolleisten, aber nicht in Menüs. Symbole für inaktivierte
Aktionen werden durch das jeweilige Betriebssystem bereit gestellt.
-
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: Ein Wert für den QuickInfo-Text, 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. Dieses Attribut
und das Attribut
pulldown schließen sich gegenseitig aus.
-
pulldown: Ein optionales Attribut, mit dem angegeben wird,
dass die Aktion über ein zusätzliches Pull-down-Menü verfügt. Wenn
die Aktion in einer Symbolleiste angezeigt wird, wird das
Pull-down-Menü neben der Aktion angezeigt. Beim Anzeigen der Aktion
in einem Menü wird dieses Attribut ignoriert. Dieses Attribut und das
Attribut state schließen sich gegenseitig aus.
-
class: Der vollständig qualifizierte Name einer Klasse, die
org.eclipse.ui.IWorkbenchWindowActionDelegate
oder org.eclipse.ui.IWorkbenchWindowPulldownDelegate
implementiert. Letzteres sollte in
Fällen implementiert sein, bei denen das Attribut pulldown
auf den Wert "true" gesetzt ist.
Gilt true für das Attribut retarget, darf dieses
Attribut nicht angegeben werden.
-
retarget: gilt true für dieses Attribut, wird eine globale retarget-Aktion
erstellt. Komponenten können einen Handler für diese globale Aktion
unter Verwendung des Standardmechanismus zum Setzen eines globalen
Aktions-Handlers auf der Site unter Verwendung der ID dieser Aktion bereit stellen. Gilt "true" für dieses Attribut, darf das Klassenattribut nicht angegeben werden.
-
allowLabelUpdates: gilt nur dann, wenn true für retarget gilt. Gilt true
für dieses Attribut, wird die retarget-Aktion
den Kennsatz und die QuickInfo vom entsprechenden Handler aktualisieren.
-
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 Namensfilter 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.
Beispiele: Das folgende Beispiel stellt ein Aktionsset dar (bitte achten Sie
insbesondere auf die Verwendung der Unterelemente und Attribute):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="Meine Aktionen"
visible="true">
<menu id="com.xyz.xyzMenu"
label="XYZ-Menü"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&XYZ-Tool ausführen"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="XYZ-Tool ausführen"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1">
<selection class="org.eclipse.core.resources.IFile" name="*.java"/>
</action>
<action id="com.xyz.runABC"
label="&ABC-Tool ausführen"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runABC.gif"
tooltip="ABC-Tool ausführen"
helpContextId="com.xyz.run_abc_action_context"
retarget="true"
allowLabelUpdate="true">
</action>
</actionSet>
</extension>
Im oben dargestellten Beispiel ist die angegebene Aktion namens
"Meine Aktionen" in der Anfangseinstellung jeder Perspektive
sichtbar. Sie wird nur bei Auswahl eines einzelnen Elements
aktiviert (Attribut enablesFor). Außerdem müssen Objekte in
der Auswahl die angegebene Schnittstelle (IFile)
implementieren und eine Java-Datei sein.
API-Informationen: Der Wert des Attributs
class muss der vollständig qualifizierte Name einer Klasse
sein, die
org.eclipse.ui.IWorkbenchWindowActionDelegate
oder org.eclipse.ui.IWorkbenchWindowPulldownDelegate
implementiert. Letztes sollte in Fällen implementiert sein,
in denen das Attribut pulldown auf den Wert "true" gesetzt
ist. Diese Klasse wird so spät wie möglich geladen, um ein Laden des
Plug-ins zu verhindern, bevor es wirklich benötigt wird.
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.
Es ist unbedingt zu beachten, dass die Workbench Menüs nicht im
Auftrag von Plug-ins erstellt. Menüpfade müssen daher auf Menüs
verweisen, die bereits vorhanden sind.
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.
Bereitgestellte Implementierung: Plug-ins können an
diesem Erweiterungspunkt neue Menüs der höchsten Ebene (z. B.
"Debug") bereitstellen.
Plug-ins können außerdem benannte Gruppen definieren, in denen andere
Plug-ins ihre Aktionen ergänzen können.
Menüs der höchsten Ebene werden durch Verwendung der folgenden
Werte im Attribut path erstellt:
-
additions: Stellt eine Gruppe links neben dem Menü "Fenster"
dar.
Wenn das Attribut path übergangen wird, wird das neue Menü
in der Menüleistengruppe additions hinzugefügt.
Die Standardgruppen in einem Workbench-Fenster sind in der
Schnittstelle "IWorkbenchActionConstants" definiert. Diese Konstanten
können im Code zur dynamischen Ergänzung eingesetzt werden.
Die Werte können aber auch in eine XML-Datei kopiert und weiter auf
die vorhandenen Workbench-Menüs und -Symbolleisten abgestimmt werden.
Verschiedene Menü- und Symbolleistenoptionen im
Workbench-Fenster werden über Algorithmen definiert. In solchen
Fällen muss ein separater Mechanismus verwendet werden, um das
Fenster zu erweitern. Das Hinzufügen einer neuen Workbench-Sicht
führt beispielsweise dazu, dass das Menü "Fenster" eine neue
Option enthält.
Erweiterungen für Import- und Exportassistenten sowie für Assistenten
für neue Ressourcen werden ebenfalls automatisch zum Fenster
hinzugefügt.