Personnalisation Qt Assistant

L'utilisation de Qt Assistant en tant que visualisateur d'aide personnalisé ne se limite pas à la possibilité d'afficher une documentation personnalisée. Il est tout aussi important que l'apparence de Qt Assistant puisse être personnalisée afin qu'elle soit perçue comme une visionneuse d'aide spécifique à l'application plutôt que comme Qt Assistant. Pour ce faire, il suffit de modifier le titre ou l'icône de la fenêtre, ainsi que certains textes et actions de menu spécifiques à l'application. Pour une liste complète des personnalisations possibles, voir Création d'un fichier de recueil d'aide personnalisé.

Une autre exigence d'une visionneuse d'aide personnalisée est la capacité de recevoir des actions ou des commandes de l'application pour laquelle elle fournit de l'aide. Ceci est particulièrement important lorsque l'application offre une aide contextuelle. Dans ce cas, la visionneuse d'aide peut être amenée à modifier son contenu en fonction de l'état dans lequel se trouve l'application. Cela signifie que l'application doit communiquer l'état actuel à la visionneuse d'aide. Pour plus d'informations, voir Utilisation de Qt Assistant à distance.

L'exemple Simple Text Viewer utilise les techniques décrites dans ce document pour montrer comment utiliser Qt Assistant comme visionneuse d'aide personnalisée pour une application.

Qt Help Fichiers de collecte

Le premier point important à connaître à propos de Qt Assistant est qu'il stocke tous les paramètres liés à son apparence et une liste de la documentation installée dans un fichier de collection d'aide. Cela signifie que lorsque l'on démarre Qt Assistant avec différents fichiers de collecte, Qt Assistant peut avoir une apparence totalement différente. Cette séparation complète des paramètres permet de déployer Qt Assistant en tant que visualiseur d'aide personnalisé pour plus d'une application sur une machine sans risque d'interférence entre les différentes instances de Qt Assistant.

Pour appliquer une certaine collection d'aide à Qt Assistant, spécifiez le fichier de collection correspondant sur la ligne de commande lorsque vous le démarrez. Par exemple :

assistant -collectionFile mycollection.qhc

Cependant, le stockage de tous les paramètres dans un seul fichier de collecte pose certains problèmes. Le fichier de collecte est généralement installé dans le même répertoire que l'application elle-même, ou dans l'un de ses sous-répertoires. En fonction du répertoire et du système d'exploitation, l'utilisateur peut ne pas avoir les autorisations nécessaires pour modifier ce fichier, ce qui se produirait lorsque les paramètres de l'utilisateur sont stockés. Il se peut également qu'il ne soit pas possible d'accorder à l'utilisateur des droits d'écriture, par exemple lorsque le fichier se trouve sur un support en lecture seule tel qu'un CD-ROM.

Même s'il est possible de donner à chacun le droit de stocker ses paramètres dans un fichier de collecte disponible dans le monde entier, les paramètres d'un utilisateur seraient écrasés par un autre utilisateur lorsqu'il quitterait Qt Assistant.

Pour résoudre ce dilemme, Qt Assistant crée des fichiers de collecte spécifiques à l'utilisateur qui sont plus ou moins copiés à partir du fichier de collecte original. Le fichier de collecte spécifique à l'utilisateur sera enregistré dans un sous-répertoire du chemin renvoyé par QDesktopServices::AppDataLocation. Le sous-répertoire, ou le répertoire de cache dans cet emplacement spécifique à l'utilisateur, peut être défini dans le fichier de projet de la collection d'aide. Par exemple, en appelant QDesktopServices::AppDataLocation

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        ...
    </assistant>
</QHelpCollectionProject>

Ainsi, lorsque l'on appelle

assistant -collectionFile mycollection.qhc

Qt Assistant utilise en fait le fichier de collecte :

%QDesktopServices::AppDataLocation%/mycompany/myapplication/mycollection.qhc

Il n'est pas nécessaire de démarrer Qt Assistant avec le fichier de collecte spécifique à l'utilisateur. Au lieu de cela, le fichier de collecte fourni avec l'application doit toujours être utilisé. De même, lorsque vous ajoutez ou supprimez de la documentation du fichier de collecte (voir la section suivante), utilisez toujours le fichier de collecte normal. Qt Assistant se chargera de synchroniser les fichiers de collecte de l'utilisateur lorsque la liste de la documentation installée aura changé.

Affichage de la documentation personnalisée

Avant que Qt Assistant ne puisse afficher la documentation, il doit savoir où il peut trouver les fichiers de documentation proprement dits, ce qui signifie qu'il doit connaître l'emplacement du fichier d'aide compressé de Qt Help (*.qch). Comme nous l'avons déjà mentionné, Qt Assistant stocke les références aux fichiers d'aide compressés dans le fichier de collection actuellement utilisé. Ainsi, lors de la création d'un nouveau fichier de collecte, vous pouvez dresser la liste de tous les fichiers d'aide compressés que Qt Assistant doit afficher.

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

