Personnalisation Qt Assistant

L'utilisation d'Qt Assistant en tant que visionneuse d'aide personnalisée ne se limite pas à la simple affichage de la documentation personnalisée. Il est tout aussi important de pouvoir personnaliser l'apparence d'Qt Assistant 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 du menu propres à l'application. Pour obtenir la liste complète des personnalisations possibles, consultez la section Création d'un fichier de collection d'aide personnalisé.

Une autre exigence d’un visualiseur d’aide personnalisé est sa capacité à recevoir des actions ou des commandes de la part de l’application pour laquelle il fournit une aide. Ceci est particulièrement important lorsque l’application propose une aide contextuelle. Utilisée de cette manière, la visionneuse d’aide peut avoir besoin de modifier son contenu en fonction de l’état actuel de l’application. Cela signifie que l’application doit communiquer son état actuel à la visionneuse d’aide. Pour plus d’informations, consultez la section « Utilisation d’ 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 collection

La première chose importante à savoir concernant Qt Assistant est qu’il stocke tous les paramètres relatifs à son apparence ainsi qu’ une liste de la documentation installée dans un fichier de collection d’aide. Cela signifie que, lorsque vous lancez Qt Assistant avec différents fichiers de collection, Qt Assistant peut présenter un aspect totalement différent. Cette séparation complète des paramètres permet de déployer Qt Assistant en tant que visionneuse d’aide personnalisée pour plusieurs applications sur un même ordinateur, sans risque d’interférence entre les différentes instances d’ Qt Assistant.

Pour appliquer une collection d’aide spécifique à Qt Assistant, indiquez le fichier de collection correspondant sur la ligne de commande lors de son lancement. Par exemple :

assistant -collectionFile mycollection.qhc

Cependant, le stockage de tous les paramètres dans un seul fichier de collection pose certains problèmes. Le fichier de collection 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. Selon le répertoire et le système d’exploitation, l’utilisateur peut ne disposer d’aucune autorisation pour modifier ce fichier, ce qui serait le cas si les paramètres utilisateur y étaient stockés. De plus, il peut s’avérer impossible d’accorder des droits d’écriture à l’utilisateur, par exemple lorsque le fichier se trouve sur un support en lecture seule tel qu’un CD-ROM.

Même s’il était possible d’accorder à tout le monde le droit de stocker ses paramètres dans un fichier de collection accessible à tous, les paramètres d’un utilisateur seraient écrasés par ceux d’un autre utilisateur à la fermeture d’ Qt Assistant.

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

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

Ainsi, lors de l’appel de

assistant -collectionFile mycollection.qhc

Qt Assistant utilise en réalité le fichier de collection :

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

Il n’est jamais nécessaire de lancer Qt Assistant avec le fichier de collection spécifique à l’utilisateur. À la place, le fichier de collection fourni avec l’application doit toujours être utilisé. De même, lors de l’ajout ou de la suppression de documentation dans le fichier de collection (voir la section suivante), utilisez toujours le fichier de collection standard. Qt Assistant se chargera de synchroniser les fichiers de collection des utilisateurs lorsque la liste des documentations installées aura changé.

Affichage de la documentation personnalisée

Avant qu’ Qt Assistant ne puisse afficher la documentation, il doit savoir où trouver les fichiers de documentation proprement dits, ce qui signifie qu’il doit connaître l’emplacement du fichier d’aide compressé Qt (*.qch). Comme 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 collection, vous pouvez répertorier tous les fichiers d’aide compressés qu’ 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, selon l’application pour laquelle Qt Assistant sert 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 d’application ou de plugins. Cela peut être effectué manuellement dans Qt Assistant en sélectionnant Édition > Préférences > Documentation. Cependant, cette approche présente l’inconvénient que chaque utilisateur doit effectuer cette opération manuellement pour accéder à la nouvelle documentation.

La méthode recommandée pour ajouter de la documentation à un fichier de collection existant consiste à 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 ferme immédiatement en affichant un message indiquant si l’enregistrement a réussi ou échoué.

L'indexation de recherche ne portera que sur vos fichiers personnalisés *.html, *.htm et *.txt.

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

L'option -quiet peut être transmise à Qt Assistant pour l'empêcher d'afficher le message d'état.

Modification de l’apparence de Qt Assistant

L’apparence d’ 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 permettent uniquement d’afficher ou de masquer des widgets spécifiques, tels que la vue « Contenu » ou « 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 collection d’aide personnalisé.

Création d’un fichier de collection d’aide personnalisé

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

Outre ces balises spécifiques à Qt Assistant, les balises permettant de générer et d’enregistrer la documentation peuvent être utilisées. Pour plus d’informations, consultez la documentation relative aux fichiers de collectionQt Help .

Vous trouverez ci-dessous un exemple de fichier de collection d’aide utilisant toutes les balises disponibles :

<?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 collection binaire, exécutez l’outil « qhelpgenerator » :

qhelpgenerator mycollection.qhcp -o mycollection.qhc

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

assistant -collectionFile mycollection.qhc

Utilisation à distance d’ Qt Assistant

Même si la visionneuse d’aide est une application autonome, elle sera le plus souvent lancée par l’application pour laquelle elle fournit l’aide. Cette approche permet à l’application de demander l’affichage de contenus d’aide spécifiques 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 du visualiseur d’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 visionneuse d’aide personnalisée de votre application, il suffit de créer un QProcess et de spécifier le chemin d’accès à l’exécutable Qt Assistant. Afin que Qt Assistant puisse « écouter » 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 qu’ 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 page spécifique 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 en peu de temps, il est recommandé de n'écrire qu'une seule ligne dans l'entrée standard (stdin) du processus, plutôt qu'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);