Les aide-mémoires sont des vues spéciales qui guident l'utilisateur dans une série de tâches complexes afin d'atteindre un objectif général. Par exemple, un aide-mémoire peut être utilisé pour guider l'utilisateur lors de toutes les étapes nécessaires à la création, à la compilation et à l'exécution d'un programme Java simple. Les aide-mémoires sont lancés en sélectionnant l'option de menu Aide>Aide-mémoires.... Les aide-mémoires peuvent également être lancés à partir d'une page d'introduction.
Les aide-mémoires sont définis à l'aide du point d'extension org.eclipse.ui.cheatsheets.cheatSheetContent. Le contenu de l'aide-mémoire proprement dit est défini dans un fichier séparé afin de pouvoir plus facilement le traduire dans d'autres langues.
La contribution à un aide-mémoire est relativement simple. Observons un aide-mémoire fourni par l'outil JDT pour créer une application Java simple.
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...Comme pour les autres contributions au plan de travail, un nom, une description et un ID peuvent être spécifiés pour l'aide-mémoire. Le nom et la description sont affichés lorsque l'utilisateur accède à la liste accessible en sélectionnant Aide>Aide-mémoires.... Il est également possible de définir une catégorie pour l'aide-mémoire si vous souhaitez placer plusieurs aide-mémoires dans un groupement logique. Si aucune catégorie n'est spécifiée, l'aide-mémoire s'affiche dans la catégorie Autre.
Le travail réel pour les aide-mémoires est réalisé dans le fichier de contenu. Le fichier de contenu est un fichier XML dont le nom et l'emplacement sont spécifiés dans l'attribut contentFile. Le chemin d'accès au fichier est relatif par rapport au répertoire du plug-in (notez l'utilisation de la variable $nl$ dans le nom du répertoire, qui signifie que le fichier se trouve dans un répertoire spécifique à la langue nationale de l'environnement cible).
Le format de fichier proprement dit inclut les informations de présentation de l'aide-mémoire suivies d'une description de chaque étape (appelée élément) que l'utilisateur réalise. Au plus simple, un élément est juste une description détaillée de l'étape que l'utilisateur doit suivre. Cependant, un élément peut également spécifier une action qui peut être exécutée pour réaliser l'étape pour le compte de l'utilisateur. Observons la première partie du fichier de contenu (HelloWorld.xml) pour l'aide-mémoire Java.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Simple Java Application"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Bienvenue dans le didacticiel Java "Hello, World". Il va vous permettre de créer la fameuse application "hello world" et de l'essayer. Vous allez créer un projet Java et une classe Java qui va afficher "hello world" sur la console au cours de l'exécution. Commençons ! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Open the Java Perspective"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Sélectionnez Window->Ouvrir une perspective->Java dans la barre de menus dans la partie supérieure du plan de travail. Cette étape modifie la perspective pour configurer le plan de travail Eclipse pour le développement Java. Vous pouvez cliquer sur le bouton "Cliquer pour réaliser l'opération" pour que la perspective "Java" s'affiche automatiquement. </description> </item> ...
Le titre et les informations d'introduction sont affichés dans la partie supérieure de l'aide-mémoire. Ensuite, les éléments sont décrits. Le premier élément de cet aide-mémoire décrit comment ouvrir la perspective Java. Mieux encore, l'attribut action spécifie une classe qui peut être utilisée pour exécuter l'action pour le compte de l'utilisateur. La classe doit implémenter IAction. Cela s'avère plutôt pratique, car cela permet de réutiliser les classes d'action développées pour les contributions au menu ou à la barre d'outils.
La classe pour l'action a la possibilité d'implémenter ICheatSheetAction si l'action utilise des paramètres ou doit connaître l'existence de l'aide-mémoire et de son état. En pareil cas, un tableau et une référence à ICheatSheetManager sont transmis à l'action afin qu'elle puisse demander d'autres informations relatives à l'aide-mémoire. Il est possible de transmettre tout paramètre nécessaire à la méthode run de l'action à l'aide de l'attribut paramN.
Il est fortement recommandé de définir les actions appelées de telle sorte qu'elles signalent une réussite/un échec si l'exécution de l'action peut échouer (par exemple, l'utilisateur peut annuler l'action dans une boîte de dialogue). Pour plus d'informations, reportez-vous à IAction.notifyResult(boolean).
Les éléments n'ont pas besoin de définir des actions. Si l'élément doit être réalisé manuellement par l'utilisateur, vous n'avez pas besoin de spécifier d'action. Voici la troisième étape de l'aide-mémoire Java, qui indique simplement à l'utilisateur comment développer le code de l'application simple. Lorsque aucune action n'est spécifiée, la description de l'élément doit indiquer à l'utilisateur d'appuyer sur le bouton approprié une fois que la tâche est terminée.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Add a System.out.println line in your main method"> <description> A présent, vous disposez de la classe HelloWorld. Dans la méthode "public static void main", ajoutez l'instruction suivante : System.out.println("Hello world!"); et enregistrez vos modifications. Appuyez sur le bouton "cliquez lorsque l'opération est terminé" ci-dessous lorsque l'opération est terminée. </description> </item>Les autres attributs contrôlent si l'élément peut être totalement ignoré et détermine l'élément à lancer si l'utilisateur demande de l'aide au cours de l'étape. Pour obtenir une description de tous les attributs qui peuvent être définis dans un aide-mémoire, reportez-vous à la documentation du point d'extension org.eclipse.ui.cheatsheets.cheatSheetContent.
Les sous-éléments peuvent être définis pour organiser de manière plus précise la présentation d'un élément. Contrairement aux éléments, les sous-éléments n'ont pas besoin d'être visité dans un ordre particulier. Les sous-éléments peuvent également définir des actions qui réalisent automatiquement la sous-tâche de l'utilisateur. Les actions des sous-éléments sont décrites de la même manière que les actions des éléments.
Il est possible d'utiliser des expressions conditionnelles pour définir des éléments de l'aide-mémoire dont le contenu ou le comportement dépend d'une condition déterminée qui est vraie. Les conditions sont décrites dans l'élément condition d'un sous-élément à l'aide de valeurs de chaîne arbitraires comparées à l'attribut when pour chaque option. Les conditions renvoient référencent généralement des variables d'aide-mémoire à l'aide du formulaire ${var}, où var fait référence au nom d'une variable d'aide-mémoire. Voici quelques exemples simples illustrant le fonctionnement des expressions conditionnelles.
Les sous-éléments conditionnelles peuvent être utilisés pour choisir un sous-élément dans une liste de sous-éléments possibles. Seul le premier sous-élément dont l'attribut when correspond à l'attribut de condition est inclus dans l'aide-mémoire. Par exemple :
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>Cet élément spécifie deux sous-éléments possibles qui dépendent de la valeur de la variable v1. Si la valeur de la variable est a, c'est le premier sous-élément qui est inclus. Si la valeur de la variable est b, c'est le second sous-élément qui est inclus. Si la variable ne correspond à aucune des deux valeurs, une erreur est générée.
Les actions conditionnelles sont similaires aux sous-éléments conditionnels. L'élément perform-when spécifie une condition pour réaliser une action parmi une liste d'actions possibles. La condition est décrite de la même manière à l'aide d'une chaîne arbitraire qui fait souvent référence à une variable. L'action dont l'attribut when correspond à la condition est celle qui va être réalisée. Par exemple :
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>L'action à réaliser est choisie en fonction de la valeur de la variable v1. Si la valeur de la variable n'est ni a ni b, une erreur est générée.
Les sous-éléments répétés décrivent un sous-élément qui peut se diviser en 0, 1 ou plus de sous-étapes similaires. Les sous-étapes sont individualisées à l'aide la variable spéciale ${this}. Cette variable va être remplacée par les valeurs spécifiées dans l'attribut values. L'attribut de valeur est une chaîne de valeurs séparées par des virgules. Il est possible d'utiliser une variable qui se développe sous forme de liste de valeurs. Par exemple :
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}" /> </repeated-subitem> </item>Si la valeur de la variable est 1,b,three, les trois sous-éléments s'affichent dans l'aide-mémoire, chacun possédant une étiquette unique ("Etape 1," "Etape b," "Etape trois"). La variable peut être utilisée dans l'étiquette ou dans la valeur de paramètre d'action. Elle est également accessible à partir de ICheatSheetManager en cours d'exécution de l'action.
Dans certains cas, vous souhaitez peut-être modifier d'autres parties de l'interface utilisateur si un aide-mémoire est actif. Par exempte, vous pouvez disposer d'un éditeur qui affiche des annotations spéciales si un aide-mémoire guide l'utilisateur tout au long d'une tâche de modification. En pareil cas, un écouteur peut être spécifié comme attribut de l'aide-mémoire. L'attribut de l'écouteur doit être le nom complet qualifié d'une classe Java qui définit des sous-classes de CheatSheetListener. Les modules d'écoute reçoivent des notifications en même temps que ICheatSheetEvent lorsqu'une modification est apportée au cycle de vie de l'aide-mémoire à l'ouverture, à la fermeture ou la fin, par exemple.
L'extension org.eclipse.ui.cheatsheets.cheatSheetItemExtension peut être utilisée pour contribuer à des attributs arbitraires dans un aide-mémoire pré-existant. L'objectif de ce point d'extension est de permettre à un plug-in d'ajouter d'autres boutons qui vont aider l'utilisateur dans une étape déterminée. Ces boutons sont affichés en regard de l'icône d'aide.
Pour utiliser ce mécanisme, vous pouvez définir un attribut arbitraire dans une définition d'élément dans le fichier XML de l'aide-mémoire. Le nom d'attribut est comparé aux attributs fournis dans les extensions dans org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Pour plus d'informations, reportez-vous à la documentation relative aux points d'extension.