Utiliser Qt Help comme une main courante

| David Boddie | traducteur : Thibaut Cuvelier | Qt Quarterly |

Tout comme les librairies telles Qt ne sont pas complètes sans guide de référence ni de documentation des API, une application distribuée doit l'être avec un manuel et une documentation en ligne. Dans leur quête d'assistance dans tous les aspects du développement, les développeurs de Qt fournissent une solution facilement réutilisable.

Qt 4.4 a introduit tellement de nouvelles fonctionnalités pour une version mineure qu'une a échappé à la majorité des utilisateurs. Le module Qt Help remplace le Qt Assistant des versions précédentes. Il fournit des mécanismes d'intégration de Qt Assistant dans vos applications, mais ce n'est pas tout.

Dans cet article, nous allons essayer de couvrir quelques-unes de ces nouveautés du module Qt Help par un exemple. Nous devrons donc créer une documentation d'API en plus d'un manuel utilisateur.

Cet article est une traduction autorisée de Using QtHelp to Lend a Helping Hand, par David Boddie.

Commentez

- Titre : Utiliser Qt Help comme une main courante

- Auteurs : David Boddie, traducteur : Thibaut Cuvelier, Qt Quarterly

- Parution : 19 mars 2009

- Mise à jour : 1 août 2011

- Licence : Copyright ® 2008 David Boddie. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. L'article original

- II. Démarrage avec la documentation de l'API

- III. Fichiers HTML et projets d'aide

- IV. Profils et documentation rationalisée

- V. Intégration d'aide à l'application

- VI. Ajouter des guides utilisateur et l'aide en ligne

- VII. Divers

- VII-A. Voir aussi

- VII-B. Remerciements

I - L'article original

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.

II - Démarrage avec la documentation de l'API

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.

III - Fichiers HTML et projets d'aide

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.

Source

Binaire

Description

.qhp

.qch

Contient la table des matières, un index des items de la documentation, et un manifeste.

.qhcp

.qhc

Contient les informations utilisées pour personnaliser l'apparence et les fonctionnalités de Qt Assistant.

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

IV - Profils et documentation rationalisée

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.

V - Intégration d'aide à l'application

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.

VI - Ajouter des guides utilisateur et l'aide en ligne

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 - Divers

VII-A - Voir aussi

- Le site web de Doxygen

- L'ancien doxygen2qthelp, des Qt Labs

- La documentation de Qt Help

- Le code source de l'exemple

VII-B - Remerciements

Au nom de toute l'équipe Qt, j'aimerais adresser le plus grand remerciement à Nokia pour nous avoir autorisé la traduction de cet article !

Ici, j'aimerais adresser un énorme merci à ram-0000 pour sa relecture attentive !