Exemple de visualiseur de texte simple

Cet exemple montre comment utiliser Qt Assistant comme visualiseur d'aide personnalisé dans une application personnalisée. Cela se fait en deux étapes. Premièrement, la documentation est créée et Qt Assistant est personnalisé ; deuxièmement, 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 de visualiser des fichiers existants. L'application fournit sa propre documentation personnalisée qui est disponible dans le menu Aide de la barre de menu 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é de lancement de Qt Assistant.
• MainWindow est 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 riche qui s'assure que les images référencées dans les documents HTML sont affichées correctement.

Création de la documentation et personnalisation Qt Assistant

La création de 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 écrites à la main ou générées à l'aide d'outils de documentation tels que qdoc ou Doxygen. Pour les besoins de cet exemple, nous supposons 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.

Organiser la documentation pour Qt Assistant

Les fichiers HTML contiennent uniquement du texte ou de la documentation sur des sujets spécifiques, mais ils ne contiennent généralement pas d'informations sur la manière dont plusieurs documents HTML sont liés les uns aux autres ou sur l'ordre dans lequel ils sont censés être lus. Ce qui manque, c'est une table des matières et un index permettant d'accéder rapidement à certains contenus de l'aide, sans avoir à parcourir de nombreux documents pour trouver une information.

Pour organiser la documentation et la rendre disponible pour Qt Assistant, nous devons créer un fichier de projet d'aide Qt Help (.qhp). La première et la plus importante partie du fichier de projet est la définition de l'espace de noms. L'espace de noms doit être unique et sera la première partie de l'URL de la page dans Qt Assistant. En outre, nous devons définir un dossier virtuel qui agit comme un 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 puisque ces fichiers se trouvent dans un seul grand dossier virtuel. Cependant, dans cet exemple, nous n'aurons qu'un seul jeu de documentation disponible, de sorte que le nom et la fonctionnalité du dossier virtuel ne sont pas importants.

<?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 filtre. Une section filtre contient la table des matières, les index et une liste complète de tous les fichiers de documentation, et peut se voir attribuer un nombre quelconque d'attributs de filtre. Un attribut de filtre est une chaîne de caractères ordinaire qui peut être choisie librement. Plus tard dans Qt Assistant, les utilisateurs peuvent définir un filtre personnalisé faisant référence à ces attributs. Si les attributs d'une section de filtre correspondent aux attributs du filtre personnalisé, la documentation sera affichée, sinon Qt Assistant cachera la documentation.

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

Nous allons maintenant construire la table des matières. Un élément de la table est défini par la balise section qui contient les attributs du titre de l'élément ainsi qu'un lien vers la page en question. 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 voulons utiliser le schéma suivant pour la table des matières :

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

Dans le fichier du projet d'aide, le plan est représenté 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 dresserons la liste de 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>

La dernière étape consiste à dresser la liste de tous les fichiers qui composent la documentation. Il est important de noter que tous les fichiers doivent être listés, y compris les fichiers images 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 du projet d'aide est maintenant terminé. Si vous voulez voir la documentation résultante dans Qt Assistant, vous devez générer un fichier d'aide compressé Qt Help à partir de celui-ci et l'enregistrer avec 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 la documentation de Qt. C'est correct pour les tests, mais pour la version finale, nous voulons que seule la documentation de la visionneuse de texte simple se trouve sur Qt Assistant.

Personnalisation Qt Assistant

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

Tout d'abord, nous modifions le titre et l'icône de la fenêtre. Au lieu d'afficher "Qt Assistant", elle affichera " Simple Text Viewer ", de sorte qu'il sera beaucoup plus clair pour l'utilisateur que la visionneuse d'aide appartient en fait à 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 Qt Help Collection Files) où le fichier cache pour la recherche plein texte ou le fichier de configuration sera stocké.

Ensuite, nous définissons la page affichée par Qt Assistant lorsqu'il est lancé pour la première fois dans sa nouvelle configuration. L'URL se compose de l'espace de noms et du dossier virtuel définis dans le fichier du projet d'aide Qt Help, suivis du nom du fichier de la page.

<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 la visionneuse de texte simple". Le contenu de la boîte de dialogue " À propos" est également modifié en spécifiant un fichier d'où provient le texte ou l'icône "À propos".

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

Qt Assistant offre la possibilité d'ajouter ou de supprimer de la documentation via son dialogue de préférences. Cette fonctionnalité est utile lorsque l'on utilise Qt Assistant comme visualiseur d'aide central pour plusieurs applications, mais dans notre cas, nous voulons empêcher l'utilisateur de supprimer la documentation. Nous cachons donc l'onglet Documentation dans la boîte de dialogue Préférences.

