Description et regroupement du contenu de l'aide contextuelle

L'aide contextuelle est décrite en associant l'ID de contexte déclaré dans le code d'interface graphique, au moyen d'une description et d'une liste de liens, aux rubriques correspondantes de l'aide en ligne.  Ces associations sont effectuées dans un fichier XML.  Vous pouvez créer un nombre quelconque de fichiers XML contenant des associations d'aide contextuelle pour chaque plug-in.  La description et les liens de chaque ID de contexte figurent dans des éléments <context> du fichier XML.  Chaque élément de contexte peut posséder un élément <description> facultatif utilisé pour décrire l'objet d'interface ainsi qu'un nombre quelconque d'éléments <topic> fournissant un lien avec la documentation en ligne.

Depuis l'édition 3.1, les éléments de contexte peuvent remplacer le titre par défaut utilisé pour présenter les informations d'aide contextuelle dans la vue Aide.

<contexts>
	<context id="panic_button" title="Panic Button Title">
		<description>This is the panic button.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/>
		<topic href="reference/panic_button.htm" label="Panic Button Reference"/>
	</context>
	...
</contexts>

Une fois les contextes décrits dans le ou les fichiers XML, vous pouvez faire référence aux fichiers de contexte dans le manifeste de votre plug-in. Dans l'exemple, l'ID de contexte n'est pas qualifié complet. Ceci est autorisé tant que le fichier de contexte est fourni dans le manifeste du plug-in ayant défini l'ID de contexte. En d'autres termes, l'ID de contexte est adapté à l'ID du plug-in ayant fourni le fichier XML.  

Un plug-in fournit des fichiers de contexte à l'aide du point d'extension org.eclipse.help.contexts.  

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml"  />
   </extension>

Vous pouvez faire référence à des fichiers de contexte à partir d'autres plug-in en incluant l'attribut plugin.  Vous pouvez ainsi regrouper toute votre documentation, y compris l'aide contextuelle, dans un seul plug-in et y faire référence à partir du plug-in de code de l'interface graphique ou tout autre plug-in relatif.

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml" plugin="com.example.helpExample"  />
   </extension>

Comme vous pouvez le constater, vous disposez d'une grande flexibilité d'organisation de vos contextes au sein d'un ou de plusieurs fichiers contenus dans un ou divers plug-in.  Seule contrainte, les ID de contexte contenus dans les fichiers doivent s'adapter correctement.  Si un ID de contexte n'est pas qualifié complet, vous devez fournir les fichiers XML de contexte dans le plug-in ayant déclaré les ID de contexte.  Si vous utilisez des ID de contexte qualifiés complets dans votre fichier XML de contexte, vous pouvez choisir l'emplacement de votre choix pour vos fichiers XML et les plug-in fournissant des contextes.

Aide contextuelle provenant de divers plug-in

Pour toujours plus de souplesse d'action, vous pouvez fournir une aide contextuelle pour le même ID de contexte provenant de divers plug-in.  Cette opération est par exemple utile s'il existe plusieurs ensembles de plug-in de documentation installés ou non dans la configuration utilisateur.  Chaque plug-in de documentation peut ainsi déclarer ses contextes de façon indépendante.  L'utilisateur final verra l'aide contextuelle fusionnée pour tous les plug-in ayant fourni des contextes à l'ID du widget.

L'ID de contexte qualifié complet du widget doit être utilisé car aucun plug-in de documentation n'a déclaré l'ID de contexte.  Lorsque plusieurs plug-in fournissent une aide contextuelle pour le même ID de contexte, le contenu défini dans le plug-in ayant déclaré le contexte (plug-in de l'interface graphique) s'affiche en premier.  D'autres descriptions et liens sont ajoutés dans un ordre aléatoire.