Utiliser Qt Help comme une main courante

Qt Quarterly est une revue trimestrielle électronique proposée par Nokia à destination des développeurs et utilisateurs de Qt. Vous pouvez trouver les versions originales.

Nokia, Qt, Qt Quarterly et leurs logos sont des marques déposées de Nokia Corporation en Finlande et/ou dans les autres pays. Les autres marques déposées sont détenues par leurs propriétaires respectifs.

Cet article est la traduction de l'article Using QtHelp to Lend a Helping Hand de David Boddie paru dans la Qt Quarterly Issue 28.

Cet article est une traduction d'un des tutoriels écrits par Nokia Corporation and/or its subsidiary(-ies) inclus dans la documentation de Qt, en anglais. Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia.

L'exemple utilisé dans cet article est une simple application de traitement d'images qui expose une seule classe, ImageWrapper, à Qt Script, pour que les utilisateurs puissent écrire de petit scripts d'automatisation.

Bien que la classe ne soit pas fournie dans une bibliothèque, nous pouvons la documenter de la même manière que Qt. Par simplicité, nous allons juste commenter cette classe, en insérant la documentation dans des commentaires de style C.

/**
	Scales the image by the horizontal and vertical
	factors specified by \a xScale and \a yScale
	respectively.
	If \a publish is true, the imageChanged() signal will
	be emitted to notify other components that the image
	has been changed.
*/
void ImageWrapper::scale(qreal xScale, qreal yScale,
						 bool publish)
{
	image = image.scaled(int(xScale*image.width()),
	int(yScale*image.height()));
	if (publish)
		emit imageChanged(image);
}

Pour convertir ceci dans une forme lisible par tous, nous utilisons Doxygen, un outil développé avec Qt très proche de celui utilisé pour générer la documentation de Qt. Cependant, nous devons d'abord le configurer pour qu'il sache quelles classes documenter. Heureusement, Doxygen est livré avec un outil, doxywizard, qui nous guide dans ce processus.

Nous cliquons sur le bouton Wizard... pour commencer le processus de configuration : nom du projet, emplacement de la source, sortie pour les documents générés. Les onglets contiennent des paramètres, libre à vous de les modifier.

L'outil nous permet de sauvegarder la configuration, et de choisir un répertoire de travail pour Doxygen. Nous pouvons l'utiliser par la ligne de commande.

doxygen Doxyfile

Dans notre cas, Doxygen crée un répertoire html et y place la documentation. Les utilisateurs peuvent la lire à l'aide d'un simple navigateur. Pourtant, nous voulons qu'elle soit accessible de l'intérieur de notre application.

Dans les versions précédentes de Qt, Qt Assistant travaillait avec des collections de fichiers HTML et d'index, comme qt.dcf, qui décrivait le contenu de la référence de Qt. Depuis Qt 4.4, le format a changé, et se base désormais sur des bases de données SQLite.

La chaîne d'outils utilisée pour construire la documentation de Qt effectue moult conversions entre des formats aux extensions fort proches.

Pour créer la documentation qui devra être montrée dans Qt Assistant, nous devrions écrire un fichier de projet Qt Help (un XML avec une extension .qhp), et le compiler en un binaire compressé (un .qch), en utilisant qhelpgenerator. Cependant, Doxygen nous facilite la tâche : il peut automatiquement générer les fichiers .qhp, mais aussi les .qch, nous permettant de créer des fichiers qui peuvent directement être utilisés avec Qt Assistant.

Pour notre documentation, nous devons changer le fichier de configuration et relancer Doxygen. Nous localisons les lignes contenant GENERATE_QHP et QCH_FILE, et d'autres définitions en rapport, et nous les modifions pour ressembler à ceci.

GENERATE_QHP		= yes
QHP_NAMESPACE		= "com.trolltech.qq.imageprocessor"
QHP_VIRTUAL_FOLDER 	= "imageprocessor-0.1"
QCH_FILE			= "../../imageprocessor/help/imageprocessor.qch"
QHG_LOCATION		= "qhelpgenerator"

Maintenant, nous lançons Doxygen pour produire le .qch. Comme précédemment, des fichiers HTML sont crées, nouvellement accompagnés d'un QCH, placé dans le répertoire, relativement aux HTML, désigné par QCH_FILE.

Ce fichier .qch doit être enregistré avec Qt Assistant, avant qu'il puisse être visualisé. Vous pouvez, au choix, ouvrir le menu Edit > Preferences de Qt Assistant, et ajouter le fichier, ou bien utiliser cette commande.

assistant -register help/imageprocessor.qch

Depuis que les fichiers HTML, les index et les tables des matières sont incluses dans un seul et même fichier, vous pouvez le déplacer où bon vous semble.

Bien que nous ne les définissions pas dans notre exemple, Doxygen accepte aussi la création de filtres personnalisés pour la documentation, comme décrit dans la documentation du module. Les définitions utilisent ces variables.

QHP_CUST_FILTER_NAME
QHP_CUST_FILTER_ATTRS
QHP_SECT_FILTER_ATTRS

Une manière de fournir un accès à notre documentation est d'ouvrir Qt Assistant depuis l'intérieur de notre application, et le contrôler avec les fonctions de contrôle à distance. Ceci est couvert par l'exemple Simple Text Viewer, distribué avec Qt. Vous pouvez ainsi teste les possibilités de cette approche en enregistrant le fichier dans Assistant, en l'invoquant avec l'option -enableRemoteControl.

