Menus, barres d'outils et actions des vues

Identificateur : org.eclipse.ui.viewActions

Description : ce point d'extension est utilisé pour ajouter des actions au menu déroulant et à la barre d'outils pour les vues enregistrées par d'autres plug-in. Chaque vue comporte un menu déroulant local que l'on active normalement en cliquant sur le bouton triangulaire supérieur droit. D'autres plug-in peuvent ajouter des sous-menus et des actions à ce menu. Les plug-in peuvent également ajouter des actions à la barre d'outils d'une vue. Les propriétaires de vue reçoivent en premier l'opportunité de remplir ces zones. Des ajouts optionnels sont réalisés par d'autres plug-in.

L'activation et/ou la visibilité d'une action peuvent être définies respectivement à l'aide des éléments enablement et visibility. Ces deux élément contiennent une expression booléenne qui est évaluée pour déterminer l'activation et/ou la visibilité.

La syntaxe utilisée pour les éléments enablement et visibility est la même. Ils contiennent tous deux un seul sous-élément d'expression booléenne. Dans le cas le plus simple, il s'agira d'un élément objectClass, objectState, pluginState ou systemProperty. Dans le cas le plus complexe, les éléments and, or et not peuvent être combinés pour former une expression booléenne. Les éléments and et or doivent contenir chacun deux sous-éléments. L'élément not doit uniquement contenir un sous-élément.

Marques de configuration :

   <!ELEMENT extension (viewContribution+)>

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

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

   Cet élément permet de définir un groupe d'actions et/ou de menus de vues.

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

   Cet élément est utilisé pour définir un nouveau menu.

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

   <!ELEMENT separator EMPTY>

   Cet élément permet de créer un séparateur de menus dans le nouveau menu.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   Cet élément permet de créer un groupe désigné dans le nouveau menu. Contrairement à l'élément separator, il n'a pas de représentation visuelle dans le nouveau menu.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   Cet élément permet d'aider à déterminer l'activation de l'action en fonction de la sélection en cours. Ignoré si l'élément enablement est spécifié.

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

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

   Cet élément permet de définir l'activation de l'action.

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

   Cet élément permet de définir la visibilité de l'action.

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

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

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

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

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

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

   <!ELEMENT objectClass EMPTY>

   Cet élément permet d'évaluer la classe ou l'interface de chaque objet de la sélection en cours. Si chaque objet de la sélection implémente la classe ou l'interface spécifiée, l'expression est considérée comme vraie ("true").

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Cet élément permet d'évaluer l'état d'attribut de chaque objet de la sélection en cours. Si chaque objet de la sélection possède l'état d'attribut spécifié, l'expression est considérée comme vraie ("true"). Pour évaluer ce type d'expression, chaque objet de la sélection doit implémenter l'interface org.eclipse.ui.IActionFilter ou s'y adapter.

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

   <!ELEMENT pluginState EMPTY>

   Cet élément permet d'évaluer l'état d'un plug-in. L'état du plug-in peut être soit installed, soit activated.

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

   <!ELEMENT systemProperty EMPTY>

   Cet élément permet d'évaluer l'état d'une propriété système. La valeur de la propriété est extraite de java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Exemples : L'exemple ci-dessous illustre une extension d'action de vue :

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

Dans cet exemple, l'action spécifiée ne sera activée que pour une seule sélection (attribut enablesFor). De plus, l'objet de la sélection doit être une ressource de fichier Java.

L'exemple ci-dessous illustre une autre extension d'action de vue :

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

Dans cet exemple, l'action spécifiée apparaîtra sous forme d'option de menu. L'action est activée si la sélection ne contient aucune ressource 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.IViewActionDelegate. 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.

L'interface org.eclipse.ui.IViewActionDelegate étend org.eclipse.ui.IActionDelegate et ajoute une méthode supplémentaire qui permet au délégué de s'initialiser avec la nouvelle instance de vue à laquelle elle contribue.

Ce point d'extension peut être utilisé pour ajouter des actions aux menus précédemment créés par la vue cible. L'omission de l'attribut de chemin d'accès du menu entraîne l'ajout du nouveau menu ou de la nouvelle action à la fin du menu déroulant.

Les critères d'activation pour une extension d'action sont initialement définis par enablesFor, ainsi que par selection ou enablement. Toutefois, 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 qui est utilisé dans le fichier plugin.xml. Il est admis que ce comportement n'est pas intuitif. Toutefois, il a été découvert après que l'API de la plateforme Eclipse a été figée. Si vous modifiez ce comportement maintenant, vous risquez d'endommager chaque plug-in qui utilise le comportement existant.

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

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
peut être exprimé à l'aide des lignes suivantes :
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Implémentation fournie : chaque vue est généralement fournie avec un certain nombre d'options standard dans le menu déroulant et la barre d'outils locale. Les ajouts provenant d'autres plug-in seront ajoutés au complément standard.

Copyright (c) 2000, 2003 IBM Corporation and others. All rights reserved. Ce programme et la documentation associée sont disponibles conformément aux dispositions de Common Public License v1.0 qui accompagne cette distribution et qui est disponible à l'adresse http://www.eclipse.org/legal/cpl-v10.html