Parfois, en fonction de l'application pour laquelle Qt Assistant fait office de visionneuse d'aide, il est nécessaire d'ajouter de la documentation au fil du temps, par exemple lors de l'installation de nouveaux composants ou modules d'extension de l'application. Cela peut être fait manuellement dans Qt Assistant en sélectionnant Édition > Préférences > Documentation. Toutefois, cette approche présente l'inconvénient que chaque utilisateur doit le faire manuellement pour avoir accès à la nouvelle documentation.

La méthode préférée pour ajouter de la documentation à un fichier de collection existant est d'utiliser l'option de ligne de commande -register de Qt Assistant. Lorsque vous lancez Qt Assistant avec cette option, la documentation est ajoutée et Qt Assistant se termine immédiatement en affichant un message indiquant si l'enregistrement a été effectué avec succès ou non.

L'indexation de recherche n'indexera que vos fichiers *.html, *.htm et *.txt personnalisés.

assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

Le drapeau -quiet peut être transmis à Qt Assistant pour l'empêcher d'écrire le message d'état.

Modification de l'apparence de Qt Assistant

L'apparence de Qt Assistant peut être modifiée en passant différentes options de ligne de commande au démarrage. Cependant, ces options de ligne de commande ne permettent que d'afficher ou de masquer des widgets spécifiques, comme la vue du contenu ou de l'index. D'autres personnalisations, telles que la modification du titre ou de l'icône de l'application, ou la désactivation de la fonctionnalité de filtrage, peuvent être effectuées en créant un fichier de recueil d'aide personnalisé.

Création d'un fichier de collecte d'aide personnalisé

Le fichier de collecte d'aide (*.qhc) utilisé par Qt Assistant est créé lors de l'exécution de l'outil qhelpgenerator sur un fichier de projet de collecte d'aide (*.qhcp). Le format du fichier de projet est XML et prend en charge les balises suivantes :

En plus de ces balises spécifiques à Qt Assistant, les balises de génération et d'enregistrement de la documentation peuvent être utilisées. Pour plus d'informations, voir la documentation sur les fichiers de collecte à l'adresseQt Help .

Un exemple de fichier de collecte d'aide utilisant toutes les balises disponibles est présenté ci-dessous :

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
        <currentFilter>myfilter</currentFilter>
        <applicationIcon>application.png</applicationIcon>
        <enableFilterFunctionality>false</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar visible="true">true</enableAddressBar>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        <aboutMenuText>
            <text>About My Application</text>
            <text language="de">Über meine Applikation...</text>
        </aboutMenuText>
        <aboutDialog>
            <file>about.txt</file>
            <file language="de">ueber.txt</file>
            <icon>about.png</icon>
        </aboutDialog>
    </assistant>
    <docFiles>
        <generate>
            <file>
                <input>myapplication-manual.qhp</input>
                <output>myapplication-manual.qch</output>
            </file>
        </generate>
        <register>
            <file>myapplication-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

Pour créer le fichier de collecte binaire, exécutez l'outil qhelpgenerator:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Pour tester le fichier de collecte généré, lancez Qt Assistant de la manière suivante :

assistant -collectionFile mycollection.qhc

Utilisation de Qt Assistant à distance

Même si la visionneuse d'aide est une application autonome, elle sera le plus souvent lancée par l'application à laquelle elle fournit de l'aide. Cette approche permet à l'application de demander l'affichage d'un contenu d'aide spécifique dès le démarrage de la visionneuse d'aide. Un autre avantage de cette approche est que l'application peut communiquer avec le processus de visualisation de l'aide et peut donc demander l'affichage d'autres contenus d'aide en fonction de l'état actuel de l'application.

Ainsi, pour utiliser Qt Assistant comme visualiseur d'aide personnalisé de votre application, il suffit de créer un QProcess et de spécifier le chemin d'accès à l'exécutable Qt Assistant. Pour que Qt Assistant écoute votre application, activez sa fonctionnalité de contrôle à distance en passant l'option de ligne de commande -enableRemoteControl.

L'exemple suivant montre comment procéder :

QProcess *process = new QProcess;
QStringList args;
args << QLatin1String("-collectionFile")
    << QLatin1String("mycollection.qhc")
    << QLatin1String("-enableRemoteControl");
process->start(QLatin1String("assistant"), args);
if (!process->waitForStarted())
    return;

Une fois que Qt Assistant est en cours d'exécution, vous pouvez envoyer des commandes en utilisant le canal stdin du processus. L'extrait de code ci-dessous montre comment demander à Qt Assistant d'afficher une certaine page de la documentation.

QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

Les commandes suivantes peuvent être utilisées pour contrôler Qt Assistant:

Si vous souhaitez envoyer plusieurs commandes dans un court laps de temps, il est recommandé d'écrire une seule ligne sur le stdin du processus au lieu d'une ligne pour chaque commande. Les commandes doivent être séparées par un point-virgule, comme le montre l'exemple suivant :

QByteArray ba;
ba.append("hide bookmarks;");
ba.append("hide index;");
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);