Menüs, Symbolleisten und Aktionen in Sichten

Kennung: org.eclipse.ui.viewActions

Beschreibung: An diesem Erweiterungspunkt können Aktionen zum Pulldown-Menü und zur Symbolleiste für Sichten hinzugefügt werden, die durch andere Plug-ins registriert wurden. Jede Sicht enthält ein lokales Pulldown-Menü, das normalerweise durch Klicken auf die Schaltfläche mit dem Dreieck aktiviert wird, die sich in der rechten oberen Ecke befindet. Andere Plug-ins können dieses Menü durch Untermenüs und Aktionen ergänzen. Auch die Symbolleiste einer Sicht kann von Plug-ins durch Aktionen ergänzt werden. Zuerst erhält der Eigner der Sicht die Möglichkeit, diese Bereich zu belegen. Optionale Zusätze durch andere Plug-ins werden angehängt.

Die Aktivierung und/oder Sichtbarkeit einer Aktion kann durch die Elemente enablement bzw. visibility definiert werden. Diese beiden Elemente enthalten einen Booleschen Ausdruck, dessen Auswertung die Aktivierung und/oder Sichtbarkeit bestimmt.

Die Syntax ist für beide Elemente enablement und visibility identisch. Beide enthalten nur ein Unterelement mit einem Booleschen Ausdruck. Im einfachsten Fall ist dies ein Element objectClass, objectState, pluginState oder systemProperty. In komplexeren Fällen können die Elemente and, or und not kombiniert werden und so einen Booleschen Ausdruck bilden. Sowohl das Element and als auch das Element or muss zwei Unterelemente enthalten. Das Element not darf nur 1 Unterelement enthalten.

Konfigurationsbefehle:

   <!ELEMENT extension (viewContribution+)>

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

   <!ELEMENT viewContribution (menu* , action*)>

   Mit diesem Element wird eine Gruppe von Aktionen und/oder Menüs für eine Sicht definiert.

   <!ATTLIST viewContribution
      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
     toolbarPath   CDATA #IMPLIED
      icon          CDATA #IMPLIED
     disabledIcon  CDATA #IMPLIED
     hoverIcon     CDATA #IMPLIED
      tooltip       CDATA #IMPLIED
     helpContextId CDATA #IMPLIED
     style         (push|radio|toggle) "push"
     state         (true | false)
     class         CDATA #REQUIRED
     enablesFor    CDATA #IMPLIED
   >

   <!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 die Aktionsaktivierung anhand der aktuellen Auswahl ermittelt. 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 Typ Ausdruck 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. Ein Plug-in kann den Status installed oder activated haben.

   <!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 eine Erweiterung für eine Sichtaktion.

   <extension point="org.eclipse.ui.viewActions"> 
      <viewContribution 
         id="com.xyz.xyzViewC1" 
         targetID="org.eclipse.ui.views.navigator.ResourceNavigator"> 
         <menu
            id="com.xyz.xyzMenu" 
            label="XYZ Menu" 
            path="additions"> 
            <separator name="group1"/> 
         </menu> 
         <action
            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            menubarPath="com.xyz.xyzMenu/group1" 
            toolbarPath="Normal/additions"
            style="toggle"
            state="true" 
            icon="icons/runXYZ.gif" 
            tooltip="Run XYZ Tool" 
            helpContextId="com.xyz.run_action_context" 
            class="com.xyz.actions.RunXYZ"> 
            <selection class="org.eclipse.core.resources.IFile" name="*.java"/> 
         </action> 
     </viewContribution> 
   </extension> 

Im oben dargestellten Beispiel wird die angegebene Aktion nur bei einer Einzelauswahl aktiviert (Attribut enablesFor). Außerdem muss das Objekt in der Auswahl eine Java-Dateiressource sein.

Das nächste Beispiel zeigt ebenfalls eine Erweiterung für eine Sichtaktion.

   <extension point="org.eclipse.ui.viewActions"> 
      <viewContribution 
         id="com.xyz.xyzViewC1" 
         targetID="org.eclipse.ui.views.navigator.ResourceNavigator"> 
         <menu
            id="com.xyz.xyzMenu" 
            label="XYZ Menu" 
            path="additions"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ2" 
            label="&amp;Run XYZ2 Tool" 
            menubarPath="com.xyz.xyzMenu/group1"
            style="push"
            icon="icons/runXYZ2.gif" 
            tooltip="Run XYZ2 Tool" 
            helpContextId="com.xyz.run_action_context2" 
            class="com.xyz.actions.RunXYZ2"> 
            <enablement>
               <and>
                  <objectClass name="org.eclipse.core.resources.IFile"/>
                  <not>
                     <objectState name="extension" value="java"/>
                  </not>
               </and>
            </enablement>
         </action> 
      </editorContribution> 
   </extension> 

In diesem Beispiel wird die angegebene Aktion als Menüoption angezeigt. Die Aktion ist aktiviert, wenn die Auswahl keine Java-Dateiressourcen enthält.

API-Informationen: Der Wert des Attributs class muss der vollständig qualifizierte Name einer Java-Klasse sein, die org.eclipse.ui.IViewActionDelegate implementiert. Diese Klasse wird so spät wie möglich geladen, um ein Laden des Plug-ins zu verhindern, bevor es wirklich benötigt wird.

Die Schnittstelle org.eclipse.ui.IViewActionDelegate erweitert org.eclipse.ui.IActionDelegate und fügt eine zusätzliche Methode hinzu, mit deren Hilfe der Stellvertreter mit dem Exemplar der Sicht initialisiert werden kann, für die die Ergänzung definiert ist.

An diesem Erweiterungspunkt können Aktionen in Menüs ergänzt werden, die zuvor durch die Zielsicht erstellt wurden. Wenn das Attribut für den Menüpfad nicht angegeben wird, wird das neue Menü bzw. die neue Aktion am Ende des Pulldown-Menüs hinzugefügt.

Die Aktivierungsbedingungen für eine Aktionserweiterung sind anfänglich durch enablesFor definiert, und ebenfalls durch selection oder enablement. Sobald der Aktionsstellvertreter als Exemplar erstellt wurde, kann er jedoch den Aktivierungsstatus der Aktion direkt in seiner Methode selectionChanged steuern.

Aktions- und Menübezeichnungen können Sonderzeichen enthalten und mnemonische Zeichen codieren. Hierbei gelten die folgenden Regeln:

  1. Mnemonische Zeichen werden angegeben, indem ein Et-Zeichen (&) vor ein ausgewähltes Zeichen des umsetzbaren Textes gesetzt wird. 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 zugegebenermaßen nicht beabsichtigt. Es wurde jedoch erst nach dem Festschreiben der Eclipse-Plattform-API festgestellt. 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

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
könnte beispielsweise auch folgendermaßen ausgedrückt werden:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Bereitgestellte Implementierung: Alle Sichten werden in der Regel mit einer Reihe von Standardoptionen im Pulldown-Menü und der lokalen Symbolleiste zur Verfügung gestellt. Zusätze, die aus anderen Plug-ins stammen, werden an den Standardinhalt angehängt.

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.