Beispiel für einen einfachen Text-Viewer

Dieses Beispiel zeigt, wie Sie „ Qt Assistant “ als benutzerdefinierten Hilfe-Viewer in einer eigenen Anwendung verwenden können. Dies erfolgt in zwei Schritten. Zunächst wird die Dokumentation erstellt und „ Qt Assistant “ angepasst; anschließend wird die Funktionalität zum Starten und Steuern von „ Qt Assistant “ in die Anwendung integriert.

Die Anwendung „Simple Text Viewer“ ermöglicht es dem Benutzer, vorhandene Dateien auszuwählen und anzuzeigen. Die Anwendung verfügt über eine eigene, angepasste Dokumentation, die über das Menü „Hilfe“ in der Menüleiste des Hauptfensters oder durch Klicken auf die Schaltfläche „Hilfe“ im Dateisuchdialog der Anwendung aufgerufen werden kann.

Das Beispiel besteht aus vier Klassen:

• Assistant bietet Funktionen zum Starten von „ Qt Assistant “.
• MainWindow ist das Hauptfenster der Anwendung.
• FindFileDialog ermöglicht es dem Benutzer, mithilfe von Platzhaltern nach Dateien zu suchen.
• TextEdit stellt einen Rich-Text-Browser bereit, der sicherstellt, dass in HTML-Dokumenten referenzierte Bilder korrekt angezeigt werden.

Erstellen der Dokumentation und Anpassen Qt Assistant

Wie die eigentliche Dokumentation in Form von HTML-Seiten erstellt wird, liegt nicht im Rahmen dieses Beispiels. Im Allgemeinen können HTML-Seiten entweder von Hand geschrieben oder mithilfe von Dokumentationswerkzeugen wie qdoc oder Doxygen generiert werden. Für die Zwecke dieses Beispiels gehen wir davon aus, dass die HTML-Dateien bereits erstellt wurden. Es bleibt also nur noch, „ Qt Assistant “ mitzuteilen, wie die Hilfeinformationen strukturiert und angezeigt werden sollen.

Organisation der Dokumentation für Qt Assistant

Reine HTML-Dateien enthalten lediglich Text oder Dokumentation zu bestimmten Themen, jedoch in der Regel keine Informationen darüber, in welcher Beziehung mehrere HTML-Dokumente zueinander stehen oder in welcher Reihenfolge sie gelesen werden sollen. Was fehlt, ist ein Inhaltsverzeichnis sowie ein Index, um schnell auf bestimmte Hilfeinhalte zugreifen zu können, ohne zahlreiche Dokumente durchblättern zu müssen, um eine bestimmte Information zu finden.

Um die Dokumentation zu organisieren und für Qt Assistant verfügbar zu machen, müssen wir eine Qt Help-Projektdatei (.qhp) erstellen. Der erste und wichtigste Teil der Projektdatei ist die Definition des Namensraums. Der Namensraum muss eindeutig sein und bildet den ersten Teil der Seiten-URL unter Qt Assistant. Zudem müssen wir einen virtuellen Ordner festlegen, der als gemeinsamer Ordner für Dokumentationssätze dient. Das bedeutet, dass zwei durch unterschiedliche Namensräume identifizierte Dokumentationssätze Querverweise auf HTML-Dateien setzen können, da sich diese Dateien in einem großen virtuellen Ordner befinden. Für dieses Beispiel steht uns jedoch nur ein Dokumentationssatz zur Verfügung, sodass der Name und die Funktionalität des virtuellen Ordners keine Rolle spielen.

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

Der nächste Schritt besteht darin, den Filterabschnitt zu definieren. Ein Filterabschnitt enthält das Inhaltsverzeichnis, die Indizes und eine vollständige Liste aller Dokumentationsdateien und kann mit einer beliebigen Anzahl von Filterattributen versehen werden. Ein Filterattribut ist eine gewöhnliche Zeichenkette, die frei gewählt werden kann. Später unter Qt Assistant können Benutzer dann einen benutzerdefinierten Filter definieren, der auf diese Attribute verweist. Wenn die Attribute eines Filterabschnitts mit den Attributen des benutzerdefinierten Filters übereinstimmen, wird die Dokumentation angezeigt; andernfalls blendet Qt Assistant die Dokumentation aus.

