Menus en incrustation

Identificateur : org.eclipse.ui.popupMenus

Description : ce point d'extension est utilisé pour ajouter de nouvelles actions aux menus en incrustation détenus par d'autres plug-ins. La contribution d'action peut être réalisée pour un type d'objet spécifique (objectContribution) ou pour un menu en incrustation spécifique. Lorsqu'elle est enregistrée pour un type d'objet, la contribution apparaît dans tous les afficheurs où sont sélectionnés des objets du type spécifié. En revanche, l'enregistrement sur un menu en incrustation apparaît uniquement dans le menu spécifié, quelle que soit la sélection.

Lorsque la sélection est hétérogène, la contribution est dans la mesure du possible, appliquée si elle est enregistrée pour un type courant de la sélection. Si une correspondance directe est impossible, la correspondance avec les super classes et les super interfaces est tentée.

La sélection peut être davantage limitée via l'utilisation d'un filtre de nom. Dans ce cas, tous les objets de la sélection doivent correspondre au filtre afin d'appliquer la contribution.

Des actions individuelles dans une contribution d'objet peuvent utiliser un attribut enablesFor pour spécifier s'il ne doit s'appliquer qu'à un seul, à plusieurs ou à tout autre type de sélection.

Si ces mécanismes de filtrage sont inappropriés, une contribution d'action peut utiliser le mécanisme des filtres. Dans ce cas, les attributs de l'objet cible sont décrits dans une série de paires clé-valeur. Les attributs qui s'appliquent à la sélection sont spécifiques au type et surpassent le domaine du plan de travail, aussi ce dernier délègue-t-il le filtrage à ce niveau à la sélection réelle.

