Aktionssets

Kennung: org.eclipse.ui.actionSets

Beschreibung: An diesem Erweiterungspunkt können Menüs, Menüoptionen und Symbolleistenschaltflächen zu den allgemeinen Bereichen des Workbenchfensters hinzugefügt werden. Diese Ergänzungen werden zusammengefasst als Aktionsset bezeichnet und im Workbenchfenster sichtbar gemacht, wenn der Benutzer eine Perspektive anpasst.

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

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

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

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

   <!ATTLIST actionSet
      id          CDATA #REQUIRED
      label       CDATA #REQUIRED
     visible     (true | false)
     description CDATA #IMPLIED
   >

   <!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|pulldown) "push"
     state            (true | false)
     pulldown         (true | false)
     class            CDATA #IMPLIED
     retarget         (true | false)
     allowLabelUpdate (true | false)
     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 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)>

   Dieses Element definiert die Aktivierung der Aktion.

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

   Dieses Element definiert die Sichtbarkeit der Aktion.

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

   Dieses Element stellt eine Boolesche Operation AND für das Auswertungsergebnis seiner beiden Unterelementausdrücke dar.

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

   Dieses Element stellt eine Boolesche Operation OR für das Auswertungsergebnis seiner beiden Unterelementausdrücke dar.

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

   Dieses Element stellt eine Boolesche Operation NOT für das Auswertungsergebnis seiner Unterelementausdrücke dar.

   <!ELEMENT objectClass EMPTY>

   Dieses Element wertet die Klasse oder Schnittstelle aller Objekte in der aktuellen Auswahl aus. Wenn jedes Objekt in der Auswahl die angegebene Klasse oder Schnittstelle implementiert, wird der Ausdruck mit dem Ergebnis "true" ausgewertet.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Dieses Element wertet den Attributstatus für alle Objekte in der aktuellen Auswahl aus. Wenn jedes Objekt in der Auswahl den angegebenen Attributstatus aufweist, wird der Ausdruck mit dem Ergebnis "true" ausgewertet. Damit dieser Typ Ausdruck ausgewertet wird, muss jedes Objekt 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>

   Dieses Element wertet den Status eines Plug-ins aus. Der Status eines Plug-ins kann installed oder activated lauten.

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

   <!ELEMENT systemProperty EMPTY>

   Dieses Element wertet den Status einer bestimmten Systemeigenschaft aus. Der Eigenschaftswert wird aus java.lang.System abgerufen.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Beispiele: Das folgende Beispiel zeigt ein Aktionsset (bitte beachten Sie insbesondere die Unterelemente sowie die Art des Attributeinsatzes):

    <extension point = "org.eclipse.ui.actionSets"> 
        <actionSet
            id="com.xyz.actionSet" 
            label="My Actions"> 
            <menu
               id="com.xyz.xyzMenu" 
               label="XYZ Menu"
               path="additions"> 
               <separator name="group1"/>
               <separator name="option1"/>
            </menu>
            
            <action
               id="com.xyz.runXYZ" 
               label="&amp;Run XYZ Tool"
               style="toggle"
               state="false"
               menubarPath="com.xyz.xyzMenu/group1" 
               icon="icons/runXYZ.gif" 
               tooltip="Run XYZ Tool" 
               helpContextId="com.xyz.run_action_context" 
               class="com.xyz.actions.RunXYZ" 
               enablesFor="1"> 
               <selection class="org.eclipse.core.resources.IFile" name="*.java"/> 
            </action>
            <action 
               id="com.xyz.runABC"
               label="&amp;Run ABC Tool"
               style="push"
               menubarPath="com.xyz.xyzMenu/group1"
               toolbarPath="Normal/XYZ"
               icon="icons/runABC.gif"
               tooltip="Run ABC Tool"
               helpContextId="com.xyz.run_abc_action_context"
               retarget="true"
               allowLabelUpdate="true">
               <enablement>
                  <and>
                     <objectClass name="org.eclipse.core.resources.IFile"/>
                     <not>
                        <objectState name="extension" value="java"/>
                     </not>
                  </and>
               </enablement>
            </action>             

            <action 
               id="com.xyz.runDEF"
               label="&amp;Run DEF Tool"
               style="radio"
               state="true"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runDEF.gif"
               tooltip="Run DEF Tool"
               class="com.xyz.actions.RunDEF" 
               helpContextId="com.xyz.run_def_action_context">
            </action>             
            <action 
               id="com.xyz.runGHI"
               label="&amp;Run GHI Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runGHI.gif"
               tooltip="Run GHI Tool"
               class="com.xyz.actions.RunGHI" 
               helpContextId="com.xyz.run_ghi_action_context">
            </action>             
            <action 
               id="com.xyz.runJKL"
               label="&amp;Run JKL Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runJKL.gif"
               tooltip="Run JKL Tool"
               class="com.xyz.actions.RunJKL" 
               helpContextId="com.xyz.run_jkl_action_context">
            </action>             
        </actionSet> 
    </extension> 

