Kontextmenüs

Kennung: org.eclipse.ui.popupMenus

Beschreibung: An diesem Erweiterungspunkt können neue Aktionen zu Kontextmenüs hinzugefügt werden, deren Eigner andere Plug-ins sind. Die Aktionsergänzung kann für einen spezifischen Objekttyp (objectContribution) oder für ein spezifisches Kontextmenüeiner Sicht oder eines Editorteils (viewerContribution) vorgenommen werden. Bei Verwendung vonobjectContribution wird die Ergänzung in allen Kontextmenüs von Sichten oder Editorteilen angezeigt, in denen Objekte des angegebenen Typs ausgewählt sind. Im Gegensatz hierzu bewirkt die Verwendung vonviewerContribution, dass die Ergänzung - unabhängig von der Auswahl - nur im Kontextmenü der angegebenen Sicht bzw. des angegebenen Editorteils angezeigt wird.

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

Die Syntax für die Elemente enablement und visibility ist jeweils identisch. Beide Elemente enthalten nur ein Unterelement für den 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 2 Unterelemente enthalten. Das Element not darf lediglich 1 Unterelement enthalten.

Konfigurationsbefehle:

   <!ELEMENT extension (objectContribution , viewerContribution)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

   <!ELEMENT objectContribution (filter* , visibility? , menu* , action*)>

   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.

   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
     objectClass CDATA #REQUIRED
     nameFilter  CDATA #IMPLIED
     adaptable   (true | false) "false"
   >

   <!ELEMENT viewerContribution (visibility? , menu* , action*)>

   Mit diesem Element wird eine Gruppe von Aktionen und/oder Menüs für das Kontextmenü einer spezifischen Sicht oder eines spezifischen Editorteils definiert.

   <!ATTLIST viewerContribution
      id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

   <!ELEMENT action (selection* , enablement?)>

  Dieses Element definiert eine Aktion, die der Benutzer in der Benutzerschnittstelle aufrufen kann.

   <!ATTLIST action
      id               CDATA #REQUIRED
      label            CDATA #REQUIRED
     menubarPath      CDATA #IMPLIED
      icon             CDATA #IMPLIED
     helpContextId    CDATA #IMPLIED
     style            (push|radio|toggle)
     state            (true | false)
     class            CDATA #REQUIRED
     enablesFor       CDATA #IMPLIED
     overrideActionId CDATA #IMPLIED
      tooltip          CDATA #IMPLIED
   >

   <!ELEMENT filter EMPTY>

   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.

   <!ATTLIST filter
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT menu (separator+ , groupMarker*)>

   Mit diesem Element wird ein neues Menü definiert.

   <!ATTLIST menu
      id    CDATA #REQUIRED
      label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

   Mit diesem Element wird im neuen Menü ein Menütrennzeichen erstellt.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   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.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   Mit diesem Element wird bestimmt, ob die Aktion aufgrund der aktuellen Auswahl aktiviert ist. Es wird ignoriert, wenn das Element enablement angegeben ist.

   <!ATTLIST selection
     class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

   <!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Mit diesem Element wird die Aktivierung der Aktion definiert.

   <!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Mit diesem Element wird die Sichtbarkeit der Aktion definiert.

   <!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 Ergebnis der Auswertung 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>

   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.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   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.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Mit diesem Element wird der Status eines Plug-ins ausgewertet. Der Status des Plug-ins kann installed oder activated lauten.

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   Mit diesem Element wird der Status einer bestimmten Systemeigenschaft ausgewertet. Der Eigenschaftswert wird aus java.lang.System abgerufen.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Beispiele: Das folgende Beispiel zeigt einen Erweiterungspunkt für ein Kontextmenü:

   <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="&amp;XYZ Java Tools"> 
            <separator name="group1"/> 
         </menu> 
         <action
            id="com.xyz.runXYZ" 
            label="&amp;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"> 
         </action> 
      </objectContribution> 
      <viewerContribution 
         id="com.xyz.C2" 
         targetID="org.eclipse.ui.views.TaskList"> 
         <action
            id="com.xyz.showXYZ" 
            label="&amp;Show XYZ"
            style="toggle"
            state="true"
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate"> 
         </action> 
      </viewerContribution> 
   </extension> 

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.

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.

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

Das nächste Beispiel zeigt ebenfalls die Verwendung des Elements "visibility":

   <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="&amp;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.

API-Informationen:  Der Wert des Aktionsattributs class muss der vollständig qualifizierte Klassenname einer Java-Klasse sein, die org.eclipse.ui.IObjectActionDelegate (bei Objektergänzungen), org.eclipse.ui.IViewActionDelegate (bei Ergänzungen für Kontextmenüs, die zu Sichten gehören) oder org.eclipse.ui.IEditorActionDelegate (bei Ergänzungen für Kontextmenüs, die zu Editoren gehören) implementieren. In allen Fällen wird die implementierende Klasse so spät wie möglich geladen, damit das gesamte Plug-in erst dann geladen wird, wenn es wirklich benötigt wird.

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

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 umsetzbaren Textes angegeben werden. Da das Et-Zeichen in XML-Zeichenfolgen nicht zulässig ist, muss die Zeichenentität &amp; 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 erst nach dem Festschreiben der Eclipse-Plattform-API festgestellt. Eine Änderung dieses 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 folgende Codierung

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
kann beispielsweise auch wie folgt ausgedrückt werden:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Bereitgestellte Implementierung: Die Workbench-Sichten enthalten integrierte Kontextmenüs, die bereits mit einer Reihe von Aktionen ausgeliefert werden. Plug-ins können Ergänzungen für diese Menüs definieren. Wenn eine Sicht Segmente für diese Ergänzungen reserviert hat und diese publiziert werden, können die Namen der Segmente als Pfadwerte verwendet werden. Andernfalls werden Aktionen und Untermenüs am Ende des Kontextmenüs hinzugefügt.

Copyright (c) 2000, 2003 IBM Corporation und Andere. Alle Rechte vorbehalten. Dieses Programm und sein Begleitmaterial werden gemäß den Bedingungen in der "Common Public License v1.0" zur Verfügung gestellt, die diese Verteilung begleitet und unter "http://www.eclipse.org/legal/cpl-v10.html" abgerufen werden kann.