Marques de configuration :

   <!ELEMENT objectContribution (filter | menu | action)*>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter  CDATA #IMPLIED
   >

   <!ELEMENT viewerContribution (menu | action)*>
   <!ATTLIST viewerContribution
      id        CDATA #REQUIRED
      targetID  CDATA #REQUIRED
   >    <!ELEMENT filter EMPTY>
   <!ATTLIST filter
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >    <!ELEMENT menu (separator)+>
   <!ATTLIST menu
      id         CDATA #REQUIRED
      label      CDATA #REQUIRED
      path       CDATA #IMPLIED
   >    <!ELEMENT separator EMPTY>
   <!ATTLIST separator
      name       CDATA #REQUIRED
   >
  • name : nom du séparateur auquel il peut être ultérieurement fait référence en tant que dernier jeton dans le chemin d'accès de l'action. De ce fait, les séparateurs servent de groupes désignés dans lesquels des actions peuvent être ajoutées.
  •    <!ELEMENT action EMPTY>
       <!ATTLIST action
          id                NMTOKEN #REQUIRED
          label             CDATA #REQUIRED
          menubarPath       CDATA #IMPLIED
          icon              CDATA #IMPLIED
          helpContextId     CDATA #IMPLIED
          state             (true | false) #IMPLIED
          class             CDATA #REQUIRED
          enablesFor        CDATA #IMPLIED
       > Les critères d'activation pour une extension d'action sont initialement définis par enablesFor et selection. 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 et les raccourcis-clavier 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;.
    2. Des raccourcis-clavier optionnels sont spécifiés à la fin du nom de la chaîne, à l'aide du caractère "@", suivi des séries de modificateurs et du caractère final du raccourci-clavier (par exemple, &amp;Save@Ctrl+S). Les raccourcis-clavier comportant plusieurs modificateurs sont obtenus en chaînant ces derniers, à l'aide du signe "+" comme délimiteur (comme dans @Ctrl+Shift+S).
    Exemples :

    L'exemple suivant est celui d'un point d'extension de menu en incrustation :

       <extension point="org.eclipse.ui.popupMenus">
          <objectContribution
             id="com.xyz.C1"
             objectClass="org.eclipse.core.resources.IFile"
             nameFilter="*.java">
             <menu id="com.xyz.xyzMenu"
                   path="additions"
                   label="&amp;XYZ Java Tools">
                <separator name="group1"/>
             </menu>
             <action id="com.xyz.runXYZ"
                  label="&amp;Run XYZ Tool"
                  menubarPath="com.xyz.xyzMenu/group1"
                  icon="icons/runXYZ.gif"
                  helpContextId="com.xyz.run_action_context"
                  class="com.xyz.actions.XYZToolActionDelegate"
                  enablesFor="1">
              </action>
            </objectContribution>
            <viewerContribution
               id="com.xyz.C2"
               targetID="org.eclipse.ui.views.TaskList">
               <action id="com.xyz.showXYZ"
                       label="&amp;Show XYZ"
                       menubarPath="additions"
                       icon="icons/showXYZ.gif"
                       helpContextId="com.xyz.show_action_context"
                       class="com.xyz.actions.XYZShowActionDelegate">
               </action>
            </viewerContribution>
         </extension>

    Dans l'exemple ci-dessus, l'action spécifiée n'activera qu'une seule sélection (l'attribut enablesFor). De plus, chaque objet de la sélection doit implémenter l'interface spécifiée (IFile) et doit être un fichier Java. Cette action sera ajoutée dans un sous-menu précédemment créé. Cette contribution sera effective dans toute vue comportant la sélection requise.

    En revanche, la contribution de l'afficheur ci-dessus n'apparaîtra que dans la vue des tâches et ne sera pas affectée par la sélection effectuée dans la vue.

    L'exemple ci-dessous est celui d'un mécanisme de filtrage. Dans ce cas, l'action apparaîtra uniquement pour les IMarkers achevés et dont la priorité est élevée.

       <extension point="org.eclipse.ui.popupMenus">
          <objectContribution
             id="com.xyz.C1"
             objectClass="org.eclipse.core.resources.IMarker">
             <filter name="done" value="true"/>
             <filter name="priority" value="2"/>
             <action id="com.xyz.runXYZ"
                  label="High Priority Completed Action Tool"
                  icon="icons/runXYZ.gif"
                  class="com.xyz.actions.MarkerActionDelegate">
              </action>
            </objectContribution>
         </extension>

    Informations d'API : la valeur de la classe de l'attribut d'action doit être un nom complet qualifié de classe Java qui implémente org.eclipse.ui.IObjectActionDelegate dans le cas de contributions d'objets, org.eclipse.ui.IViewActionDelegate pour les contributions aux afficheurs appartenant aux vues ou org.eclipse.ui.IEditorActionDelegate pour les contributions aux afficheurs appartenant éditeurs. Dans tous les cas, la classe d'implémentation est chargée aussi tard que possible afin d'éviter le chargement du plug-in tout entier avant qu'il ne soit réellement nécessaire.

    Remarque : Pour la compatibilité avec les versions antérieures, org.eclipse.ui.IActionDelegate peut être implémenté pour les contributions d'objets.

    L'extension d'un menu en incrustation dans un composant est possible uniquement si le composant cible publie un menu pour extension. Cette opération est vivement conseillée car elle améliore l'extensibilité du produit. Pour ce faire, chaque composant doit publier des menus en incrustation définis en appelant IWorkbenchPartSite#registerContextMenu. Une fois ceci fait, le plan de travail insère automatiquement toutes les extensions d'action qui existent.

    Un ID menu doit être fourni pour chaque menu enregistré. Pour plus de cohérence entre les composants, la stratégie énoncée ci-après doit être adoptée par toutes les classes d'implémentation de composant.

    Tout menu en incrustation en relation avec le plan de travail doit contenir un point d'insertion standard avec un id IWorkbenchActionConstants.MB_ADDITIONS. Les autres plug-ins utilisent cette valeur comme point de référence pour l'insertion. Le point d'insertion peut être défini en ajoutant un GroupMarker (marqueur de groupe) au menu à l'emplacement approprié pour l'insertion.

    Un objet du plan de travail qui est la sélection dans un menu contextuel peut définir un org.eclipse.ui.IActionFilter. Il s'agit d'une stratégie de filtrage qui peut effectuer des filtrages spécifiques au type. Le plan de travail extrait le filtre pour la sélection en testant pour voir s'il implémente IActionFilter. Si l'opération échoue, le plan de travail demandera un filtre via le mécanisme IAdaptable.

    Implémentation fournie : la vue du plan de travail comporte des menus en incrustation intégrés qui sont déjà chargés pour un certain nombre d'actions. Les plug-ins peuvent contribuer à ces menus. Si un afficheur a réservé des emplacements pour ces contributions et qu'ils sont rendus publics, les noms des emplacements peuvent être utilisés comme chemins d'accès. Sinon, les actions et les sous-menus seront ajoutés à la fin du menu en incrustation.

    Copyright IBM Corp. 2000, 2001. Tous droits réservés.