Le cadre Qt Help

Vue d'ensemble

Le système d'aide Qt comprend des outils pour générer et afficher des fichiers d'aide Qt. En outre, il fournit des classes permettant d'accéder au contenu de l'aide de manière programmatique afin de pouvoir intégrer l'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 les fichiers d'aide compressés de Qt Help. Ainsi, un tel fichier d'aide représente généralement un manuel ou un ensemble de documents. Étant donné que la plupart des produits sont plus complets et consistent en un certain nombre d'outils, un seul manuel est rarement suffisant. Au lieu de cela, il existe plusieurs manuels, qui devraient être accessibles en même temps. Idéalement, il devrait également être possible de faire référence à certains points d'intérêt d'un manuel à l'autre. C'est pourquoi le système d'aide de Qt Help fonctionne sur des fichiers de collection d'aide, qui comprennent un nombre quelconque de fichiers d'aide compressés.

Cependant, le fait d'avoir des fichiers de collection pour fusionner de nombreux ensembles de documentation peut entraîner certains problèmes. Par exemple, un mot-clé d'index peut être défini dans différents ensembles de documentation. Ainsi, lorsque vous voyez un mot-clé dans l'index et que vous l'activez, vous ne pouvez pas être sûr que la documentation attendue sera affichée. C'est pourquoi le système d'aide Qt Help offre la possibilité de filtrer le contenu de l'aide en fonction de certains attributs. Cela nécessite toutefois que les attributs aient été assignés au contenu de l'aide avant la génération du fichier d'aide compressé.

Comme nous l'avons déjà mentionné, le fichier d'aide compressé de Qt Help contient toutes les données, il n'est donc plus nécessaire d'expédier tous les fichiers HTML individuels. Au lieu de cela, seuls le fichier d'aide compressé et, éventuellement, le fichier de collecte doivent être distribués. Le fichier de collecte est facultatif car tout fichier de collecte existant, par exemple d'une version antérieure, peut être utilisé.

Ainsi, en général, il y a quatre fichiers qui interagissent avec le système d'aide, deux utilisés pour générer l'aide de Qt Help et deux destinés à la distribution :

Génération Qt Help

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

Une fois les documents HTML en place, un fichier de projetQt Help , portant l'extension .qhp, doit être créé. Après avoir spécifié toutes les informations pertinentes dans ce fichier, il doit être compilé en appelant :

qhelpgenerator doc.qhp -o doc.qch

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

Pour la compilation standard des sources de 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 Qt Help. Étant donné qu'une collection d'aide Qt Help stocke principalement des références à des fichiers d'aide compressés, le fichier projet mycollection.qhcp semble 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, appelez :

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Pour générer l'aide compressée et le fichier de collecte en une seule fois, modifiez le fichier de projet de la collecte 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 plus d'un fichier dans la section generate ou register, de sorte que n'importe quel nombre de fichiers d'aide compressés peut être généré et enregistré en une seule fois.

Utilisation de l'API de QHelpEngine

QHelpEngine permet d'intégrer le contenu de l'aide directement 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 peut être affiché sous presque n'importe quelle forme. L'affichage de l'aide sur le site QTextBrowser est probablement la méthode la plus courante, mais il est également possible de l'intégrer à l'aide "What's This".

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, nous demandons au moteur les liens attribués à l'identifiant, dans ce cas MyDialog::ChangeButton. Si un lien a été trouvé, ce qui signifie qu'il existe au moins un document d'aide sur ce sujet, nous obtenons le contenu de l'aide en appelant QHelpEngineCore::fileData() et nous affichons 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 référence de la classe QHelpEngine.