Im oben dargestellten Beispiel ist das angegebene Aktionsset "My Actions" anfänglich nicht in jeder Perspektive sichtbar, weil das Attribut visible nicht angegeben ist.

Die Aktion "XYZ" wird als Markierungsfeldoption angezeigt, die anfänglich nicht ausgewählt ist. Sie wird nur dann aktiviert, wenn der Auswahlzähler 1 beträgt und die Auswahl eine Java-Dateiressource enthält.

Die Aktion "ABC" wird sowohl im Menü als auch in der Symbolleiste angezeigt. Sie wird nur dann aktiviert, wenn die Auswahl keine Java-Dateiressourcen enthält. Bitte beachten Sie, dass es sich hierbei auch um eine Aktion für ein neues Bezeichnungsziel handelt. Daher wird kein Attribut class bereitgestellt.

Die Aktionen "DEF", "GHI" und "JKL" werden als Optionsfelder angezeigt. Sie sind - unabhängig vom aktuellen Status der Auswahl - immer aktiviert.

API-Informationen: Der Wert des Attributs "class" muss der vollständig qualifizierte Name einer Klasse sein, die org.eclipse.ui.IWorkbenchWindowActionDelegate oder org.eclipse.ui.IWorkbenchWindowPulldownDelegate implementiert. Letzteres sollte in Fällen implementiert werden, in denen für das Attribut style der Wert pulldown angegeben ist. Diese Klasse ist die Steuerroutine, die für die Ausführung der Aktion zuständig ist. Falls das Attribut retarget auf "true" gesetzt ist, wird dieses Attribut ignoriert und sollte nicht angegeben werden. 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 Aktivierungsbedingung für eine Aktionserweiterung ist anfänglich durch enablesFor definiert und ebenfalls durch selection oder enablement. Sobald der Aktionsstellvertreter als Exemplar erstellt wurde, kann sie den Aktionsaktivierungsstatus jedoch direkt in ihrer Methode selectionChanged steuern.

Es muss unbedingt beachtet werden, dass die Workbench die Generierung des Menüs für ein Plug-in nicht übernimmt. Menüpfade müssen auf Menüs verweisen, die bereits vorhanden sind.

Aktions- und Menübezeichnungen können Sonderzeichen für die Codierung von mnemonischen Zeichen enthalten. 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 entdeckt, nachdem die API für die Eclipse-Plattform festgeschrieben wurde. 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. So kann beispielsweise die folgende Codierung:

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
ebenfalls unter Verwendung der folgenden Angaben ausgedrückt werden:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Bereitgestellte Implementierung: Plug-ins können an diesem Erweiterungspunkt neue Menüs der höchsten Ebene zur Verfügung stellen. Plug-ins können außerdem benannte Gruppen definieren, in denen andere Plug-ins ihre Aktionen ergänzen können.

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 der Menüleistengruppe namens "additions" hinzugefügt.

Die Standardgruppen in einem Workbenchfenster sind in der Schnittstelle IWorkbenchActionConstants definiert. Diese Konstanten können zur dynamischen Ergänzung im Code verwendet werden. Die Werte können außerdem in eine XML-Datei kopiert werden, damit eine differenzierte Integration in die vorhandenen Menüs und die Symbolleiste der Workbench erreicht wird.

Verschiedene Menü- und Symbolleistenoptionen im Workbenchfenster werden algorithmisch definiert. In diesen Fällen muss ein separater Mechanismus verwendet werden, um das Fenster zu erweitern. Das Hinzufügen einer neuen Workbenchsicht führt beispielsweise dazu, dass im Menü "Perspektive" eine neue Menüoption angezeigt wird. Erweiterungen für Import- und Exportassistenten sowie für Assistenten für neue Ressourcen werden ebenfalls automatisch zum Fenster hinzugefügt.

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