assistant -enableRemoteControl
hide contents;
hide index;
hide bookmarks;
hide search;
setSource
	qthelp://com.trolltech.qq.imageprocessor/imageprocessor-0.1/index.html;

Nous pouvons personnaliser l'interface utilisateur et la documentation disponible en utilisant un fichier de collection Qt Help .qhc. Ceci est la manière à préférer pour utiliser Qt Assistant comme visionneur d'aide, parce qu'elle permet de s'assurer que seulement l'aide correspondante est montrée.

Pour une intégration plus poussée, nous utilisons les classes du module QtHelp. Nous devons alors créer un fichier .qhc avant de procéder. Ainsi, nous écrivons un fichier de collection qui sera compilé pour nous donner une seule collection d'aide.

<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
	<assistant>
		<startPage>qthelp://com.trolltech.qq.imageprocessor/
		imageprocessor-0.1/classImageWrapper.html</startPage>
	</assistant>
	<docFiles>
		<register>
			<file>../imageprocessor/help/imageprocessor.qch</file>
		</register>
	</docFiles>
</QHelpCollectionProject>

Plusieurs paramètres supplémentaires peuvent être ajoutés, mais ils ne sont pas utiles dans ce type d'utilisation. Une collection compilée peut être créée avec qcollectiongenerator, fourni avec Qt.

qcollectiongenerator doc/imageprocessor.qhcp -o doc/imageprocessor.qhc

Vous pouvez tester la collection en lançant Qt Assistant de cette manière.

assistant -collectionFile doc/imageprocessor.qhc

Ceci devrait montrer si la collection est valide ou non.

Nous aimerions donner un accès aux utilisateurs directement depuis l'application. Pour ce faire, nous devons d'abord préparer le système d'aide. Nous devons aussi afficher le HTML dans un navigateur (pour notre simplicité, nous dérivons simplement de QTextBrowser, en l'étendant pour qu'il puisse avoir accès à la collection d'aide.

Regardons un peu le code, pour préparer le système d'aide et l'interface, que nous allons exécuter dans le constructeur de la fenêtre principale de notre application.

QHelpEngine *helpEngine = new QHelpEngine(DOCS_PATH, this);
helpEngine->setupData();

La macro DOCS_PATH est définie dans le système de compilation de notre application : elle contient le répertoire du fichier .qhc. Le système d'aide charge ce fichier, et nous nous assurons qu'il l'est bien avant de l'utiliser.

Le reste de ce code crée un widget qui contient la table des matières, fournie comme un QHelpContentWidget, par le système d'aide, et un navigateur personnalisé help-aware.

helpWindow = new QDockWidget(tr("Help"), this);
QSplitter *helpPanel = new QSplitter(Qt::Horizontal);
HelpBrowser *helpBrowser = new HelpBrowser(helpEngine);
helpPanel->insertWidget(0, helpEngine->contentWidget());
helpPanel->insertWidget(1, helpBrowser);
helpPanel->setStretchFactor(1, 1);
helpWindow->setWidget(helpPanel);
addDockWidget(Qt::BottomDockWidgetArea, helpWindow);
/*
...
*/
connect(helpEngine->contentWidget(),
		SIGNAL(linkActivated(const QUrl &)),
		helpBrowser, SLOT(setSource(const QUrl &)));

Nous connectons ces deux widgets par le signal linkActivated(), pour que l'utilisateur puisse voir les sujets par double-clic dans la table des matières.

Le navigateur est un simple dérivé de QTextBrowser, qui peut s'occuper des URL qthelp://, utilisées par l'aide. La partie spécifique est la fonction loadResource(), qui utilise une instance de QHelpEngine passée à la construction pour rapatrier les données pour le navigaeur.

Pour toutes les autres URL, il utilise l'implémentation par défaut fournie par QTextBrowser.

QVariant HelpBrowser::loadResource(	int type,
									const QUrl &url)
{
	if (url.scheme() == "qthelp")
		return QVariant(helpEngine->fileData(url));
	else
		return QTextBrowser::loadResource(type, url);
}

Dans le code d'exemple fourni avec cet article, nous avons mis un système simple de compilation qui génère la documentation avec Doxygen et crée la collection d'aide.

Les fichiers .qch et .qhc produits par ce processus sont installés dans la source pour l'application d'exemple, et leur emplacement est passé dans la macro DOCS_PATH au compilateur.

Bien que Doxygen soit principalement utilisé pour la documentation d'API, il peut aussi être utilisé pour la création des pages d'un manuel, qui peut être inclus dans la collection d'aide, avec la documentation du script. Alternativement, nous pouvons utiliser un autre outil pour générer la documentation HTML et créer une collection à part. QHelpEngine est prévu pour le support de plusieurs collections, nous aurions simplement pu afficher les deux côte à côte.

Le mécanisme d'aide fournit des procédures pour permettre l'inclusion de pages individuelles, mais aussi pour la recherche, par la librairie CLucene.

Des utilisations plus spécialisées de ce système pourraient utiliser les collections pour stocker du texte pour les tooltips et d'autres formes de documentation en ligne. Avec assez de temps pour expérimenter les différentes options, une pléthore de moyens peuvent être trouvés en ce but.

VII-A. Voir aussi▲

VII-B. Remerciements▲