Menüs, Symbolleisten und Aktionen in Editoren

Kennung: org.eclipse.ui.editorActions

Beschreibung: An diesem Erweiterungspunkt können Aktionen zu den Menü- und Symbolleisten von Editoren hinzugefügt werden, die durch andere Plug-ins definiert werden.

Das anfängliche Ergänzungsset für einen Editor wird durch einen anderen Erweiterungspunkt (org.eclipse.ui.editors) definiert. Ein Aktionsset wird erstellt und von allen Exemplaren desselben Editortyps gemeinsam verwendet. Sobald es aufgerufen wird, gelten diese Aktionen für den aktiven Editor. Dieser Erweiterungspunkt folgt demselben Muster. Jede Aktionserweiterung wird erstellt und von allen Exemplaren desselben Editortyps gemeinsam verwendet. Die Klasse "action" wird benötigt, um org.eclipse.ui.IEditorActionDelegate zu implementieren. Der aktive Editor wird an den Stellvertreter übergeben, indem IEditorActionDelegate.setActiveEditor aufgerufen wird.

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

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 (editorContribution+)>

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

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

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

   <!ATTLIST editorContribution
      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
     accelerator   CDATA #IMPLIED
     definitionId  CDATA #IMPLIED
     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
     actionID      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 eine benannte Gruppe im neuen Menü 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)>

   Dieses Element definiert die Aktivierung für die Aktion.

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

   Dieses Element definiert die Sichtbarkeit für die Aktion.

   <!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. Zur Auswertung dieses Typs Ausdruck müssen alle Objekte in der Auswahl die Schnittstelle org.eclipse.ui.IActionFilter implementieren oder 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 eine Erweiterung für Editoraktionen.

   <extension point="org.eclipse.ui.editorActions"> 
      <editorContribution 
         id="com.xyz.xyzContribution" 
         targetID="com.ibm.XMLEditor"> 
         <menu
            id="XYZ"
            label="&amp;XYZ Menu"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            menubarPath="XYZ/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> 
      </editorContribution> 
   </extension> 

In diesem Beispiel wird die angegebene Aktion im neuen Menü der obersten Ebene namens "XYZ Menu" durch ein Markierungsfeldelement und in der Symbolleiste durch eine Umschaltfläche dargestellt. Die Aktion ist nur dann aktiviert, wenn die Auswahl ausschließlich Java-Dateiressourcen enthält.

Das nächste Beispiel zeigt ebenfalls eine Erweiterung für Editoraktionen:

   <extension point="org.eclipse.ui.editorActions"> 
      <editorContribution 
         id="com.xyz.xyz2Contribution" 
         targetID="com.ibm.XMLEditor"> 
         <menu 
            id="XYZ2" 
            label="&amp;XYZ2 Menu" 
            path="edit/additions"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ2" 
            label="&amp;Run XYZ2 Tool" 
            menubarPath="edit/XYZ2/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> 

Im oben dargestellten Beispiel wird die angegebene Aktion als Menüoption im Untermenü namens "XYZ2 Menu" angezeigt, das zum Menü "Edit" der höchsten Ebene gehört. 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.IEditorActionDelegate 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 Methode setActiveEditor wird immer dann aufgerufen, wenn ein Editor des angegebenen Typs aktiviert wird. Für alle Exemplare des angegebenen Editortyps wird jeweils nur ein Set mit Aktionen und Menüs erstellt, und zwar unabhängig von der Anzahl der Editorexemplare, die gegenwärtig in der Workbench geöffnet sind.

An diesem Erweiterungspunkt können Menüs, die zuvor durch den Zieleditor erstellt wurden, durch Aktionen ergänzt werden. Außerdem kann das Workbenchfenster durch Menüs und Aktionen ergänzt werden. Die Kennungen für Aktionen und Hauptgruppen im Workbenchfenster sind in org.eclipse.ui.IWorkbenchActionConstants definiert. Sie sollten als Referenzpunkt für das Hinzufügen neuer Aktionen verwendet werden. Menüs der höchsten Ebene werden erstellt, indem die folgenden Werte für das Attribut "path" verwendet werden:

Wenn das Attribut "path" nicht angegeben wird, wird das neue Menü in die Menüleistengruppe "additions" eingefügt.

Aktionen und Menüs, die zu diesen Pfaden hinzugefügt werden, werden nur dann angezeigt, wenn der zugeordnete Editor aktiv ist. Beim Schließen des Editors werden die Menüs und Aktionen entfernt.

Die Aktivierungsbedingungen für eine Aktionserweiterung werden anfänglich durch enablesFor definiert, und außerdem entweder durch selection oder enablement. Sobald der Aktionsstellvertreter als Exemplar erstellt wurde, kann er jedoch den Aktionsaktivierungsstatus direkt in seiner Methode selectionChanged steuern.

Aktions- und Menübezeichnungen können Sonderzeichen enthalten, die 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 festgestellt, nachdem die API für die Eclipse-Plattform festgeschrieben wurde. 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 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 stellt einen integrierten Standardtexteditor zur Verfügung. Plug-ins können diesen Standardeditor ergänzen wie auch Editoren, die durch andere Plug-ins bereitgestellt werden.

Copyright (c) 2000, 2003 IBM Corporation und Andere. Alle Rechte vorbehalten. Dieses Programm und sein Begleitmaterial werden gemäß den Bedingungen 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.