Chemins d'accès aux menus et à la barre d'outils

Nous avons abordé de nombreuses contributions d'actions qui spécifient le chemin d'accès à l'emplacement de leur action. Examinons de plus près la signification de ces chemins d'accès. Pour ce faire, nous utiliserons le menu Aide du plan de travail.

Groupes désignés

Les emplacements d'insertion de nouveaux menus, options de menu ou éléments de barre d'outils sont définis à l'aide de groupes désignés. Vous pouvez considéré un groupe désigné comme un emplacement ou une marque de réservation qui vous permet d'insérer vos contributions de menu et de barre d'outils à certains points d'un menu ou d'une barre d'outils.

Le plan de travail définit tous les noms des emplacements de groupe dans la classe IWorkbenchActionConstants. Pour chaque menu du plan de travail, des groupes désignés sont placés dans le menu aux endroits où il est attendu que des plug-in insèrent de nouvelles actions.

La description ci-dessous du menu d'aide est adaptée de la définition de la classe IWorkbenchActionConstants.

   Actions du menu Aide standard
   Groupe de début - HELP_START - "start"
   Groupe de fin - HELP_END - "end"
   A propos de l'action - ABOUT - "About"

Le menu d'aide standard du plan de travail est constitué d'un groupe désigné appelé "start", suivi d'un groupe désigné appelé "end", suivi de l'action "About". La définition de deux groupes offre aux plug-in un contrôle accru sur l'emplacement des éléments ajoutés dans le menu d'aide. Lorsque vous définissez un menu, vous pouvez choisir autant d'emplacements que vous le souhaitez. L'ajout d'emplacements supplémentaires donne aux autres plug-in plus de contrôle sur l'endroit où leurs contributions apparaissent par rapport aux contributions existantes.

Nous savons qu'il existe d'autres options de menu dans le menu Aide. Elles sont ajoutées par des plug-in. Par exemple, le plug-in d'aide ajoute un jeu d'actions contenant le menu "Help Contents" au plan de travail. Les marques ci-dessous sont extraites du fichier plugin.xml du plug-in org.eclipse.help.ui.

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.help.internal.ui.HelpActionSet"
		label="%help"
		visible="true">
			
	<action id="org.eclipse.help.internal.ui.HelpAction"
		menubarPath="help/helpEnd"
		label="%helpcontents"
		class="org.eclipse.help.ui.internal.HelpContentsAction"
		icon="icons/view.gif"
		helpContextId="org.eclipse.help.ui.helpContentsMenu"
		tooltip="%openhelpcontents"/>
	...

La nouvelle action de l'aide sera placée dans le menu d'aide, dans le groupe helpEnd. Si aucun autre plug-in n'a contribué au menu d'aide, cela signifie que l'option de menu "Help Contents" apparaîtra comme première option du menu au dessus de l'option "About". Si Un autre plug-in veut ajouter une option apparaissant toujours au-dessus de l'option "Help Contents", il peut indiquer le groupe helpStart dans son chemin.  

Les chemins d'accès de la barre d'outils fonctionne de façon similaire. Chaque fois qu'un chemin d'accès est spécifié, il doit se terminer par le nom d'un groupe dans la barre d'outils.

Chemins d'accès complets qualifié de menu et de barre d'outils

Un chemin d'accès complet à un menu ou une barre d'outils se compose simplement de "nom du menu/nom du groupe." Les noms de menus pour le plan de travail sont définis dans IWorkbenchActionConstants. Cette classe est utiliser pour identifier le nom du chemin d'accès qualifié complet pour notre action d'aide comme "help/helpEnd."

Certains menus comportent des sous-menus imbriqués. C'est là qu'entrent en jeu les chemins d'accès plus longs. Si le menu d'aide a défini un sous-menu appelé "submenu" avec un groupe désigné appelé "submenuStart", le chemin d'accès complet qualifié du menu pour une action dans le nouveau sous-menu doit être "help/submenu/submenuStart."

Externalisation des libellés de l'interface utilisateur

