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ü vorgenommen werden. Bei der Registrierung für einen Objekttyp wird die Ergänzung in allen Anzeigefunktionen angezeigt, in denen Objekte des angegebenen Typs ausgewählt sind. Im Gegensatz hierzu bewirkt die Registrierung für ein Kontextmenü, dass die Aktion - unabhängig von der Auswahl - nur im angegebenen Menü 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.

Wenn diese Filtermechanismen ungeeignet sind, kann eine Aktionsergänzung den Mechanismus filter verwenden.  In diesem Fall werden die Attribute des Zielobjekts in einer Reihe von Schlüssel-/Wertpaaren beschrieben. Die auf die Auswahl angewendeten Attribute sind typspezifisch und gelten über die Domäne der Workbench selbst hinaus. Die Workbench delegiert die Filterung auf dieser Stufe daher an die tatsächliche Auswahl.

Konfigurationsbefehle:

   <!ELEMENT objectContribution (filter | menu | action)* (visibility)?>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter  CDATA #IMPLIED
      adaptable   (true|false) #IMPLIED
   >

   <!ELEMENT visibility (and | or | not | objectClass | objectState | systemProperty
        | pluginState)>
   <!ATTLIST visibility EMPTY>
In Version 2.0 von Eclipse kann das Element visibility in einer objectContribution verwendet werden, um die Sichtbarkeit für eine Aktion zu definieren. Dies ist kein Ersatz für das Attribut objectClass, das das primäre Ziel für die Aktion definiert. Das Element visibility wird dazu verwendet, das primäre Ziel näher zu spezifizieren. Weitere Informationen zur Verwendung des Elements visibility finden Sie unter actionExpressions.html.
   <!ELEMENT viewerContribution (menu | action)*>
   <!ATTLIST viewerContribution
      id        CDATA #REQUIRED
      targetID  CDATA #REQUIRED
   >    <!ELEMENT filter EMPTY>
   <!ATTLIST filter
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >    <!ELEMENT menu (separator)+>
   <!ATTLIST menu
      id         CDATA #REQUIRED
      label      CDATA #REQUIRED
      path       CDATA #IMPLIED
   >    <!ELEMENT separator EMPTY>
   <!ATTLIST separator
      name       CDATA #REQUIRED
   >
  • name: Der Name des Trennzeichens, auf das später im Aktionspfad als letztes Token verwiesen werden kann. Trennzeichen dienen daher als benannte Gruppen, in denen Aktionen hinzugefügt werden können.
  •    <!ELEMENT action (selection)* (enablement)?>
       <!ATTLIST action
          id                NMTOKEN #REQUIRED
          label             CDATA #REQUIRED
          menubarPath       CDATA #IMPLIED
          icon              CDATA #IMPLIED
          helpContextId     CDATA #IMPLIED
          state             (true | false) #IMPLIED
          class             CDATA #REQUIRED
          enablesFor        CDATA #IMPLIED
       >    <!ELEMENT selection EMPTY>
       <!ATTLIST selection
          class             CDATA #REQUIRED
          name              CDATA #IMPLIED
       >    <!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.
    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.

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

    Beispiele:

    Das folgende Beispiel ist ein 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"
                  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;XYZ anzeigen"
                       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 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 in der Sicht "Aufgaben" 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.C1"
             objectClass="org.eclipse.core.resources.IMarker">
             <filter name="done" value="true"/>
             <filter name="priority" value="2"/>
             <action id="com.xyz.runXYZ"
                  label="Tool für abgeschlossene Aktion mit hoher Priorität"
                  icon="icons/runXYZ.gif"
                  class="com.xyz.actions.MarkerActionDelegate">
              </action>
            </objectContribution>
         </extension>

    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 Anzeigefunktionen, die zu Sichten gehören) oder org.eclipse.ui.IEditorActionDelegate (bei Ergänzungen für Anzeigefunktionen, 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 Kontextmenüerweiterung in einer Komponente ist nur dann möglich, wenn die Zielkomponente ein Menü zur Erweiterung publiziert. Dies wird dringend empfohlen, da es die Erweiterbarkeit des Produkts verbessert. Zu diesem Zweck sollte jede Komponente alle definierten Kontextmenüs durch einen Aufruf von IWorkbenchPartSite#registerContextMenu publizieren.  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ü ist, kann ein Element org.eclipse.ui.IActionFilter definieren. Diese Filterungsstrategie kann typspezifische Filterungen ausführen. Die Workbench ruft den Filter für die Auswahl ab, indem sie testet, ob IActionFilter implementiert ist.  Verläuft dieser Versuch erfolglos, fordert die Workbench über den Mechanismus IAdaptable einen Filter an.

    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 Anzeigefunktion 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 IBM Corporation und Andere 2000, 2002. Alle Rechte vorbehalten.