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.  

Chemins d'accès au menus

Penchons-nous d'abord sur les chemins d'accès aux menus en observant le menu Aide du plan de travail.

Groupes désignés dans le plan de travail

L'emplacement d'insertion de nouveaux menus et d'options se définit à l'aide de groupes désignés. Ces derniers s'apparentent à des emplacements ou marques de réservation permettant d'insérer des options de menu à certains points dans la barre de menu ou d'un menu déroulant.

Le plan de travail définit tous les noms d'emplacement de groupe dans les classes IWorkbenchActionConstants et IIDEActionConstants (deux classes différentes sont utilisées car les options de menu liées aux ressources ne se trouvent pas dans le plan de travail générique). 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"

Le menu d'aide du plan de travail standard définit un groupe nommé, appelé "start", qui est suivi d' un groupe nommé, appelé "end". La définition de deux groupes permet aux plug-ins de bénéficier d'un peu plus de contrôle sur le positionnement des options qu'ils mettent à disposition dans le menu d'aide. Lorsque vous définissez un menu, vous pouvez définir 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.

Les plug-ins qui ajoutent une option de menu au menu d'aide peuvent utiliser ces noms de groupe pour déterminer la position de leurs options de menu. Par exemple, le plug-in de l'aide-mémoire ajoute un ensemble d'actions contenant le menu "Aide-mémoire..." au plan de travail. Voici le marquage dans le fichier plugin.xml de org.eclipse.ui.cheatsheets.

<extension
	point="org.eclipse.ui.actionSets">
	<actionSet
		label="%CHEAT_SHEETS"
		visible="true"
		id="org.eclipse.ui.cheatsheets.actionSet">
		<action
			label="%CHEAT_SHEETS_MENU"
			class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction"
			menubarPath="help/helpStart"
			id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction">
		   </action>
	   </actionSet>
</extension>

La nouvelle action d'aide va être placée dans le menu d'aide, dans le groupe helpStart.

Chemins complets qualifiés d'accès aux menus

Un chemin complet d'accès au menu prend la forme "nom du menu/nom du groupe." La plupart des noms de menu du plan de travail sont définis dans IWorkbenchActionConstants (les noms de menu liés aux ressources sont définis dans IIDEActionConstants). Si vous recherchez le nom du menu d'aide dans cette classe, vous découvrez que le nom complet qualifié de l'action d'aide est "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 qui permet d'externaliser des chaînes qui s'affichent dans l'interface utilisateur. Les chaînes externalisées sont utilisées pour simplifier la traduction dans d'autres langues de l'interface utilisateur des plug-ins. Vous pouvez externaliser les chaînes des fichiers plugin.xml en remplaçant la chaîne par une touche (%CHEAT_SHEETS_MENU) et en créant des entrées dans le fichier plugin.properties sous la forme :

	CHEAT_SHEETS_MENU = Aide-mémoires...

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 la plupart des exemples présentés, les actions fournies par les plug-ins sont ajoutées à des groupes désignés existant dans des menus.

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.png"
		   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";  // Groupe.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Groupe.

A partir de ces informations, nous pouvons rassembler les éléments du chemin d'accès pour ajouter quelque chose au menu "Fenêtre" 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.  

Dans l'exemple d'outil de readme, nous utilisons l'attribut separator pour identifier les noms de groupes. Une ligne de séparateur apparaît alors entre ces groupes lorsqu'ils contiennent des éléments. A la place, nous pouvons employer l'attribut groupMarker afin de définir un groupe désigné sans créer de séparateurs dans le menu.

Chemins d'accès aux barres d'outils

Les chemins d'accès aux barres d'outils fonctionnement comme ceux aux menus.  

Barres d'outils désignées dans le plan de travail

La barre d'outils du plan de travail se compose de barres fournies par divers plug-ins, dont le plan de travail lui-même. Dans une barre d'outils donnée, des groupes désignés ou emplacements sont disponibles pour insérer de nouvelles options.    

La description ci-après des barres d'outils du plan de travail est adaptée de la définition de classe IWorkbenchActionConstants.

// ID de barres d'outils du plan de travail
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; 

