Exemple de visionneuse de texte simple

Cet exemple montre comment utiliser Qt Assistant comme visionneuse d’aide personnalisée dans une application sur mesure. Cette opération s’effectue en deux étapes. Tout d’abord, la documentation est créée et Qt Assistant est personnalisée ; ensuite, la fonctionnalité permettant de lancer et de contrôler Qt Assistant est ajoutée à l’application.

L’application « Simple Text Viewer » permet à l’utilisateur de sélectionner et d’afficher des fichiers existants. L’application fournit sa propre documentation personnalisée, accessible depuis le menu « Aide » de la barre de menus de la fenêtre principale ou en cliquant sur le bouton « Aide » dans la boîte de dialogue de recherche de fichiers de l’application.

L'exemple se compose de quatre classes :

• Assistant fournit la fonctionnalité permettant de lancer Qt Assistant.
• MainWindow Il s'agit de la fenêtre principale de l'application.
• FindFileDialog permet à l'utilisateur de rechercher des fichiers à l'aide de caractères génériques.
• TextEdit fournit un navigateur de texte enrichi qui garantit l'affichage correct des images référencées dans les documents HTML.

Création de la documentation et personnalisation Qt Assistant

La manière de créer la documentation proprement dite sous forme de pages HTML n’entre pas dans le cadre de cet exemple. En général, les pages HTML peuvent être soit rédigées manuellement, soit générées à l’aide d’outils de documentation tels que qdoc ou Doxygen. Dans le cadre de cet exemple, nous partons du principe que les fichiers HTML ont déjà été créés. Il ne reste donc plus qu’à indiquer à Qt Assistant comment structurer et afficher les informations d’aide.

Organisation de la documentation pour les Qt Assistant

Les fichiers HTML simples ne contiennent que du texte ou de la documentation sur des sujets spécifiques, mais ils ne fournissent généralement aucune information sur les liens entre les différents documents HTML ni sur l’ordre dans lequel ils sont censés être lus. Il manque une table des matières ainsi qu’un index permettant d’accéder rapidement à certains contenus d’aide, sans avoir à parcourir de nombreux documents pour trouver une information.

Pour organiser la documentation et la rendre accessible à Qt Assistant, nous devons créer un fichier de projet Qt Help (.qhp). La première partie, et la plus importante, du fichier de projet est la définition de l’espace de noms. L'espace de noms doit être unique et constituera la première partie de l'URL de la page sur Qt Assistant. De plus, nous devons définir un dossier virtuel qui servira de dossier commun pour les ensembles de documentation. Cela signifie que deux ensembles de documentation identifiés par deux espaces de noms différents peuvent faire référence à des fichiers HTML les uns des autres, puisque ces fichiers se trouvent dans un seul et même grand dossier virtuel. Toutefois, pour cet exemple, nous ne disposerons que d’un seul ensemble de documentation ; le nom et la fonctionnalité du dossier virtuel n’ont donc pas d’importance.

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
  <namespace>org.qt-project.examples.simpletextviewer</namespace>
  <virtualFolder>doc</virtualFolder>

L’étape suivante consiste à définir la section de filtrage. Une section de filtrage contient la table des matières, les index et une liste complète de tous les fichiers de documentation ; elle peut se voir attribuer un nombre illimité d’attributs de filtrage. Un attribut de filtre est une chaîne de caractères ordinaire que l’on peut choisir librement. Plus tard, dans Qt Assistant, les utilisateurs pourront alors définir un filtre personnalisé faisant référence à ces attributs. Si les attributs d’une section de filtrage correspondent à ceux du filtre personnalisé, la documentation s’affichera ; dans le cas contraire, Qt Assistant masquera la documentation.

Là encore, comme nous n’aurons qu’un seul ensemble de documentation, nous n’avons pas besoin de la fonctionnalité de filtrage d’ Qt Assistant et pouvons donc ignorer les attributs de filtrage.

