Menüs

org.eclipse.ui.menus

3.2

An diesem Erweiterungspunkt können Plug-in-Entwickler Menüs, Trennlinien, logische Gruppen und Menüoptionen definieren, die an einer beliebigen Stelle in der Anwendung (inklusive Statuszeilen und Kontextmenüs) angezeigt werden können. Außerdem können hier Gruppen solcher Ergänzungen (also Aktionssets) definiert werden. Diese Aktionssets können durch den Benutzer aktiviert oder inaktiviert werden. Kurz gesagt enthält der Erweiterungspunkt für Menüs (mit Ausnahme der Symbole) alle Darstellungselemente für die Ergänzung eines beliebigen Menüs oder Ausschnittbereichs in Eclipse.

Jedes Element in diesem Erweiterungspunkt erhält eine eindeutige Kennung, damit an jeder beliebigen Stelle auf diese Elemente verwiesen werden kann, ohne dass das Element erneut angegeben werden muss. Die Kennung kann beispielsweise erforderlich sein, um ein Aktionsset zu definieren oder um seine interne Reihenfolge anzuordnen. Außerdem können Entwickler von Plug-ins anderer Anbieter diese Elemente bei Bedarf in neuen Positionen der Schnittstelle platzieren.

HINWEIS: Bei Version 3.2 wurde lediglich der Teil dieses Erweiterungsmechanimus' implementiert, der den Ergänzungen für Elemente "trim" (Ausschnitt) zugeordnet ist. Der Versuch, Optionen, Menüs, Symbolleisten oder Einträge für Statuszeilen hinzuzufügen, wird als Nullbefehl gewertet.

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

Ein Element "item" (Option) kann eine Menüoption oder eine Ausschnittoption sein (je nach Platzierung). Der Text und das Image, die der Option zugeordnet sind, können aus dem Befehl abgeleitet werden.



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

Ein Element "menu" (Menü) kann einer Symbolleistenoption zugeordnet sein oder im Menü einer Sicht, in einem Kontextmenü oder im Ausgangsmenü verwendet werden. Der Plug-in-Entwickler kann davon ausgehen, dass für jede Sicht eine Menü- und eine Symbolleiste vorhanden ist und dass es eine Ausgangsmenüleiste gibt. Kontextmenüs müssen über das Programm registriert werden, bevor sie verwendet werden können (siehe API-Informationen).

Ein Menü kann ausschließlich Gruppen enthalten.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

Eine logische Gruppe. Sie kann entweder sichtbar sein (davor bzw. danach werden also Trennlinien dargestellt) oder unsichtbar. Logische Gruppen sind standardmäßig sichtbar.

Eine Gruppe kann Menüs, Optionen und andere Gruppen enthalten.



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

Ein Menü- oder Ausschnittelement, das direkten Zugriff auf die Fensterobjekte hat. Dies kann beispielsweise verwendet werden, um ein kombiniertes Feld wiederzugeben. Nachteilig ist, dass die Sichtbarkeit eines Fensterobjekts in der Benutzerschnittstelle dazu führt, dass Plug-ins geladen werden. Verwenden Sie dieses Element umsichtig, da es Leistungsprobleme verursachen kann. Außerdem werden hierdurch Probleme bei der Makrounterstützung, der Scripterstellung und nicht wenigen anderen befehlsbasierten Mechanismen hervorgerufen. Bei der Verwendung als Ausschnitt veranlasst das Fensterobjekt nur dann das Laden des Plug-ins, wenn es in der Benutzerschnittstelle sichtbar wird.



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Mit diesem Element können verschiedene Layoutoptionen für Elemente angegeben werden, die in Positionen des Typs trim (also Ausschnitten) hinzugefügt werden.



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

Eine Position, in der ein Element menu, group, item oder widget angezeigt werden kann. Mit diesem Element werden die positionsspezifischen Informationen gesteuert.



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

Ein Blatt in einer Position. Dies kann die Menüleiste oder der Ausschnittbereich sein. Wenn dieses Attribut nicht qualifiziert ist, gibt es das Ausgangsmenü oder den Ausschnitt der höchsten Ebene an. Ist dieses Attribut mit einem Element part qualifiziert, gibt es das Menü oder den Ausschnitt einer Komponente an.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Ein Klassenelement, das die Parsingsyntax für die ausführbare Erweiterung bei Elementen widget und dynamic unterstützt.



<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Diese Angabe steuert die Sichtbarkeit des entsprechenden Elements.



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

Ein Element in einer Position. Diese Angabe qualifiziert die Position so, dass sie auf einen bestimmten Teil der Workbench verweist. Hierbei kann es sich entweder um eine Sicht oder um einen Editor handeln. Die Qualifizierung kann entweder den Klassennamen der Komponente (inklusive Übernahme) verwenden oder auf die Kennung für die Sicht bzw. den Editor verweisen.

Es kann nur eine Angabe von id und class verwendet werden.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ein Parameter für eine ausführbare Erweiterung oder einen Befehl (je nachdem, wo er in der Erweiterung verwendet wird).



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