Da wir wiederum nur über einen Dokumentationssatz verfügen, benötigen wir die Filterfunktion von Qt Assistant nicht und können daher auf die Filterattribute verzichten.

Nun erstellen wir das Inhaltsverzeichnis. Ein Eintrag im Inhaltsverzeichnis wird durch das Tag ` section ` definiert, das die Attribute für den Titel des Eintrags sowie den Link zur eigentlichen Seite enthält. Abschnittstags können unbegrenzt verschachtelt werden, aus praktischen Gründen wird jedoch empfohlen, sie nicht tiefer als drei oder vier Ebenen zu verschachteln. Für unser Beispiel möchten wir folgende Gliederung für das Inhaltsverzeichnis verwenden:

• Einfacher Text-Viewer
  • Datei suchen
    • Dateidialog
    • Platzhalter-Übereinstimmung
    • Durchsuchen
  • Datei öffnen

In der Hilfe-Projektdatei wird die Gliederung wie folgt dargestellt:

<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>

Nachdem das Inhaltsverzeichnis definiert ist, listen wir alle Stichwörter des Index auf:

<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>

Als letzten Schritt müssen wir alle Dateien auflisten, aus denen die Dokumentation besteht. Dabei ist zu beachten, dass alle Dateien aufgeführt werden müssen, einschließlich Bilddateien und sogar Stylesheets, sofern diese verwendet werden.

    <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>

Die Hilfe-Projektdatei ist nun fertiggestellt. Wenn Sie die resultierende Dokumentation in Qt Assistant anzeigen möchten, müssen Sie daraus eine komprimierte Qt Help-Datei erstellen und diese in der Standard-Hilfesammlung von Qt Assistant registrieren.

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

Wenn Sie nun Qt Assistant starten, sehen Sie die Dokumentation zum „Simple Text Viewer“ neben der Qt-Dokumentation. Für Testzwecke ist das in Ordnung, aber für die endgültige Version möchten wir, dass sich ausschließlich die Dokumentation zum „Simple Text Viewer“ unter Qt Assistant befindet.

Anpassen Qt Assistant

Der einfachste Weg, um zu erreichen, dass „ Qt Assistant “ ausschließlich die Dokumentation zum „Simple Text Viewer“ anzeigt, besteht darin, eine eigene Hilfesammlungsdatei zu erstellen. Eine Sammlungsdatei wird in einem binären Format gespeichert, ähnlich wie die komprimierte Hilfedatei, und aus einer Hilfesammlungs-Projektdatei (*.qhcp) generiert. Mithilfe einer Sammlungsdatei können wir das Erscheinungsbild und sogar einige Funktionen von „ Qt Assistant “ anpassen.

Zunächst ändern wir den Fenstertitel und das Symbol. Anstelle von „Qt Assistant “ wird nun „Simple Text Viewer“ angezeigt, sodass für den Benutzer viel deutlicher wird, dass der Hilfe-Viewer tatsächlich zu unserer Anwendung gehört.

<?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>

Das Tag „ cacheDirectory “ gibt ein Unterverzeichnis des Datenverzeichnisses des Benutzers an (siehe „Qt Help -Sammlungsdateien“), in dem die Cache-Datei für die Volltextsuche oder die Einstellungsdatei gespeichert wird.

Anschließend legen wir die Seite fest, die von „ Qt Assistant “ beim allerersten Start in der neuen Konfiguration angezeigt wird. Die URL besteht aus dem Namespace und dem virtuellen Ordner, die in der Qt Help-Projektdatei definiert sind, gefolgt vom eigentlichen Dateinamen der Seite.

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

Als Nächstes ändern wir den Namen des Menüeintrags „Über“ in „Über Simple Text Viewer“. Der Inhalt des „Über “-Dialogfelds wird ebenfalls geändert, indem wir eine Datei angeben, aus der der Text oder das Symbol für die „Über“-Informationen übernommen wird.

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

Qt Assistant Qt Assistant bietet die Möglichkeit, über den Einstellungsdialog Dokumentation hinzuzufügen oder zu entfernen. Diese Funktion ist hilfreich, wenn als zentraler Hilfe-Viewer für mehrere Anwendungen genutzt wird, aber in unserem Fall möchten wir eigentlich verhindern, dass der Benutzer die Dokumentation entfernt. Daher blenden wir die Registerkarte „Dokumentation“ im Einstellungsdialog aus.

