Version 3.0
Le présent document décrit la structure du fichier de contenu de l'aide-mémoire sous la forme de fragments DTD (schéma XML lisible une machine).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
L'élément <cheatsheet> définit le corps du fichier de contenu de l'aide-mémoire. Les attributs <cheatsheet> sont les suivants :
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
L'élément <intro> permet de décrire l'introduction de l'aide-mémoire à afficher. Le sous-élément <description> contient le corps de l'introduction. Les attributs <intro> sont les suivants :
description
<!ELEMENT description EMPTY> <!ATTLIST description >
L'élément <description> contient la description d'un aide-mémoire ou d'un élément de l'aide-mémoire. La description correspond à un texte associé à des balises de formatage simples. L'aide-mémoire formate et dispose automatiquement le texte afin de permettre un affichage optimal dans l'interface utilisateur. Au sein du texte, les balises <b>...</b> permettent de mettre en gras le texte qu'elles encadrent et l'élément <br/> peut être utilisé pour forcer un retour à ligne. Ces balises sont les seules balises prises en charge pour le moment. (Toutefois, d'autres pourraient être ajoutées dans le futur). Certains caractères utilisés dans le texte ont une signification particulière pour les programmes d'analyse syntaxique ; Par exemple, pour indiquer "<", ">", "&", "'" et """ (guillemet), indiquez respectivement "<", ">", "&", "'" et """. Les espaces (espaces et retours à la ligne) sont traités comme des séparateurs de mots ; Les espaces adjacents et les retours à la ligne sont traités comme des unités et apparaissent sous la forme d'un espace ou d'un retour à la ligne unique. Les espaces placés immédiatement après les balises <description> et <br/> sont ignorés tout comme ceux situés juste avant la balise </description>.
item
<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Chaque élément <item> décrit une étape de niveau supérieur dans un aide-mémoire. L'élément <item> est simple ou composé. Les attributs <item> sont les suivants :
org.eclipse.ui.cheatsheets.cheatSheetItemExtension permet de disposer d'autres options personnalisées pour l'affichage de l'élément dans l'interface utilisateur. Les contributions à ce point d'extension déclarent les noms des attributs supplémentaires (chaînes) qui peuvent apparaître pour les éléments <item>.
Les éléments simples sont associés à une description et une action facultative. Dans une présentation standard, les titres des éléments de l'aide-mémoire sont affichés. La description d'un élément apparaît uniquement lorsque l'étape est en cours d'exécution. La présence d'un élément <action> (ou <perform-when>) est généralement associé à un bouton sur lequel l'utilisateur peut cliquer pour exécuter l'action associée à l'étape. Si aucune action n'est disponible, l'étape doit être exécutée manuellement par l'utilisateur et le programme doit indiquer qu'elle s'est déroulée correctement.
Les étapes composées se divisent en sous-étapes indiquées par les sous-éléments <subitem>. Contrairement aux éléments, qui doivent être utilisés dans un ordre précis, les sous-éléments peuvent être exécutés dans n'importe quel ordre. Tous les sous-éléments d'un élément doivent être exécutés (ou ignorés) pour permettre l'accès à l'élément suivant. (Les actions qui doivent être effectuées dans un ordre déterminé ne doivent donc pas être représentées sous forme de sous-éléments.)
Un sous-élément <conditional-subitem> permet de personnaliser la présentation d'une sous-étape en fonction de variables de l'aide-mémoire, dont les valeurs sont obtenues lors des étapes précédentes. Un sous-élément <repeated-subitem> permet à une étape d'inclure un ensemble de sous-étapes identiques. De même, l'ensemble de sous-étapes peut reposer sur des variables dont les valeurs sont obtenues lors des étapes précédentes.
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Chaque élément <subitem> décrit une sous-étape de l'aide-mémoire. Un élément <subitem> contient un libellé simple mais ne comporte pas de description détaillée ni d'autres sous-éléments. Les attributs <subitem> sont les suivants :
Les sous-éléments disposent d'une action facultative. La présence d'un élément<action> (ou <perform-when>) est généralement associé à un bouton sur lequel l'utilisateur peut cliquer pour exécuter l'action de la sous-étape. Si aucune action n'est disponible, l'étape doit être exécutée manuellement par l'utilisateur et le programme doit indiquer qu'elle s'est déroulée correctement.
Contrairement aux éléments, qui doivent être utilisés dans un ordre précis, les sous-éléments peuvent être exécutés dans n'importe quel ordre. Tous les sous-éléments d'un élément doivent être exécutés (ou ignorés) pour permettre l'accès à l'élément suivant. (Les actions qui doivent être effectuées dans un ordre déterminé ne doivent donc pas être représentées sous forme de sous-éléments.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Chaque élément <conditional-subitem> décrit une sous-étape unique dont la forme peut varier en fonction d'une condition connue lorsque l'élément est développé. Les attributs <conditional-subitem> sont les suivants :
L'attribut condition de l'élément <conditional-subitem> fournit une chaîne (cette chaîne provient d'une variable de l'aide-mémoire). Chacun des enfants <subitem> doit être associé à un attribut when doté d'une chaîne distincte. Lorsque l'élément est développé, l'élément <conditional-subitem> est remplacé par l'élément <subitem> avec la chaîne correspondante. S'il n'y a pas d'élément <subitem> avec une chaîne concordante, le programme considère qu'il y a une erreur.
Par exemple, si la variable de l'aide-mémoire "v1" correspond à la chaîne "b" lorsque l'élément suivant est développé
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>le second sous-élément est sélectionné et l'élément est développé sous la forme suivante :
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Chaque élément <repeated-subitem> décrit un sous-élément qui comporte aucune, une ou plusieurs sous-étapes identiques. Les attributs de l'élément <repeated-subitem> sont les suivants :
L'attribut values fournit une liste de chaînes séparées par des virgules ; l'enfant <subitem> fournit le modèle. Lorsque l'élément est développé, l'élément <repeated-subitem> est remplacé par les copies de l'élément <subitem> avec les occurrences de la variable "this" remplacées par la chaîne correspondante.
Par exemple, si la variable de l'aide-mémoire "v1" correspond à la chaîne "1,b,three" lorsque l'élément suivant est développé
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>l'élément est développé sous la forme suivante :
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Chaque élément <action> décrit une action dans l'aide-mémoire. Les attributs <action> sont les suivants :
org.eclipse.jface.action.IAction
.
Si cette action implémente également org.eclipse.ui.cheatsheets.ICheatSheetAction
, elle est appelée via sa méthode
run(String[],ICheatSheetManager) et le gestionnaire d'aide-mémoire et les paramètre d'action sont transmis. Lorsque cet attribut est indiqué, l'attribut pluginId doit être utilisé. Il est fortement recommandé que les actions à appeler à partir de l'aide-mémoire indiquent la réussite ou l'échec d'une procédure, si l'exécution de l'action risque d'échouer (peut-être lorsque l'utilisateur annule l'action à partir de la boîte de dialogue). (Pour plus d'informations,
reportez-vous à org.eclipse.jface.action.Action.notifyResult(boolean).)org.eclipse.ui.cheatsheets.ICheatSheetAction
,
les valeurs (chaîne) de ces attributs sont transmises à l'action lors de l'invocation. Vous pouvez transmettre jusqu'à 9 paramètres à une action d'aide-mémoire (param1, param2, etc.). Les paramètres fournis doivent commencer par le paramètre 1
et être contigus ; vous ne pouvez pas indiquer param2 sans spécifier param1. Si la chaîne de l'attribut apparaît sous la forme "${var}", le programme la considère comme une référence à la variable de l'aide-mémoire var et la valeur de la condition correspond à celle de la variable de l'aide-mémoire au début de l'exécution de l'élément conteneur <item> (ou à une chaîne vide si la variable n'est pas liée à ce stade).perform-when
<!ELEMENT perform-when (action+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Chaque élément <perform-when> décrit une action dans l'aide-mémoire. Les attributs de l'élément <perform-when> sont les suivants :
L'attribut condition de l'élément <conditional-subitem> fournit une chaîne (cette chaîne provient d'une variable de l'aide-mémoire). Chacun des enfants <subitem> doit être associé à un attribut when doté d'une chaîne distincte. Lorsque l'élément est développé, l'élément <conditional-subitem> est remplacé par l'élément <subitem> avec la chaîne correspondante. S'il n'y a pas d'élément <subitem> avec une chaîne concordante, le programme considère qu'il y a une erreur.
Par exemple, si la variable de l'aide-mémoire "v1" correspond à la chaîne "b" lorsque l'élément suivant est développé
<item ...> <subitem label="Etape principale"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> </conditional-subitem> </subitem> </item>la seconde action est sélectionnée et l'élément est développé sous la forme suivante :
<item ...> <subitem label="Etape principale"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
L'exemple suivant représente le fichier de contenu d'un aide-mémoire très simple :
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Exemple"> <intro> <description>Exemple d'aide-mémoire comportant deux étapes.</description> </intro> <item title="Step 1"> <description>Etape avec une action.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Etape 2"> <description>Etape manuelle complète.</description> </item> </cheatsheet>
Copyright (c) 2004 IBM Corporation and others.
All rights reserved. Ce programme et les produits associés sont
distribués sous licence publique Eclipse v1.0 et disponibles à
l'adresse suivante :
http://www.eclipse.org/legal/epl-v10.html