Nous allons maintenant créer la table des matières. Un élément de la table des matières est défini par la balise section, qui contient les attributs du titre de l’élément ainsi que le lien vers la page correspondante. Les balises de section peuvent être imbriquées à l’infini, mais pour des raisons pratiques, il n’est pas recommandé de les imbriquer à plus de trois ou quatre niveaux. Pour notre exemple, nous souhaitons utiliser la structure suivante pour la table des matières :

• Visionneuse de texte simple
  • Rechercher un fichier
    • Boîte de dialogue de fichier
    • Correspondance avec des caractères génériques
    • Parcourir
  • Ouvrir un fichier

Dans le fichier de projet d'aide, la table des matières est représentée par :

<filterSection>
  <toc>
    <section title="Simple Text Viewer" ref="index.html">
      <section title="Find File" ref="findfile.html">
        <section title="File Dialog" ref="filedialog.html"/>
        <section title="Wildcard Matching" ref="wildcardmatching.html"/>
        <section title="Browse" ref="browse.html"/>
      </section>
      <section title="Open File" ref="openfile.html"/>
    </section>
  </toc>

Une fois la table des matières définie, nous allons répertorier tous les mots-clés de l'index :

<keywords>
  <keyword name="Display" ref="index.html"/>
  <keyword name="Rich text" ref="index.html"/>
  <keyword name="Plain text" ref="index.html"/>
  <keyword name="Find" ref="findfile.html"/>
  <keyword name="File menu" ref="findfile.html"/>
  <keyword name="File name" ref="filedialog.html"/>
  <keyword name="File dialog" ref="filedialog.html"/>
  <keyword name="File globbing" ref="wildcardmatching.html"/>
  <keyword name="Wildcard matching" ref="wildcardmatching.html"/>
  <keyword name="Wildcard syntax" ref="wildcardmatching.html"/>
  <keyword name="Browse" ref="browse.html"/>
  <keyword name="Directory" ref="browse.html"/>
  <keyword name="Open" ref="openfile.html"/>
  <keyword name="Select" ref="openfile.html"/>
</keywords>

Pour finir, nous devons répertorier tous les fichiers composant la documentation. Il est important de noter ici que tous les fichiers doivent être répertoriés, y compris les fichiers image, et même les feuilles de style si elles sont utilisées.

    <files>
      <file>browse.html</file>
      <file>filedialog.html</file>
      <file>findfile.html</file>
      <file>index.html</file>
      <file>intro.html</file>
      <file>openfile.html</file>
      <file>wildcardmatching.html</file>
      <file>images/browse.png</file>
      <file>images/fadedfilemenu.png</file>
      <file>images/filedialog.png</file>
      <file>images/handbook.png</file>
      <file>images/mainwindow.png</file>
      <file>images/open.png</file>
      <file>images/wildcard.png</file>
    </files>
  </filterSection>
</QtHelpProject>

Le fichier de projet d'aide est désormais terminé. Si vous souhaitez consulter la documentation obtenue dans Qt Assistant, vous devez générer un fichier d'aide compressé Qt à partir de celui-ci et l'enregistrer dans la collection d'aide par défaut de Qt Assistant.

qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
assistant -register simpletextviewer.qch

Si vous lancez Qt Assistant maintenant, vous verrez la documentation de Simple Text Viewer à côté de celle de Qt. Cela convient pour les tests, mais pour la version finale, nous souhaitons que seule la documentation de Simple Text Viewer figure sur Qt Assistant.

Personnalisation Qt Assistant

La manière la plus simple de faire en sorte qu’ Qt Assistant n’affiche que la documentation de Simple Text Viewer consiste à créer notre propre fichier de collection d’aide. Un fichier de collection est stocké dans un format binaire, similaire au fichier d’aide compressé, et généré à partir d’un fichier de projet de collection d’aide (*.qhcp). À l’aide d’un fichier de collection, nous pouvons personnaliser l’apparence et même certaines fonctionnalités proposées par Qt Assistant.