Da die Adressleiste bei einem so kleinen Dokumentationsumfang nicht wirklich relevant ist, deaktivieren wir sie ebenfalls. Durch die Verwendung nur eines Filterbereichs ohne Filterattribute können wir zudem die Filterfunktionalität von „ Qt Assistant “ deaktivieren, was bedeutet, dass die Filterseite und die Filter-Symbolleiste nicht verfügbar sind.

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

Zu Testzwecken haben wir die komprimierte Hilfedatei bereits generiert und in der Standard-Hilfesammlung von Qt Assistant registriert. Mit den folgenden Zeilen erzielen wir das gleiche Ergebnis. Der einzige und wichtige Unterschied besteht darin, dass wir die komprimierte Hilfedatei nicht in der Standardsammlung, sondern in unserer eigenen Sammlungsdatei registrieren.

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

Als letzten Schritt müssen wir aus der Hilfssammlungs-Projektdatei die binäre Sammlungsdatei generieren. Dies geschieht durch Ausführen des Tools „ qhelpgenerator “.

qhelpgenerator simpletextviewer.qhcp -o simpletextviewer.qhc

Um alle unsere Anpassungen an „ Qt Assistant “ zu testen, fügen wir den Namen der Sammlungsdatei zur Befehlszeile hinzu:

assistant -collectionFile simpletextviewer.qhc

Steuerung von „ Qt Assistant “ über die Assistant-Klasse

Zunächst sehen wir uns an, wie „ Qt Assistant “ von einer Remote-Anwendung aus gestartet und bedient wird. Zu diesem Zweck erstellen wir eine Klasse namens „ Assistant “.

Diese Klasse stellt eine öffentliche Funktion bereit, mit der Seiten der Dokumentation angezeigt werden können, sowie eine private Hilfsfunktion, um sicherzustellen, dass „ Qt Assistant “ läuft.

Der Start von Qt Assistant erfolgt in der Funktion „ startAssistant() “, indem einfach ein „QProcess“ erstellt und gestartet wird. Läuft der Prozess bereits, kehrt die Funktion sofort zurück. Andernfalls muss der Prozess eingerichtet und gestartet werden.

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;
}

Um den Prozess zu starten, benötigen wir den Namen der ausführbaren Datei von „ Qt Assistant “ sowie die Befehlszeilenargumente, um „ Qt Assistant “ in einem angepassten Modus auszuführen. Der Name der ausführbaren Datei ist etwas knifflig, da er von der Plattform abhängt, unterscheidet sich jedoch glücklicherweise nur unter macOS.

Die angezeigte Dokumentation kann mithilfe des Befehlszeilenarguments „ -collectionFile “ beim Starten von „ Qt Assistant “ geändert werden. Wird „ Qt Assistant “ ohne Optionen gestartet, zeigt es einen Standardsatz an Dokumentationen an. Wenn Qt installiert ist, enthält der in „ Qt Assistant “ festgelegte Standarddokumentationssatz die Qt-Referenzdokumentation sowie die mit Qt gelieferten Tools, wie beispielsweise „ Qt Designer “ und „ qmake “.

In unserem Beispiel ersetzen wir den Standard-Dokumentationssatz durch unsere benutzerdefinierte Dokumentation, indem wir unsere anwendungsspezifische Sammeldatei als Argument an die Befehlszeilenoptionen des Prozesses übergeben.

Als letztes Argument fügen wir „ -enableRemoteControl “ hinzu, wodurch „ Qt Assistant “ auf seinem Kanal „ stdin “ auf Befehle wartet, beispielsweise solche, die eine bestimmte Seite in der Dokumentation anzeigen sollen. Anschließend starten wir den Prozess und warten, bis er tatsächlich läuft. Falls „ Qt Assistant “ aus irgendeinem Grund nicht gestartet werden kann, gibt „ startAssistant() “ den Wert „false“ zurück.