Comme la barre d'adresse n'est pas vraiment pertinente dans une documentation aussi restreinte, nous la désactivons également. En n'ayant qu'une seule section de filtre, sans aucun attribut de filtre, nous pouvons également désactiver la fonctionnalité de filtre de Qt Assistant, ce qui signifie que la page de filtre et la barre d'outils de filtre 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 permettent d'obtenir le même résultat. La seule différence importante est 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>

La dernière étape consiste à générer le fichier de collecte 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 apportées à Qt Assistant, nous ajoutons le nom du fichier de collecte à la ligne de commande :

assistant -collectionFile simpletextviewer.qhc

Contrôle de Qt Assistant via la classe d'assistant

Nous allons d'abord voir comment démarrer et faire fonctionner Qt Assistant à partir d'une application distante. Pour ce faire, nous créons une classe appelée Assistant.

Cette classe fournit une fonction publique qui est utilisée pour afficher les pages de la documentation, et une fonction d'aide privée pour s'assurer que Qt Assistant est opérationnel.

Le lancement de Qt Assistant se fait 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 revient immédiatement. Dans le cas contraire, le processus doit être configuré et lancé.

bool Assistant::startAssistant()
{
    if (m_process.isNull()) {
        m_process.reset(new QProcess);
        QObject::connect(m_process.data(), &QProcess::finished,
                         m_process.data(), [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 la ligne de commande pour exécuter Qt Assistant dans un mode personnalisé. Le nom de l'exécutable est un peu délicat car il dépend de la plateforme, mais heureusement il n'est différent que sur macOS.

La documentation affichée peut être modifiée en utilisant 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é, le jeu de documentation par défaut dans 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 le jeu de documentation par défaut par notre documentation personnalisée en passant notre fichier de collection spécifique à l'application dans les options de la ligne de commande du processus.

Comme dernier argument, nous ajoutons -enableRemoteControl, qui fait en sorte que Qt Assistant écoute son canal stdin pour les commandes, comme celles d'afficher une certaine page de la documentation. Nous démarrons ensuite le processus et attendons qu'il s'exécute. Si, pour une raison quelconque, Qt Assistant ne peut pas être démarré, startAssistant() renverra false.

La mise en œuvre de showDocumentation() est maintenant simple. Tout d'abord, nous nous assurons que Qt Assistant est en cours d'exécution, puis nous envoyons la demande d'affichage de page via le canal stdin du processus. Il est très important que la commande soit terminée par un jeton de fin de ligne pour purger 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 tue le processus, ce qui signifie que l'application n'a pas la possibilité de faire des choses telles que sauvegarder les paramètres de l'utilisateur, ce qui entraînerait des fichiers de paramètres corrompus. Pour éviter cela, nous demandons à Qt Assistant de se terminer dans le destructeur de la classe Assistant.

Assistant::~Assistant()
{
    if (!m_process.isNull() && m_process->state() == QProcess::Running) {
        QObject::disconnect(m_process.data(), &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 File permet à l'utilisateur d'ouvrir et de visualiser un fichier existant, tandis que le menu Help fournit des informations sur l'application et sur Qt Help, 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 > Contenu de l'aide, est particulièrement intéressante. Cette action est connectée à l'emplacement 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 l'emplacement showDocumentation(), nous appelons la fonction showDocumentation() de la classe Assistant avec 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() pour nous assurer que l'instance Qt Assistant de l'application est correctement fermée avant de mettre fin à l'application.

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

Classe FindFileDialog

L'application Simple Text Viewer propose 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 est effectuée 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 tant qu'arguments. L'objet Assistant sera utilisé dans l'emplacement help() de FindFileDialog, comme nous le verrons bientôt, tandis que le QTextEdit sera utilisé dans l'emplacement openFile() de la boîte de dialogue pour afficher le fichier choisi.

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

Le membre le plus pertinent à observer dans la classe FindFileDialog est le slot privé help(). Ce slot est connecté au bouton Help de la boîte de dialogue et place l'instance Qt Assistant actuelle au premier plan avec la documentation de 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 agisse comme un outil d'aide personnalisé pour votre application, vous devez fournir à votre application un processus qui contrôle Qt Assistant en plus d'un fichier de collecte d'aide personnalisé comprenant des fichiers d'aide compressés de Qt Help.

Pour plus d'informations sur les options et les paramètres disponibles pour les applications qui utilisent Qt Assistant comme visualiseur d'aide personnalisé, voir Personnaliser Qt Assistant.

Exemple de projet @ code.qt.io