// ID de barres d'outils du plan de travail. Pour ajouter un élément au début du groupe, 
// utilisez l'ID GROUP. Pour un ajout en fin de groupe, utilisez l'ID EXT.
public static final String PIN_GROUP = "pin.group"; 
public static final String HISTORY_GROUP = "history.group"; 
public static final String NEW_GROUP = "new.group"; 
public static final String SAVE_GROUP = "save.group"; 
public static final String BUILD_GROUP = "build.group"; 

Dans le scénario le plus simple, un plug-in peut ajouter une option de barre d'outils dans sa propre barre. Par exemple, les action de l'outil de readme ajoutées au menu reçoivent également un chemin d'accès :

<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="readme"
...

Sachant qu'il n'existe aucune référence aux chemins d'accès aux barres d'outils ou groupes du plan de travail, les actions de readme apparaissent dans leur propre groupe dans la barre d'outils. L'indication du chemin suivant place l'élément dans la barre d'outils de fichier, à l'intérieur du groupe de sauvegarde :

...
<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="org.eclipse.ui.workbench.file/save.group"
...

Les chemins d'accès définis dans IWorkbenchActionConstants peuvent être référencés dans ceux des barres d'outils d'autres plug-ins.

Ajout de jeux d'actions à un autre plug-in

Prenons un plug-in dont les options de la barre d'outils doivent être mieux intégrés avec des actions d'un autre plug-in. Observons comment le plug-in externe (org.eclipse.ui.externaltools) intègre son action avec la barre d'outils du débogueur. Le débogueur (org.eclipse.debug.ui) définit ses actions de barre d'outils comme suit :

<extension
      point="org.eclipse.ui.actionSets">
   	<actionSet
         label="%LaunchActionSet.label"
         visible="false"
         id="org.eclipse.debug.ui.launchActionSet">
   ...
   <action
         toolbarPath="debug"
         id="org.eclipse.debug.internal.ui.actions.RunDropDownAction"
         hoverIcon="icons/full/ctool16/run_exc.png"
         class="org.eclipse.debug.internal.ui.actions.RunToolbarAction"
         disabledIcon="icons/full/dtool16/run_exc.png"
         icon="icons/full/etool16/run_exc.png"
         helpContextId="run_action_context"
         label="%RunDropDownAction.label"
         pulldown="true">
   </action>
   ...

A l'instar de l'outil readme, le plug-in du débogueur définit son propre chemin de barre d'outils, les options se trouvant alors dans leur propre barre du plan de travail. Que fait alors le plug-in externe ?

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.ui.externaltools.ExternalToolsSet"
		label="%ActionSet.externalTools"
		visible="true">
		...
		<action
			id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			label="%Action.externalTools"
			toolbarPath="org.eclipse.debug.ui.launchActionSet/debug"
			disabledIcon="icons/full/dtool16/external_tools.png"
			icon="icons/full/etool16/external_tools.png"
			hoverIcon="icons/full/ctool16/external_tools.png"
			tooltip="%Action.externalToolsTip"
			pulldown="true"
			class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate">
		   </action>
	   </actionSet>
</extension>

Vous remarquez l'utilisation d'un ID de jeu d'actions du débogueur dans le chemin d'accès à la barre d'outils. Cette opération montre que l'option de barre d'outils doit être placée dans la barre employée par le jeu référencé. Dans un groupe de barres d'outils, les options sont classées par ID de jeux d'actions ; l'action des outils externes se produira donc après celles du débogueur. 

Dans le cas d'un ajout à la barre d'outils d'un jeu d'actions, de nouveaux groupes sont également définis.  Si le plug-in d'outils externes a pris comme chemin d'accès à la barre d'outils "org.eclipse.debug.ui.launchActionSet/external", un groupe est créé pour l'action dans la barre d'outils. Comme dans le cas de menus, les groupes de barres d'outils se distinguent par des séparateurs. 

Utilisation de chemins d'accès à partir d'un autre plug-in

En général, il n'est pas conseillé de contribuer au menu ou à la barre d'outils d'un autre plug-in en partant du nom de chemin dans plugin.xml, sauf s'il est précisément indiqué comme disponible pour des clients. Il est possible qu'une version ultérieure du plug-in puisse modifier les noms des chemins d'accès. Vous pouvez indiquer deux deux façons que les ID de jeux d'actions et chemins d'accès d'un plug-in sont corrects :