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 übersetzbarer Name, der dieses Aktionsset im Menü des
Workbench-Fensters darstellt.
-
visible: Ein wahlfreies Attribut, mit dem angegeben wird, ob
das Aktionsset in der Anfangseinstellung des Workbench-Fensters
sichtbar sein soll. Der Benutzer kann diese Option im Dialog
"Perspektive anpassen" überschreiben.
-
description: Ein optionales Unterelement, dessen Hauptteil
einen Text als Kurzbeschreibung des Aktionsset enthalten sollte.
<!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
zwischen den Menüs "Perspektive" und "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 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
pulldown
(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.
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.
-
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.
-
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.
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.
Die in der Anfangseinstellung geltenden Aktivierungskriterien für
eine Aktionserweiterung werden durch
enablesFor und selection definiert. Sobald die
Aktionsdelegation 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 für ein Aktionsset dargestellt (bitte
achten
Sie insbesondere auf die Verwendung der Unterelemente und Attribute):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visible="true">
<menu id="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1">
<selection class="org.eclipse.core.resources.IFile" name="*.java"/>
</action>
</actionSet>
</extension>
Im oben dargestellten Beispiel ist die angegebene Aktion namens
"My Actions" 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.
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ü "Perspektive" 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.