Menus Editeur, Barres d'outils et Actions

Identificateur : org.eclipse.ui.editorActions

Description : ce point d'extension est utilisé pour ajouter des actions au menu et à la barre d'outils d'éditeurs enregistrés par d'autres plug-in.

Le jeu de contributions initial d'un éditeur est défini par un autre point d'extension (org.eclipse.ui.editors). Un jeu d'actions est créé et partagé par toutes les instances du même type d'éditeur. Une fois appelée, cette action agit sur l'éditeur actif. Ce point d'extension suit le même schéma. Chaque extension d'action est créée et partagée par toutes les instances du même type d'éditeur. La classe d'action est requise pour implémenter org.eclipse.ui.IEditorActionDelegate. L'éditeur actif est transmis au délégué en invoquant IEditorActionDelegate.setActiveEditor.

L'activation et/ou visibilité d'une action se définissent respectivement à l'aide des éléments enablement et visibility. Ces deux éléments contiennent une expression booléenne qui entraîne l'activation et/ou la visibilité.

La syntaxe des éléments enablement et visibility est identique. Ils contiennent chacun un unique sous-élément d'expression booléenne. Dans les cas les plus simples, il s'agit d'un élément objectClass, objectState, pluginState ou systemProperty. Dans les cas plus complexes, les éléments and, or et not peuvent être combinés pour former une expression booléenne. Les éléments and et or doivent chacun contenir 2 sous-éléments. L'élément not ne doit en contenir qu'un.

Marques de configuration :

   <!ELEMENT extension (editorContribution+)>

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

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

   Cet élément définit un groupe d'actions et/ou de menus d'éditeur.

   <!ATTLIST editorContribution
      id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

   <!ELEMENT action (selection* | enablement?)>

   Cet élément définit une action que l'utilisateur peut appeler dans l'interface utilisateur.

   <!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*)>

   Cet élément définit un nouveau menu.

   <!ATTLIST menu
      id    CDATA #REQUIRED
      label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

   Cet élément crée un séparateur de menu dans le nouveau menu.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   Cet élément crée un groupe nommé dans le nouveau menu. Il ne possède aucune représentation visuelle dans le nouveau menu, à la différence de l'élément separator.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   Cet élément détermine l'activation de l'action en fonction de la sélection courante. Ignoré si l'élément enablement n'est pas spécifié.

   <!ATTLIST selection
     class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

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

   Cet élément définit l'activation de l'action.

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

   Cet élément définit la visibilité de l'action.

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

   Cet élément représente une opération booléenne AND en résultat de l'évaluation de ses deux expressions de sous-élément.

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

   Cet élément représente une opération booléenne OR en résultat de l'évaluation de ses deux expressions de sous-élément.

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

   Cet élément représente une opération booléenne NOT en résultat de l'évaluation de ses deux expressions de sous-élément.

   <!ELEMENT objectClass EMPTY>

   Cet élément évalue la classe ou l'interface de chaque objet de la sélection courante. Si chaque objet de la sélection implémente la classe ou l'interface spécifiée, l'expression est considérée vraie.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Cet élément évalue l'état d'attribut de chaque objet de la sélection courante. Si chaque objet de la sélection présente l'état d'attribut spécifié, l'expression est considérée vraie. Pour évaluer ce type d'expression, chaque objet de la sélection doit implémenter (ou s'adapter à) l'interface org.eclipse.ui.IActionFilter.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Cet élément évalue l'état d'un plug-in. L'état du plug-in est installé ou activé.

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

   <!ELEMENT systemProperty EMPTY>

   Cet élément évalue l'état de certaines propriétés système. La valeur de la propriété système est déterminée en appelant java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Exemples : Voici un exemple de point d'extension d'action d'éditeur :

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

Dans cet exemple, l'action spécifiée apparaîtra sous forme de case à cocher dans le nouveau menu de niveau supérieur nommé "XYZ Menu" et sous forme de bouton dans la barre d'outils. L'action est activée si la sélection ne contient que des ressources de fichier Java.

Voici un autre exemple de point d'extension d'action d'éditeur :

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

Dans cet exemple, l'action spécifiée apparaîtra sous forme d'option dans le sous-menu nommé "XYZ2 Menu" du menu "Edit" de niveau supérieur. L'action est activée si la sélection ne contient pas de ressources de fichier Java.

Informations d'API : la valeur de l'attribut class doit être un nom complet qualifié d'une classe Java qui implémente org.eclipse.ui.IEditorActionDelegate. Cette classe est chargée aussi tardivement que possible afin d'éviter le chargement du plug-in tout entier avant que cela ne soit réellement nécessaire. La méthode setActiveEditor sera appelée chaque fois qu'un éditeur du type spécifié est activé. Un seul jeu d'actions et de menus sera créé pour toutes les instances du type d'éditeur spécifié, quel que soit le nombre d'instances d'éditeur ouverts dans le plan de travail.

Ce point d'extension peut être utilisé pour ajouter des actions aux menus précédemment créés par l'éditeur cible. De plus, des menus et des actions peuvent être ajoutés à la fenêtre du plan de travail. Les identificateurs d'actions et les principaux groupes de la fenêtre du plan de travail sont définis dans org.eclipse.ui.IWorkbenchActionConstants. Ils doivent être utilisés comme point de référence pour l'ajout de nouvelles actions. Des menus de niveau supérieur sont créés à l'aide de la valeur suivante pour l'attribut path :

L'omission de l'attribut path entraîne l'ajout du nouveau menu au groupe de la barre de menus additions.

Les actions et les menus ajoutés à ces chemins d'accès ne s'affichent que lorsque l'éditeur associé est actif. Lorsque l'éditeur est fermé, les menus et les actions sont supprimés.

Les critères d'activation d'une extension d'action d'action sont initialement définis par enablesFor, et aussi par selection ou enablement. Cependant, une fois le délégué d'action instancié, il peut contrôler l'état d'activation de l'action directement dans sa méthode selectionChanged.

Les libellés d'actions et de menus peuvent contenir des caractères spéciaux qui encodent les mnémoniques en respectant les règles suivantes :

  1. Les mnémoniques sont spécifiées à l'aide du caractère perluète (&) placé devant un caractère sélectionné dans le texte traduit. Comme le caractère perluète n'est pas autorisé dans les chaînes XML, utilisez l'entité de caractère &amp;.
Si deux actions ou plus sont ajoutées à un menu ou une barre d'outils par une extension, elles apparaîtront dans l'ordre inverse de celui dans le fichier plugin.xml. Ce comportement est intuitif. Toutefois, il a été découvert qu'une fois l'API de plateforme Eclipse figée. Si vous modifiez ce comportement maintenant, vous endommagez chaque plug-in utilisant le comportement existant.

Les éléments selection et enablement sont mutuellement exclusifs. L'élément enablement peut remplacer l'élément selection en utilisant les sous-éléments objectClass et objectState. Par exemple :

 <selection

class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
peut s'exprimer comme suit :
 <enablement>
                  <and>
                     <objectClass
name="org.eclipse.core.resources.IFile"/>
                     <objectState
name="extension"
value="java"/>
               </and>
            </enablement>

Implémentation fournie : le plan de travail fournit un "éditeur de texte par défaut" intégré. Les plug-in peuvent contribuer à cet éditeur par défaut ou à ceux fournis par d'autres plug-in.

Copyright (c) 2000, 2003 IBM Corporation and others. All rights reserved. Ce programme et les produits qui l'accompagnent sont fournis sous licence v1.0 associée à cette distribution et disponibles à l'adresse suivante : http://www.eclipse.org/legal/cpl-v10.html