Das „ Qt Help “-Framework

Übersicht

Das Qt Help-System umfasst Werkzeuge zum Erstellen und Anzeigen von Qt-Hilfedateien. Darüber hinaus stellt es Klassen für den programmgesteuerten Zugriff auf Hilfeinhalte bereit, um die Online-Hilfe in Qt-Anwendungen integrieren zu können.

Die eigentlichen Hilfedaten, d. h. das Inhaltsverzeichnis, die Stichwörter des Indexes oder HTML-Dokumente, sind in komprimierten Qt Help-Dateien enthalten. Eine solche Help-Datei entspricht somit in der Regel einem Handbuch oder einem Dokumentationssatz. Da die meisten Produkte umfangreicher sind und aus einer Reihe von Werkzeugen bestehen, reicht ein Handbuch selten aus. Stattdessen gibt es mehrere Handbücher, auf die gleichzeitig zugegriffen werden können sollte. Im Idealfall sollte es auch möglich sein, von einem Handbuch auf bestimmte relevante Stellen in einem anderen Handbuch zu verweisen. Daher arbeitet das Qt Help-System mit Hilfe-Sammlungsdateien, die eine beliebige Anzahl komprimierter Hilfedateien enthalten.

Die Verwendung von Sammeldateien zur Zusammenführung vieler Dokumentationssätze kann jedoch zu einigen Problemen führen. Beispielsweise kann ein Index-Schlüsselwort in verschiedenen Dokumentationssätzen definiert sein. Wenn man also nur ein Schlüsselwort im Index sieht und es anklickt, kann man nicht sicher sein, dass die erwartete Dokumentation angezeigt wird. Daher bietet das Qt Help-System die Möglichkeit, die Hilfeinhalte nach bestimmten Attributen zu filtern. Dies setzt jedoch voraus, dass die Attribute den Hilfeinhalten bereits vor der Erstellung der komprimierten Hilfedatei zugewiesen wurden.

Wie bereits erwähnt, enthält die komprimierte Qt Help-Datei alle Daten, sodass es nicht mehr notwendig ist, alle einzelnen HTML-Dateien mitzuliefern. Stattdessen müssen nur noch die komprimierte Help-Datei und optional die Sammeldatei verteilt werden. Die Sammeldatei ist optional, da jede vorhandene Sammeldatei, beispielsweise aus einer älteren Version, verwendet werden könnte.

Im Allgemeinen gibt es also vier Dateien, die mit dem Hilfesystem interagieren: zwei dienen der Erstellung der Qt Help und zwei sind für die Verteilung vorgesehen:

Erstellen Qt Help

Die Erstellung von Hilfedateien für das Qt Help-System setzt voraus, dass die HTML-Dokumentationsdateien bereits vorhanden sind.

Sobald die HTML-Dokumente vorliegen, muss eine „Qt Help “-Projektdatei mit der Erweiterung „ .qhp “ erstellt werden. Nachdem alle relevanten Informationen in dieser Datei angegeben wurden, muss sie durch folgenden Befehl kompiliert werden:

qhelpgenerator doc.qhp -o doc.qch

Die Datei „doc.qch“ enthält alle HTML-Dateien in komprimierter Form sowie das Inhaltsverzeichnis und die Stichwörter für den Index. Um zu überprüfen, ob die generierte Datei korrekt ist, öffnen Sie „ Qt Assistant “ und installieren Sie die Datei unter „ Settings > Documentation “.

Bei der Standard-Qt-Quellcode-Kompilierung wird die .qhp-Datei generiert und im selben Verzeichnis wie die HTML-Seiten abgelegt.

Erstellen einer „ Qt Help “-Sammlung

Der erste Schritt besteht darin, eine Projektdatei für eine „ Qt Help “-Sammlung zu erstellen. Da eine Qt Help-Sammlung in erster Linie Verweise auf komprimierte Hilfedateien enthält, sieht die Projektdatei „mycollection.qhcp“ erwartungsgemäß einfach aus:

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

Um die Sammlungsdatei tatsächlich zu erstellen, rufen Sie folgenden Befehl auf:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Um sowohl die komprimierte Hilfe als auch die Sammeldatei in einem Durchgang zu generieren, ändern Sie die Projektdatei der Hilfe-Sammlung so, dass der Hilfe-Generator angewiesen wird, zuerst die komprimierte Hilfe zu erstellen:

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

Natürlich ist es möglich, im Abschnitt „ generate “ oder „ register “ mehr als eine Datei anzugeben, sodass beliebig viele komprimierte Hilfedateien in einem Schritt generiert und registriert werden können.

Verwendung der QHelpEngine-API

QHelpEngine ermöglicht die direkte Einbettung der Hilfeinhalte in eine Anwendung.

Anstatt die Hilfe in einer externen Anwendung wie einem Webbrowser anzuzeigen, ist es auch möglich, die Online-Hilfe in die Anwendung einzubetten. Die Inhalte können dann über die Klasse „ QHelpEngine “ abgerufen und in nahezu beliebiger Form dargestellt werden. Die Anzeige der Hilfe in einem „ QTextBrowser “ ist wahrscheinlich die gängigste Methode, aber auch die Einbettung in die „What's This“-Hilfe ist problemlos möglich.

Das Abrufen von Hilfedaten aus der Datei-Engine erfordert nicht viel Code. Der erste Schritt besteht darin, eine Instanz der Hilfe-Engine zu erstellen. Anschließend fragen wir die Engine nach den Links, die dem Bezeichner zugeordnet sind, in diesem Fall MyDialog::ChangeButton. Wurde ein Link gefunden – was bedeutet, dass mindestens ein Hilfedokument zu diesem Thema existiert –, rufen wir QHelpEngineCore::fileData() auf, um den eigentlichen Hilfeinhalt abzurufen, und zeigen das Dokument dem Benutzer an.

QHelpEngineCore helpEngine("mycollection.qhc");
...

// get all file references for the identifier
QList<QHelpLink> links =
    helpEngine.documentsForIdentifier(QLatin1String("MyDialog::ChangeButton"));

// If help is available for this keyword, get the help data
// of the first file reference.
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin()->url);
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

Weitere Informationen zur Verwendung der API finden Sie in der Klassenreferenz zu QHelpEngine.