Le framework Qt Help

Présentation

Le système Qt Help comprend des outils permettant de générer et d'afficher des fichiers Qt Help. De plus, il fournit des classes permettant d'accéder au contenu de l'aide par programmation afin de pouvoir intégrer une aide en ligne dans les applications Qt.

Les données d'aide proprement dites, c'est-à-dire la table des matières, les mots-clés de l'index ou les documents HTML, sont contenues dans des fichiers d'aide compressés Qt Help. Ainsi, un tel fichier d'aide représente généralement un manuel ou un ensemble de documentation. Comme la plupart des produits sont plus complets et se composent d'un certain nombre d'outils, un seul manuel suffit rarement. Il existe donc plusieurs manuels, qui doivent être accessibles simultanément. Idéalement, il devrait également être possible de renvoyer de un manuel à un autre vers des points d’intérêt spécifiques. C’est pourquoi le système Qt Help fonctionne avec des fichiers de collection d’aide, qui peuvent contenir un nombre illimité de fichiers d’aide compressés.

Cependant, le fait de disposer de fichiers de collection pour regrouper de nombreux ensembles de documentation peut poser certains problèmes. Par exemple, un mot-clé d’index peut être défini dans différents ensembles de documentation. Ainsi, lorsque vous voyez uniquement un mot-clé dans l’index et que vous cliquez dessus, vous ne pouvez pas être sûr que la documentation attendue s’affichera. C’est pourquoi le système Qt Help offre la possibilité de filtrer le contenu de l’aide en fonction de certains attributs. Cela nécessite toutefois que ces attributs aient été attribués au contenu de l’aide avant la génération du fichier d’aide compressé.

Comme déjà mentionné, le fichier d’aide compressé Qt contient toutes les données ; il n’est donc plus nécessaire de fournir tous les fichiers HTML individuels. À la place, seuls le fichier d’aide compressé et, éventuellement, le fichier de collection doivent être distribués. Le fichier de collection est facultatif, car tout fichier de collection existant, provenant par exemple d’une version antérieure, peut être utilisé.

Ainsi, en général, quatre fichiers interagissent avec le système d'aide : deux servent à générer Qt Help et deux sont destinés à la distribution :

Génération Qt Help

La création de fichiers d’aide pour le système Qt Help suppose que les fichiers de documentation HTML existent déjà.

Une fois les documents HTML en place, il faut créer un fichier de projet «Qt Help », avec l’extension .qhp. Après avoir spécifié toutes les informations pertinentes dans ce fichier, il faut le compiler en exécutant la commande suivante :

qhelpgenerator doc.qhp -o doc.qch

Le fichier doc.qch contient tous les fichiers HTML sous forme compressée, ainsi que la table des matières et les mots-clés de l'index. Pour vérifier que le fichier généré est correct, ouvrez Qt Assistant et installez le fichier dans Settings > Documentation.

Pour la compilation standard des sources Qt, le fichier .qhp est généré et placé dans le même répertoire que les pages HTML.

Création d’une collection « Qt Help »

La première étape consiste à créer un fichier de projet de collection d'Qt Help. Étant donné qu'une collection d' Qt Help stocke principalement des références à des fichiers d' compressés, le fichier de projet mycollection.qhcp est, sans surprise, très simple :

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <docFiles>
        <register>
            <file>doc.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

Pour créer le fichier de collection, utilisez la commande suivante :

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Pour générer à la fois l’aide compressée et le fichier de collection en une seule opération, modifiez le fichier de projet de la collection d’aide de manière à ce qu’il indique au générateur d’aide de créer d’abord l’aide compressée :

...
<docFiles>
    <generate>
        <file>
            <input>doc.qhp</input>
            <output>doc.qch</output>
        </file>
    </generate>
    <register>
        <file>doc.qch</file>
    </register>
</docFiles>
...

Bien entendu, il est possible de spécifier plusieurs fichiers dans la section « generate » ou « register » ; ainsi, un nombre illimité de fichiers d’aide compressés peut être généré et enregistré en une seule fois.

Utilisation de l'API QHelpEngine

QHelpEngine permet d'intégrer directement le contenu de l'aide dans une application.

Au lieu d'afficher l'aide dans une application externe telle qu'un navigateur Web, il est également possible d'intégrer l'aide en ligne dans l'application. Le contenu peut alors être récupéré via la classe ` QHelpEngine ` et affiché sous pratiquement n'importe quelle forme. L'affichage de l'aide dans une fenêtre « QTextBrowser » est sans doute la méthode la plus courante, mais son intégration dans l'aide « What's This » est également tout à fait possible.

La récupération des données d’aide à partir du moteur de fichiers ne nécessite pas beaucoup de code. La première étape consiste à créer une instance du moteur d’aide. Ensuite, on demande au moteur les liens associés à l’identifiant, en l’occurrence MyDialog::ChangeButton. Si un lien est trouvé, ce qui signifie qu’au moins un document d’aide existe sur ce sujet, on récupère le contenu réel de l’aide en appelant QHelpEngineCore::fileData() et on affiche le document à l’utilisateur.

QHelpEngineCore helpEngine("mycollection.qhc");
...

// get all file references for the identifier
QList<QHelpLink> links =
    helpEngine.documentsForIdentifier(QLatin1String("MyDialog::ChangeButton"));

// If help is available for this keyword, get the help data
// of the first file reference.
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin()->url);
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

Pour plus d’informations sur l’utilisation de l’API, consultez la documentation de la classe QHelpEngine.