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.
Penchons-nous d'abord sur les chemins d'accès aux menus en observant le menu Aide du 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 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 "Contenu de l'aide" 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.
Le format d'un chemin d'accès complet est "nom menu/nom groupe." Les noms de menus du 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."
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é.
Dans la plupart des exemples présentés, les actions contribuées 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.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" 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.
Les chemins d'accès aux barres d'outils fonctionnement comme ceux aux menus.
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.
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.gif" class="org.eclipse.debug.internal.ui.actions.RunToolbarAction" disabledIcon="icons/full/dtool16/run_exc.gif" icon="icons/full/etool16/run_exc.gif" 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.gif" icon="icons/full/etool16/external_tools.gif" hoverIcon="icons/full/ctool16/external_tools.gif" 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.
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 :