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
angewendet werden sollen.
Falls diese Filtermechanismen ungeeignet sind, kann eine Aktionsergänzung einen eigenen Filtermechanismus verwenden. In diesem Fall werden die Attribute des Zielobjekts in einer Reihe von Name/Wert-Paaren beschrieben. Die für die Auswahl geltenden Attribute sind typspezifisch und gehen über die Domäne der eigentlichen Workbench hinaus. Daher delegiert die Workbench die Filterung auf dieser Ebene an die aktuelle Auswahl.
Die Aktivierung und/oder Sichtbarkeit einer Aktion kann mit den Elementen enablement bzw. visibility definiert werden. Diese beiden Elemente enthalten einen Booleschen Ausdruck, dessen Auswertung die Aktivierung und/oder Sichtbarkeit festlegt.
Die Syntax für die Elemente enablement und visibility ist jeweils identisch. Beide enthalten nur ein Unterelement mit einem Booleschen Ausdruck. Im einfachsten Fall handelt es sich hierbei um ein Element objectClass, objectState, pluginState oder systemProperty. In komplexeren Angaben können die Elemente and, or und not zu einem Booleschen Ausdruck kombiniert werden. Sowohl das Element and als auch das Element or muss zwei Unterelemente enthalten. Das Element not darf nur 1 Unterelement enthalten.
<!ELEMENT extension (objectContribution , viewerContribution)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>
<!ATTLIST objectContribution
id CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
adaptable (true | false) "false">
Mit diesem Element wird eine Gruppe von Aktionen und/oder Menüs für alle Kontextmenüs von Anzeigefunktionen definiert, in denen Objekte des angegebenen Typs ausgewählt sind.
<!ELEMENT viewerContribution (visibility? , menu* , action*)>
<!ATTLIST viewerContribution
id CDATA #REQUIRED
targetID CDATA #REQUIRED>
Mit diesem Element wird eine Gruppe von Aktionen und/oder Menüs für das Kontextmenü einer spezifischen Sicht oder eines spezifischen Editorteils definiert.
<!ELEMENT action (selection* , enablement?)>
<!ATTLIST action
id CDATA #REQUIRED
label CDATA #REQUIRED
definitionId CDATA #IMPLIED
menubarPath CDATA #IMPLIED
icon CDATA #IMPLIED
helpContextId CDATA #IMPLIED
style (push|radio|toggle|pulldown)
state (true | false)
class CDATA #REQUIRED
enablesFor CDATA #IMPLIED
overrideActionId CDATA #IMPLIED
tooltip CDATA #IMPLIED>
Dieses Element definiert eine Aktion, die der Benutzer in der Benutzerschnittstelle aufrufen kann.
push | - Die Aktion wird als normale Menüoption oder Symbolleistenoption dargestellt. | |
radio | - Die Aktion wird im Menü oder in der Symbolleiste als Optionsfeld angezeigt. Aktionen mit dieser Darstellung, die zur gleichen Menü- oder Symbolleistengruppe gehören, verhalten sich wie eine Optionsfeldgruppe. Der Ausgangswert wird durch das Attribut state definiert. | |
toggle | - Die Aktion wird als mit einem Haken markierte Menüoption oder als Umschaltelement in der Symbolleiste angezeigt. Der Ausgangswert wird durch das Attribut state definiert. | |
pulldown | - Als Menüelement mit gestaffelter Darstellung. |
! | - 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 genaue Anzahl ausgewählter Elemente. Bei der Angabe enablesFor=" 4" wird die Aktion beispielsweise nur dann aktiviert, wenn 4 Elemete ausgewählt sind. | |
* | - Beliebig viele ausgewählte Elemente |
Die Aktivierungsbedingungen für eine Aktionserweiterung sind anfänglich durch enablesFor, selection und enablement definiert. Sobald der Aktionsstellvertreter als Exemplar erstellt wurde, kann er jedoch den Aktivierungsstatus der Aktion direkt in seiner Methode selectionChanged steuern.
<!ELEMENT filter EMPTY>
<!ATTLIST filter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Mit diesem Element wird der Attributstatus aller Objekte in der aktuellen Auswahl ausgewertet. Eine Übereinstimmung liegt nur dann vor, wenn alle Objekte in der Auswahl den angegebenen Attributstatus aufweisen. Alle Objekte in der Auswahl müssen org.eclipse.ui.IActionFilter implementieren oder zugeordnet sein.
<!ELEMENT menu (separator+ , groupMarker*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path CDATA #IMPLIED>
Mit diesem Element wird ein neues Menü definiert.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED>
Mit diesem Element wird im neuen Menü ein Menütrennzeichen erstellt.
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name CDATA #REQUIRED>
Mit diesem Element wird im neuen Menü eine benannte Gruppe erstellt. Anders als das Element separator gibt es für dieses Element im neuen Menü keine sichtbare Darstellung.
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class CDATA #REQUIRED
name CDATA #IMPLIED>
Mit diesem Element wird die Aktionsaktivierung anhand der aktuellen Auswahl ermittelt. Es wird ignoriert, wenn das Element enablement angegeben ist.
<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Mit diesem Element wird die Aktivierung der Erweiterung definiert.
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Dieses Element definiert die Sichtbarkeit für die Erweiterung.
<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Dieses Element stellt eine Boolesche Operation AND für das Ergebnis der Auswertung seiner beiden Unterelementausdrücke dar.
<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Dieses Element stellt eine Boolesche Operation OR für das Auswertungsergebnis seiner beiden Unterelementausdrücke dar.
<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Dieses Element stellt eine Boolesche Operation NOT für das Ergebnis der Auswertung seiner Unterelementausdrücke dar.
<!ELEMENT objectClass EMPTY>
<!ATTLIST objectClass
name CDATA #REQUIRED>
Mit diesem Element wird die Klasse oder Schnittstelle aller Objekte in der aktuellen Auswahl ausgewertet. Wenn alle Objekte in der Auswahl die angegebene Klasse oder Schnittstelle implementieren, wird der Ausdruck mit dem Ergebnis "true" ausgewertet.
<!ELEMENT objectState EMPTY>
<!ATTLIST objectState
name CDATA #REQUIRED
value CDATA #REQUIRED>
Mit diesem Element wird der Attributstatus aller Objekte in der aktuellen Auswahl ausgewertet. Wenn alle Objekte in der Auswahl den angegebenen Attributstatus aufweisen, wird der Ausdruck mit dem Ergebnis "true" ausgewertet. Damit ein solcher Ausdruckstyp ausgewertet wird, müssen alle Objekte in der Auswahl die Schnittstelle org.eclipse.ui.IActionFilter implementieren bzw. ihr zugeordnet sein.
<!ELEMENT pluginState EMPTY>
<!ATTLIST pluginState
id CDATA #REQUIRED
value (installed|activated) "installed">
Mit diesem Element wird der Status eines Plug-ins ausgewertet. Der Status des Plug-ins kann installed (entspricht dem OSGi-Konzept "resolved") oder activated (entspricht dem OSGi-Konzept "active") lauten.
<!ELEMENT systemProperty EMPTY>
<!ATTLIST systemProperty
name CDATA #REQUIRED
value CDATA #REQUIRED>
Mit diesem Element wird der Status einer bestimmten Systemeigenschaft ausgewertet. Der Eigenschaftswert wird aus java.lang.System abgerufen.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Ein generisches Stammelement. Das Element kann in einem Erweiterungspunkt zum Definieren seines Ausdrucks "enablement" eingesetzt werden. Die untergeordneten Elemente eines Ausdrucks "enablement" werden durch den Einsatz des Operators "and" kombiniert.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Dieses Element stellt eine Operation NOT für das Ergebnis der Auswertung seiner Unterelementausdrücke dar.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Dieses Element stellt eine Operation AND für das Auswertungsergebnis aller seiner Unterelementausdrücke dar.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Dieses Element stellt eine Operation OR für das Auswertungsergebnis aller seiner Unterelementausdrücke dar.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Dieses Element wird zur Durchführung einer Prüfung des Typs "instanceof" für das Objekt im Fokus eingesetzt. Der Ausdruck gibt "EvaluationResult.TRUE" zurück, wenn es sich bei dem Objekttyp um einen Untertyp des im Attribut "value" angegebenen Typs handelt. Andernfalls wird "EvaluationResult.FALSE" zurückgegeben.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Dieses Element wird verwendet, um den Eigenschaftsstatus des Objekts im Fokus zu auszuwerten. Die Gruppe der Eigenschaften, die getestet werden können, kann mit Hilfe des Erweiterungspunktes "propertyTesters" für Testfunktionen für Eigenschaften erweitert werden. Der Ausdruck "test" gibt "EvaluationResult.NOT_LOADED" zurück, wenn die Testfunktion für Eigenschaften, die den Test durchführt, noch nicht geladen ist.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Testet eine Systemeigenschaft, indem die Methode "System.getProperty" aufgerufen wird und das Ergebnis mit dem im Attribut "value" angegebenen Wert verglichen wird.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Dieses Element wird zur Durchführung einer Prüfung des Typs "equals" für das Objekt im Fokus eingesetzt. Der Ausdruck gibt "EvaluationResult.TRUE" zurück, wenn das Objekt mit dem Wert übereinstimmt, der von dem Attributwert zur Verfügung gestellt wird. Andernfalls wird "EvaluationResult.FALSE" zurückgegeben.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Dieses Element wird verwendet, um die Anzahl der Elemente in einer Gruppe zu testen.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
Dieses Element ändert das zu untersuchende Objekt für alle seine untergeordneten Elemente in das Objekt, auf das mit der betreffenden Variablen verwiesen wird. Kann die Variable nicht aufgelöst werden, löst der Ausdruck bei der Auswertung der Variablen die Ausnahmebedingung "ExpressionException" aus. Die untergeordneten Elemente des Ausdrucks "with" werden durch Verwendung des Operators "and" kombiniert.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
Dieses Element ändert das zu untersuchende Objekt für alle seine untergeordneten Elemente in das Objekt, auf das mit der betreffenden Variablen verwiesen wird. Kann die Variable nicht aufgelöst werden, löst der Ausdruck bei der Auswertung der Variablen die Ausnahmebedingung "ExpressionException" aus. Die untergeordneten Elemente des Ausdrucks "with" werden durch Verwendung des Operators "and" kombiniert.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Dieses Element wird verwendet, um das Objekt im Fokus an den Typ anzupassen, der im Attribut "type" angegeben ist. Der Ausdruck gibt "not loaded" zurück, wenn entweder der Adapter oder der verwiesene Typ noch nicht geladen ist. Während der Auswertung wird die Ausnahmebedingung "ExpressionException" ausgelöst, wenn der Typname überhaupt nicht existiert. Die untergeordneten Elemente eines Ausdrucks "adapt" werden mit Hilfe des Operators "and" kombiniert.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Dieses Element wird zur Iteration einer Variablen des Typs "java.util.Collection" eingesetzt. Wenn das Objekt im Fokus nicht den Typ "java.util.Collection" hat, wird während der Auswertung des Ausdrucks die Ausnahmebedingung "ExpressionException" ausgelöst.
Im oben dargestellten Beispiel wird die angegebene Aktion für die Objektergänzung 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.<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=
"&Run XYZ Tool"
style=
"push"
menubarPath=
"com.xyz.xyzMenu/group1"
icon=
"icons/runXYZ.gif"
helpContextId=
"com.xyz.run_action_context"
class=
"com.xyz.actions.XYZToolActionDelegate"
enablesFor=
"1"
/>
</objectContribution>
<viewerContribution id=
"com.xyz.C2"
targetID=
"org.eclipse.ui.views.TaskList"
>
<action id=
"com.xyz.showXYZ"
label=
"&Show XYZ"
style=
"toggle"
state=
"true"
menubarPath=
"additions"
icon=
"icons/showXYZ.gif"
helpContextId=
"com.xyz.show_action_context"
class=
"com.xyz.actions.XYZShowActionDelegate"
/>
</viewerContribution>
</extension>
Im Gegensatz dazu wird die oben darstellte Ergänzung der Anzeigefunktion nur im Kontextmenü 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.
Das nächste Beispiel zeigt ebenfalls die Verwendung des Elements "visibility":<extension point=
"org.eclipse.ui.popupMenus"
>
<objectContribution id=
"com.xyz.C3"
objectClass=
"org.eclipse.core.resources.IMarker"
>
<filter name=
"done"
value=
"true"
/>
<filter name=
"priority"
value=
"2"
/>
<action id=
"com.xyz.runXYZ"
label=
"High Priority Completed Action Tool"
icon=
"icons/runXYZ.gif"
class=
"com.xyz.actions.MarkerActionDelegate"
>
</action>
</objectContribution>
</extension>
<extension point=
"org.eclipse.ui.popupMenus"
>
<viewerContribution id=
"com.xyz.C4"
targetID=
"org.eclipse.ui.views.TaskList"
>
<visibility>
<and>
<pluginState id=
"com.xyz"
value=
"activated"
/>
<systemProperty name=
"ADVANCED_MODE"
value=
"true"
/>
</and>
</visibility>
<action id=
"com.xyz.showXYZ"
label=
"&Show XYZ"
style=
"push"
menubarPath=
"additions"
icon=
"icons/showXYZ.gif"
helpContextId=
"com.xyz.show_action_context"
class=
"com.xyz.actions.XYZShowActionDelegate"
>
</action>
</viewerContribution>
</extension>
In diesem Beispiel wird die angegebene Aktion als Menüoption im Kontextmenü der Sicht "Tasks" angezeigt, allerdings nur dann, wenn das Plug-in "com.xyz" aktiv ist und die angegebene Systemeigenschaft auf "true" gesetzt ist.
Hinweis: Aus Gründen der Abwärtskompatibilität kann org.eclipse.ui.IActionDelegate für Objektergänzungen implementiert werden.
Die Erweiterung des Kontextmenüs in einer Komponente ist nur dann möglich, wenn die Zielkomponente ein Menü für die Erweiterung publiziert. Dies ist sehr zu empfehlen, da auf diese Weise die Erweiterbarkeit des Produkts vergrößert wird. Um dies zu erreichen, sollte jede Komponente alle Kontextmenüs publizieren, die durch einen Aufruf von IWorkbenchPartSite.registerContextMenu definiert werden. 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 die Konsistenz komponentenübergreifend gewährleistet wird, sollten alle Implementierungselemente die folgende Strategie verwenden.
Alle in der Workbench registrierten Kontextmenüs sollten ebenfalls eine Standardeinfügemarke mit ID enthalten (IWorkbenchActionConstants.MB_ADDITIONS). Andere Plug-ins verwenden diesen Wert beim Einfügen als Referenzpunkt. Die Einfügemarke kann definiert werden, indem ein Element "GroupMarker" an der entsprechenden Einfügeposition zum Menü hinzugefügt wird. Andere Plug-ins verwenden diesen Wert als Referenzpunkt für die Einfügung. Die Einfügemarke kann definiert werden, indem ein Element "GroupMarker" an der entsprechenden Einfügeposition zum Menü hinzugefügt wird.
Ein Objekt in der Workbench, das die Auswahl in einem Kontextmenü darstellt, kann ein Objekt org.eclipse.ui.IActionFilter definieren. Hierbei handelt es sich um eine Filterstrategie, die eine typspezifische Filterung ausführen kann. Die Workbench ruft den Filter für die Auswahl ab, indem sie versucht, IActionFilter zu implementieren. Schlägt dieser Versuch fehl, ruft die Workbench einen Filter über den Mechanismus IAdaptable ab.
Aktions- und Menübezeichnungen können Sonderzeichen enthalten, die mnemonische Zeichen codieren, die über ein Et-Zeichen (&) vor einem ausgewählten Zeichen des übersetzbaren Textes angegeben werden. Da das Et-Zeichen in XML-Zeichenfolgen nicht zulässig ist, muss die Zeichenentität & verwendet werden.
Wenn zwei oder mehr Aktionen einem Menü 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 zugegebenermaßen nicht beabsichtigt. Es wurde jedoch festgestellt, nachdem die API für die Eclipse-Plattform festgeschrieben wurde. Eine Änderung des Verhaltens zum jetzigen Zeitpunkt würde alle Plug-ins beschädigen, die auf dem vorhandenen Verhalten basieren.
Die Elemente selection und enablement schließen sich gegenseitig aus. Das Element enablement kann das Element selection unter Verwendung der Unterelemente objectClass und objectState ersetzen. Die Angabe
könnte beispielsweise auch folgendermaßen ausgedrückt werden:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2005 IBM Corporation und Andere.
Alle Rechte vorbehalten. Dieses Programm und sein Begleitmaterial werden gemäß den Bedingungen der "Eclipse Public License v1.0" zur Verfügung gestellt, die dieser Lieferung beiliegt und unter
http://www.eclipse.org/legal/epl-v10.html abgerufen werden kann.