Diese Angabe steuert die Position eines Menüs, einer Gruppe, einer Option oder eines Fensterobjekts in einer bestimmten Position.



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

Ein Positionswert, der angibt, dass das Menü, die Gruppe, die Option oder das Fensterobjekt im Kontextmenü angezeigt werden soll.



<!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.



Eine Basismenüdefinition sieht etwa folgendermaßen aus:

<menu id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

In diesem Beispiel ergänzt der Plug-in-Entwickler alle Komponenten, die den angegebenen Typ implementieren oder eine Unterklasse des Typs bilden. Auf diese Weise können beispielsweise Ergänzungen zu allen Texteditoren hinzugefügt werden.

<menu id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

Es ist möglich, einem Menü einen Hilfetext zuzuordnen.

<menu id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

In einem Menü können Sie logische Gruppen definieren. Diese logischen Gruppen können entweder sichtbar sein (davor bzw. danach werden also Trennlinien dargestellt) oder unsichtbar. Logische Gruppen sind standardmäßig sichtbar.

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

Menüs, Gruppen, Optionen und Fensterobjekte können in mehrere Positionen gestellt werden.

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

Falls das Kontextmenüelement ohne ID und ohne Element für die übergeordnete Komponente angegeben wird, wird es bei allen Kontextmenüs angewendet, die in der Workbench registriert sind. Dieses Verhalten erinnert an die früheren Objektergänzungen. Ganz ähnlich wirkt sich auch hier ein Kontextmenüelement der höchsten Ebene mit einer ID auf alle Kontextmenüs aus, die mit dem angegebenen Namen registriert sind.

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

Manchmal kann es sinnvoll sein, die Sichtbarkeit einer Option zu steuern. Ein kontinuierliches Layout von Menüs und Symbolleisten ist zwar normalerweise vorzuziehen, aber es kann vorkommen, dass Optionen, die nicht sofort relevant sind, ausgeblendet werden soll. Dies gilt insbesondere bei Kontextmenüs, deren verfügbarer Platz naturgemäß eingeschränkt ist. In einem solchen Fall wird ein Element visibleWhen definiert. Dieses Element ist mit den Elementen activeWhen und enabledWhen, die im Erweiterungspunkt für Handler definiert sind, quasi identisch.

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

Am häufigsten soll ein Element dann aktiviert werden, wenn sein Handler aktiv ist. Dies wird durch eine kleine Syntaxänderung erreicht. Es gibt ein Attribut checkEnabled für das Element visibleWhen.

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

Jede Option, der ein Befehl zugeordnet ist, kann Parameterwerte enthalten. Falls der Parameter der angegebenen Kennung nicht definiert ist, tritt ein Fehler auf. Hat diese Option keinen Befehl, tritt ebenfalls ein Fehler auf.

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

Es besteht die Möglichkeit, eine relative Reihenfolge anzugeben. Hierzu wird das Attribut "order" für das Element "location" verwendet. Das Attribut "order" akzeptiert die folgenden Werte: start (stellt das Element an den Beginn des Containers); end (stellt das Element an das Ende seines Containers); after (stellt das Element hinter das gleichgeordnete Element, dessen ID mit dem Wert für ref übereinstimmt); before (stellt das Element vor das gleichgeordnete Element, dessen ID mit dem Wert für ref übereinstimmt). Die relative Reihenfolge kann auf jeden beliebigen Typ von Menüelementen angewendet werden.

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

Falls Sie einen direkten Zugriff auf die Fensterobjekte benötigen (beispielsweise um ein kombiniertes Feld darzustellen), können Sie das Element widget verwenden. Nachteilig ist, dass die Sichtbarkeit eines Fensterobjekts in der Benutzerschnittstelle dazu führt, dass Plug-ins geladen werden.

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

Sie können Fensterobjekte auch zur Ergänzung des Workbenchausschnitts einsetzen. Das folgende Beispiel definiert ein neues Fensterobjekt "HeapStatus", das standardmäßig unmittelbar nach dem Statuszeilenausschnitt (also am unteren Rand des Workbench-Fensters) angeordnet werden soll. Weitere Informationen zu den vordefinierten Gruppen finden Sie in den Angaben über das Element "bar".

Bitte beachten Sie, dass Ausschnittgruppen in den anderen Ausschnittbereichen neu angeordnet werden können. Die Angabe relativeTo in den Positionsangaben geht davon aus, dass sich die Gruppe, auf die verwiesen wird, in der Standardposition befindet, wenn die Position des neuen Ausschnitts ermittelt wird. Im Allgemeinen wird erwartet, dass Ergänzungen dieses Typs eine eigene Gruppe für das neue Fensterobjekt erstellen, um auf diese Weise eine Neuplatzierung des Ausschnittselements zu ermöglichen, die von den anderen Ausschnittselementen unabhängig ist. Eine nennenswerte Ausnahme für diese Praxis ist die Gruppe "status".

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

Verwenden Sie zum Registrieren eines Kontextmenüs die Methoden von IWorkbenchPartSite.registerContextMenu.