L'exemple ci-dessus illustre une technique d'externalisation de chaînes apparaissant dans l'interface graphique. Les chaînes externalisées sont utilisées pour simplifier la traduction l'interface du plug-in dans d'autres langues. Vous pouvez externaliser les chaînes dans les fichiers plugin.xml en les remplaçant par une clé (telle que %help, %helpcontents) et en créant des entrées dans le fichier plugin.properties, comme suit :

   help = "Help"
   helpContents = "Help Contents"

Le fichier plugin.properties peut être traduit dans différentes langues et le fichier plugin.xml n'aura pas besoin d'être modifié.

Ajout de nouveaux menus et groupes

Dans de nombreux exemples abordés jusque là, les actions fournies par les exemples de plug-in ont été ajoutées aux groupes désignés existants dans des menus et des barres d'outils.

Les points d'extension actionSets, viewActions, editorActions et popupMenus permettent également de définir de nouveaux menus et groupes dans votre contribution. Ceci signifie que vous pouvez définir de nouveaux sous-menus ou de nouveaux menus déroulants et ajouter vos actions à ces nouveaux menus. Dans ce cas, le chemin d'accès de votre nouvelle action contient le nom du menu nouvellement défini.

Nous avons vu cette technique lorsque l'outil readme a défini un nouveau menu pour son jeu d'actions. Examinons encore une fois les marques, maintenant que nous avons détaillé les chemins d'accès au menu.

   <extension point = "org.eclipse.ui.actionSets">
   <actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
	   label="%ActionSet.name"
	   visible="true">
	   <menu id="org_eclipse_ui_examples_readmetool"
		   label="%ActionSet.menu"
		   path="window/additions"> 
		   <separator name="slot1"/>
		   <separator name="slot2"/>
		   <separator name="slot3"/>
	   </menu>
	   <action id="org_eclipse_ui_examples_readmetool_readmeAction"
		   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
		   toolbarPath="readme"
		   label="%ReadmeAction.label"
		   tooltip="%ReadmeAction.tooltip"
		   helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
		   icon="icons/ctool16/openbrwsr.gif"
		   class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
		   enablesFor="1">
		   <selection class="org.eclipse.core.resources.IFile"
				name="*.readme">
		   </selection>
	   </action>
	   ...

Nous avons ajouté un menu nommé "org_eclipse_ui_examples_readmetool" dont le libellé est défini par la clé "%ActionSet.name" dans le fichier de propriétés. Dans ce menu, nous définissons trois groupes : "slot1," "slot2," et "slot3." Nous ajoutons ce nouveau menu au chemin d'accès "window/additions."

Si nous revenons à IWorkbenchActionConstants, nous voyons cette définition du menu Fenêtre dans la documentation Java :

    * <h3>Actions du menu Fenêtre standard</h3>
    * <ul>
    * <li>Groupe d'actions de type fenêtre (<code>WINDOW_EXT</code>)</li>

Si nous examinons encore plus la définition de la classe, nous trouvons les définitions connexes suivantes :

   public static final String MENU_PREFIX = "";
   ...
   public static final String M_WINDOW = MENU_PREFIX+"window";
   ...
   public static final String MB_ADDITIONS = "additions";  // Group.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Group.

A partir de ces informations, nous pouvons rassembler les éléments du chemin d'accès pour ajouter quelque chose au menu "Fenêtre" (Window) du plan de travail. Le menu lui-même est appelé "window" et il définit un emplacement appelé "additions". Nous utilisons le chemin d'accès "window/additions" pour ajouter notre nouveau menu.

Dans la déclaration du jeu d'actions, nous ajoutons une action à notre menu nouvellement défini, à l'aide du chemin d'accès "window/org_eclipse_ui_examples_readmetool/slot1".

D'autres plug-in peuvent contribuer à notre menu en utilisant le même chemin d'accès (ou peut-être l'un des autres emplacements) pour ajouter un de leurs propres menus.  

En règle générale, il n'est pas judicieux de contribuer au menu ou à la barre d'outils d'un autre plug-in en faisant dériver le nom du chemin d'accès du fichier plugin.xml. Il est possible qu'une version future du plug-in change les noms des chemins d'accès. La pratique recommandée consiste à définir une interface publique (un peu comme IWorkbenchActionConstants) qui spécifie exactement quels menus, groupes de barre d'outils et emplacements sont considérés aptes à être utilisés par d'autres plug-in.

Copyright IBM Corp. and others 2000,2002.