Dans un premier temps, nous modifions le titre et l’icône de la fenêtre. Au lieu d’afficher «Qt Assistant », celle-ci affichera « Simple Text Viewer », ce qui permettra à l’utilisateur de comprendre plus clairement que la visionneuse d’aide appartient bien à notre application.

<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
    <title>Simple Text Viewer</title>
    <applicationIcon>images/handbook.png</applicationIcon>
    <cacheDirectory>QtProject/SimpleTextViewer</cacheDirectory>

La balise ` cacheDirectory ` spécifie un sous-répertoire du répertoire de données de l’utilisateur (voir la section « Fichiers de collection d’Qt Help ») dans lequel seront stockés le fichier de cache pour la recherche en texte intégral ou le fichier de paramètres.

Ensuite, nous définissons la page affichée par Qt Assistant lors de son tout premier lancement avec sa nouvelle configuration. L’URL se compose de l’espace de noms et du dossier virtuel définis dans le fichier de projet Qt Help, suivis du nom du fichier de la page proprement dit.

<startPage>qthelp://org.qt-project.examples.simpletextviewer/doc/index.html</startPage>

Ensuite, nous modifions le nom de l’élément de menu « À propos » en « À propos de Simple Text Viewer ». Le contenu de la boîte de dialogue « À propos » est également modifié en spécifiant un fichier d’où proviennent le texte ou l’icône de la section « À propos ».

<aboutMenuText>
    <text>About Simple Text Viewer</text>
</aboutMenuText>
<aboutDialog>
    <file>about.txt</file>
    <icon>images/icon.png</icon>
</aboutDialog>

Qt Assistant Qt Assistant offre la possibilité d’ajouter ou de supprimer de la documentation via sa boîte de dialogue de préférences. Cette fonctionnalité est utile lorsque l’on utilise comme visionneuse d’aide centrale pour plusieurs applications, mais dans notre cas, nous souhaitons en réalité empêcher l’utilisateur de supprimer la documentation. Nous masquons donc l’onglet « Documentation » dans la boîte de dialogue « Préférences ».

Comme la barre d’adresse n’est pas vraiment pertinente dans un ensemble de documentation aussi restreint, nous la désactivons également. En ne conservant qu’une seule section de filtrage, sans aucun attribut de filtrage, nous pouvons également désactiver la fonctionnalité de filtrage d’ Qt Assistant, ce qui signifie que la page de filtrage et la barre d’outils de filtrage ne seront pas disponibles.

    <enableDocumentationManager>false</enableDocumentationManager>
    <enableAddressBar>false</enableAddressBar>
    <enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>

À des fins de test, nous avons déjà généré le fichier d’aide compressé et l’avons enregistré dans la collection d’aide par défaut de Qt Assistant. Les lignes suivantes nous permettent d’obtenir le même résultat. La seule différence, et elle est importante, réside dans le fait que nous enregistrons le fichier d’aide compressé non pas dans la collection par défaut, mais dans notre propre fichier de collection.

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

Pour terminer, nous devons générer le fichier de collection binaire à partir du fichier de projet de la collection d’aide. Pour ce faire, il suffit d’exécuter l’outil qhelpgenerator.

qhelpgenerator simpletextviewer.qhcp -o simpletextviewer.qhc

Pour tester toutes les personnalisations que nous avons apportées à Qt Assistant, nous ajoutons le nom du fichier de collection à la ligne de commande :

assistant -collectionFile simpletextviewer.qhc

Contrôle d’ Qt Assistant via la classe Assistant

Nous allons d’abord voir comment démarrer et utiliser Qt Assistant depuis une application distante. Pour cela, nous créons une classe appelée Assistant.

Cette classe fournit une fonction publique permettant d’afficher les pages de la documentation, ainsi qu’une fonction d’aide privée permettant de s’assurer qu’ Qt Assistant est bien en cours d’exécution.