Die Implementierung von ` showDocumentation() ` ist nun unkompliziert. Zunächst stellen wir sicher, dass ` Qt Assistant ` läuft, dann senden wir die Anforderung zur Anzeige von ` page ` über den Kanal ` stdin ` des Prozesses. Dabei ist es sehr wichtig, dass der Befehl mit einem Zeilenende-Token abgeschlossen wird, um den Kanal zu leeren.

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');
}

Schließlich stellen wir sicher, dass „ Qt Assistant “ ordnungsgemäß beendet wird, falls die Anwendung heruntergefahren wird. Der Destruktor von „QProcess“ beendet den Prozess, was bedeutet, dass die Anwendung keine Möglichkeit hat, beispielsweise Benutzereinstellungen zu speichern, was zu beschädigten Einstellungsdateien führen würde. Um dies zu vermeiden, weisen wir „ Qt Assistant “ im Destruktor der Klasse „ Assistant “ an, sich selbst zu beenden.

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);
    }
}

Klasse „MainWindow“

Die Klasse „ MainWindow “ stellt das Hauptfenster der Anwendung mit zwei Menüs bereit: Über das Menü „Datei“ kann der Benutzer eine vorhandene Datei öffnen und anzeigen, während das Menü „Hilfe“ Informationen zur Anwendung und zu Qt bereitstellt und es dem Benutzer ermöglicht, Qt Assistant zu öffnen, um die Dokumentation der Anwendung anzuzeigen.

Um auf die Hilfefunktion zugreifen zu können, initialisieren wir das „ Assistant “-Objekt im Konstruktor von „ MainWindow “.

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

Anschließend erstellen wir alle Aktionen für die Anwendung „Simple Text Viewer“. Von besonderem Interesse ist die Aktion „ assistantAct “, die über die Tastenkombination F1 oder den Menüpunkt „Hilfe > Hilfe-Inhalt“ aufgerufen werden kann. Diese Aktion ist mit dem Slot „ showDocumentation() “ der Klasse „ MainWindow “ verbunden.

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

Im Slot „ showDocumentation() “ rufen wir die Funktion „ showDocumentation() “ der Klasse „ Assistant “ mit der URL der Startseite der Dokumentation auf.

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

Schließlich müssen wir den geschützten Ereignis-Handler `QWidget::closeEvent()` neu implementieren, um sicherzustellen, dass die ` Qt Assistant `-Instanz der Anwendung ordnungsgemäß geschlossen wird, bevor wir die Anwendung beenden.

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

Klasse „FindFileDialog“

Die Anwendung „Simple Text Viewer“ bietet einen Dateiauswahldialog, über den der Benutzer mithilfe von Platzhaltern nach Dateien suchen kann. Die Suche erfolgt innerhalb des angegebenen Verzeichnisses, und der Benutzer hat die Möglichkeit, das vorhandene Dateisystem zu durchsuchen, um das entsprechende Verzeichnis zu finden.

Im Konstruktor speichern wir die Referenzen auf die als Argumente übergebenen Objekte ` Assistant ` und ` QTextEdit `. Das ` Assistant `-Objekt wird, wie wir gleich sehen werden, im Slot ` help() ` des ` FindFileDialog` verwendet, während das `QTextEdit`-Objekt im Slot ` openFile() ` des Dialogs zum Anzeigen der ausgewählten Datei verwendet wird.

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

Das wichtigste Element in der Klasse „ FindFileDialog “ ist der private Slot „ help() “. Dieser Slot ist mit der Schaltfläche „Hilfe“ des Dialogs verbunden und ruft die Funktion „ showDocumentation() “ von „ Assistant “ auf, um die aktuelle Instanz von „ Qt Assistant “ mit der Dokumentation zum Dialog in den Vordergrund zu holen.

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

Zusammenfassung

Damit „ Qt Assistant “ als benutzerdefiniertes Hilfe-Tool für Ihre Anwendung fungieren kann, müssen Sie Ihrer Anwendung neben einer benutzerdefinierten Hilfesammeldatei, die komprimierte Qt Help-Dateien enthält, auch einen Prozess zur Verfügung stellen, der „ Qt Assistant “ steuert.

Weitere Informationen zu den Optionen und Einstellungen, die für Anwendungen verfügbar sind, die „ Qt Assistant “ als benutzerdefinierten Hilfe-Viewer verwenden, finden Sie unter „ Qt Assistant anpassen“.

Beispielprojekt @ code.qt.io