Utiliser Qt Help comme une main couranteDate de publication : 19/03/2009. Date de mise à jour : 01/08/2011.
Par
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.
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 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.
\a\a
\a
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.
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
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 !
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'à 3 ans de prison et jusqu'à 300 000 E
de dommages et intérêts. Cette page est déposée à la SACD.
|