Le lancement de Qt Assistant s’effectue dans la fonction startAssistant() en créant et en démarrant simplement un QProcess. Si le processus est déjà en cours d’exécution, la fonction renvoie immédiatement une valeur. Dans le cas contraire, le processus doit être configuré et démarré.

bool Assistant::startAssistant()
{
    if (!m_process) {
        m_process = std::make_unique<QProcess>();
        QObject::connect(m_process.get(), &QProcess::finished,
                         m_process.get(), [this](int exitCode, QProcess::ExitStatus status) {
            finished(exitCode, status);
        });
    }

    if (m_process->state() != QProcess::Running) {
        QString app = QLibraryInfo::path(QLibraryInfo::BinariesPath);
#ifndef Q_OS_DARWIN
        app += "/assistant"_L1;
#else
        app += "/Assistant.app/Contents/MacOS/Assistant"_L1;
#endif

        const QString collectionDirectory = documentationDirectory();
        if (collectionDirectory.isEmpty()) {
            showError(tr("The documentation directory cannot be found"));
            return false;
        }

        const QStringList args{"-collectionFile"_L1,
                               collectionDirectory + "/simpletextviewer.qhc"_L1,
                               "-enableRemoteControl"_L1};

        m_process->start(app, args);

        if (!m_process->waitForStarted(3000)) {
            showError(tr("Unable to launch Qt Assistant (%1): %2")
                      .arg(QDir::toNativeSeparators(app), m_process->errorString()));
            return false;
        }
    }
    return true;
}

Pour démarrer le processus, nous avons besoin du nom de l’exécutable de Qt Assistant ainsi que des arguments de ligne de commande permettant d’exécuter Qt Assistant en mode personnalisé. Le nom de l’exécutable est un peu délicat à déterminer car il dépend de la plateforme, mais heureusement, il ne diffère que sous macOS.

La documentation affichée peut être modifiée à l’aide de l’argument de ligne de commande -collectionFile lors du lancement de Qt Assistant. Lorsqu’il est lancé sans aucune option, Qt Assistant affiche un ensemble de documentation par défaut. Lorsque Qt est installé, l’ensemble de documentation par défaut disponible à l’adresse Qt Assistant contient la documentation de référence de Qt ainsi que les outils fournis avec Qt, tels que Qt Designer et qmake.

Dans notre exemple, nous remplaçons l'ensemble de documentation par défaut par notre documentation personnalisée en transmettant notre fichier de collection spécifique à l'application via les options de ligne de commande du processus.

En dernier argument, nous ajoutons -enableRemoteControl, ce qui permet à Qt Assistant d’écouter son canal stdin pour recevoir des commandes, telles que celles permettant d’afficher une page spécifique de la documentation. Nous lançons ensuite le processus et attendons qu’il soit effectivement en cours d’exécution. Si, pour une raison quelconque, Qt Assistant ne peut pas être lancé, startAssistant() renverra la valeur false.

L’implémentation de ` showDocumentation() ` est désormais simple. Tout d’abord, nous nous assurons que ` Qt Assistant ` est en cours d’exécution, puis nous envoyons la requête pour afficher ` page ` via le canal ` stdin ` du processus. Il est très important ici que la commande se termine par un caractère de fin de ligne afin de vider le canal.

void Assistant::showDocumentation(const QString &page)
{
    if (!startAssistant())
        return;

    QByteArray ba("SetSource ");
    ba.append("qthelp://org.qt-project.examples.simpletextviewer/doc/");

    m_process->write(ba + page.toLocal8Bit() + '\n');
}

Enfin, nous nous assurons que Qt Assistant se termine correctement en cas d’arrêt de l’application. Le destructeur de QProcess met fin au processus, ce qui signifie que l’application n’a pas la possibilité d’effectuer des opérations telles que la sauvegarde des paramètres utilisateur, ce qui entraînerait la corruption des fichiers de paramètres. Pour éviter cela, nous demandons à Qt Assistant de se terminer dans le destructeur de la classe Assistant.

