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 gültig sein 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)*>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter  CDATA #IMPLIED
   >

   <!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 als letztes Token im Aktionspfad verwiesen werden kann. Trennzeichen dienen daher als benannte Gruppen, in denen Aktionen hinzugefügt werden können.
  •    <!ELEMENT action EMPTY>
       <!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
       > Die in der Anfangseinstellung geltenden Aktivierungskriterien für eine Aktionserweiterung werden durch die Attribute enablesFor und selection definiert. Sobald die Aktionsdelegierung jedoch als Exemplar erstellt wurde, kann sie den Aktivierungsstatus einer Aktion direkt in ihrer Methode selectionChanged steuern.

    Aktions- und Menübezeichnungen können Sonderzeichen enthalten, die mnemonische Zeichen und Direktaufrufzeichen gemäß den folgenden Regeln codieren:

    1. 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 &amp; verwendet werden.
    2. Optionale Direktaufrufzeichen werden am Ende der Namenszeichenfolge mit dem Zeichen @ angegeben, auf das eine Reihe von Änderungswerten und das eigentliche Direktaufrufzeichen folgen (Beispiel: &amp;Speichern@Strg+S). Direktaufrufzeichen mit mehreren Änderungswerten können durch die Verkettung von Änderungswerten erreicht werden, die das Zeichen + als Begrenzer verwenden (Beispiel: @Strg+Umschalt+S).
    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;XYZ-Tool ausführen"
                  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 dargestellte Ergänzung der Anzeigefunktion nur in 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.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: Um eine Abwärtskompatibilität zu ermöglichen, 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 eine komponentenübergreifende Konsistenz gewährleistet wird, sollten alle Implementierungselemente die folgende Strategie verwenden:

    Alle in der Workbench registrierten Kontextmenüs sollten außerdem eine Standardeinfügemarke mit einer 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 die Schnittstelle 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 Corp. 2000, 2001. Alle Rechte vorbehalten.