Assistant::~Assistant()
{
    if (m_process && m_process->state() == QProcess::Running) {
        QObject::disconnect(m_process.get(), &QProcess::finished, nullptr, nullptr);
        m_process->terminate();
        m_process->waitForFinished(3000);
    }
}

Classe MainWindow

La classe ` MainWindow ` fournit à la fenêtre principale de l’application deux menus : le menu « Fichier » permet à l’utilisateur d’ouvrir et de consulter un fichier existant, tandis que le menu « Aide » fournit des informations sur l’application et sur Qt, et permet à l’utilisateur d’ouvrir ` Qt Assistant ` pour afficher la documentation de l’application.

Pour pouvoir accéder à la fonctionnalité d'aide, nous initialisons l'objet ` Assistant ` dans le constructeur de ` MainWindow`.

MainWindow::MainWindow()
    : textViewer(new TextEdit)
    , assistant(new Assistant)
{
    ...
}

Nous créons ensuite toutes les actions de l’application Simple Text Viewer. L’action « assistantAct », accessible via le raccourci F1 ou l’élément de menu Aide > Sommaire de l’aide, présente un intérêt particulier. Cette action est reliée au slot « showDocumentation() » de la classe « MainWindow ».

void MainWindow::createActions()
{
    assistantAct = new QAction(tr("Help Contents"), this);
    assistantAct->setShortcut(QKeySequence::HelpContents);
    connect(assistantAct, &QAction::triggered, this, &MainWindow::showDocumentation);
    ...
}

Dans le slot ` showDocumentation() `, nous appelons la fonction ` showDocumentation() ` de la classe ` Assistant ` en lui passant l’URL de la page d’accueil de la documentation.

void MainWindow::showDocumentation()
{
    assistant->showDocumentation("index.html");
}

Enfin, nous devons réimplémenter le gestionnaire d'événement protégé `QWidget::closeEvent()` afin de garantir que l'instance ` Qt Assistant ` de l'application soit correctement fermée avant de quitter l'application.

void MainWindow::closeEvent(QCloseEvent *)
{
    delete assistant;
}

Classe FindFileDialog

L’application Simple Text Viewer fournit une boîte de dialogue de recherche de fichiers permettant à l’utilisateur de rechercher des fichiers à l’aide de caractères génériques. La recherche s’effectue dans le répertoire spécifié, et l’utilisateur a la possibilité de parcourir le système de fichiers existant pour trouver le répertoire pertinent.

Dans le constructeur, nous enregistrons les références aux objets ` Assistant ` et ` QTextEdit ` transmis en arguments. L’objet ` Assistant ` sera utilisé dans le slot ` help() ` de ` FindFileDialog`, comme nous le verrons sous peu, tandis que le `QTextEdit` sera utilisé dans le slot ` openFile() ` de la boîte de dialogue pour afficher le fichier sélectionné.

FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant)
    : QDialog(editor)
    , currentEditor(editor)
    , currentAssistant(assistant)
{
    ...
}

L'élément le plus pertinent à observer dans la classe ` FindFileDialog ` est le slot privé ` help() `. Ce slot est relié au bouton « Aide » de la boîte de dialogue et affiche au premier plan l'instance actuelle de ` Qt Assistant ` avec la documentation relative à la boîte de dialogue, en appelant la fonction ` showDocumentation() ` de ` Assistant`.

void FindFileDialog::help()
{
    currentAssistant->showDocumentation("filedialog.html");
}

Résumé

Pour que Qt Assistant fasse office d’outil d’aide personnalisé pour votre application, vous devez fournir à celle-ci un processus qui contrôle Qt Assistant, en plus d’un fichier de collection d’aide personnalisé comprenant des fichiers d’aide compressés Qt Help.

Pour plus d’informations sur les options et les paramètres disponibles pour les applications utilisant Qt Assistant comme visionneuse d’aide personnalisée, consultez la section Personnalisation d’ Qt Assistant.

Exemple de projet @ code.qt.io