Der Qt Help Rahmen

Überblick

Das Qt-Hilfesystem enthält Werkzeuge zum Erzeugen und Anzeigen von Qt-Hilfedateien. Darüber hinaus bietet es Klassen für den programmatischen Zugriff auf Hilfeinhalte, um die Online-Hilfe in Qt-Anwendungen zu integrieren.

Die eigentlichen Hilfedaten, d.h. das Inhaltsverzeichnis, die Index-Schlüsselwörter oder HTML-Dokumente, sind in Qt-komprimierten Hilfedateien enthalten. Eine solche Hilfedatei stellt also in der Regel ein Handbuch oder eine Dokumentation dar. Da die meisten Produkte umfangreicher sind und aus einer Reihe von Werkzeugen bestehen, ist ein Handbuch selten ausreichend. Stattdessen gibt es mehrere Handbücher, die gleichzeitig zugänglich sein sollten. Idealerweise sollte es auch möglich sein, auf bestimmte interessante Punkte eines Handbuchs in einem anderen zu verweisen. Deshalb arbeitet das Qt-Hilfesystem mit Hilfesammeldateien, die eine beliebige Anzahl von komprimierten Hilfedateien enthalten.

Allerdings können Sammeldateien, die viele Dokumentationen zusammenfassen, zu einigen Problemen führen. Zum Beispiel kann ein Index-Schlüsselwort in verschiedenen Dokumentations-Sets definiert sein. Wenn Sie also nur ein Schlüsselwort im Index sehen und es aktivieren, können Sie 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 allerdings voraus, dass die Attribute vor der Erzeugung der komprimierten Hilfedatei den Hilfeinhalten zugewiesen wurden.

Wie bereits erwähnt, enthält die komprimierte Qt-Hilfedatei alle Daten, so dass es nicht mehr notwendig ist, alle einzelnen HTML-Dateien auszuliefern. Stattdessen müssen nur noch die komprimierte Hilfedatei und optional die Sammeldatei verteilt werden. Die Sammeldatei ist optional, da jede bestehende Sammeldatei, zum Beispiel aus einer älteren Version, verwendet werden kann.

Im Allgemeinen gibt es also vier Dateien, die mit dem Hilfesystem interagieren, zwei für die Erzeugung der Qt-Hilfe und zwei für die Verteilung:

Erzeugen von Qt Help

Die Erstellung von Hilfedateien für das Qt-Hilfesystem setzt voraus, dass die HTML-Dokumentationsdateien bereits existieren.

Sobald die HTML-Dokumente vorhanden sind, muss eine Qt Help Projektdatei mit der Erweiterung .qhp erstellt werden. Nachdem alle relevanten Informationen in dieser Datei angegeben wurden, muss sie durch Aufruf kompiliert werden:

qhelpgenerator doc.qhp -o doc.qch

Die Datei doc.qch enthält alle HTML-Dateien in komprimierter Form zusammen mit dem Inhaltsverzeichnis und den Index-Schlüsselwörtern. Um zu testen, ob die erzeugte Datei korrekt ist, öffnen Sie Qt Assistant und installieren Sie die Datei unter Settings > Documentation.

Beim Standard-Qt-Quellcode-Build wird die .qhp-Datei erzeugt und im selben Verzeichnis wie die HTML-Seiten abgelegt.

Erstellen einer Qt Help Sammlung

Der erste Schritt besteht darin, eine Qt Help Collection Project Datei zu erstellen. Da eine Qt-Hilfe-Sammlung hauptsächlich Verweise auf komprimierte Hilfedateien speichert, sieht die Projektdatei mycollection.qhcp wenig überraschend einfach aus:

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

Zum eigentlichen Erstellen der Sammlungsdatei rufen Sie auf:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Um sowohl die komprimierte Hilfe als auch die Sammeldatei in einem Durchgang zu erzeugen, ändern Sie die Projektdatei der Hilfesammlung so, dass sie den Hilfegenerator anweist, zuerst die komprimierte Hilfe zu erzeugen:

...
<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, mehr als eine Datei im Abschnitt generate oder register anzugeben, so dass eine beliebige Anzahl von komprimierten Hilfedateien in einem Durchgang erzeugt und registriert werden kann.

QHelpEngine API verwenden

QHelpEngine können die Hilfeinhalte direkt in eine Anwendung eingebettet werden.

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 sind dann über die Klasse QHelpEngine abrufbar und können in nahezu beliebiger Form angezeigt werden. Die Anzeige der Hilfe in einem QTextBrowser ist wahrscheinlich die gebräuchlichste Form, aber auch die Einbettung in die What's This-Hilfe ist durchaus möglich.

Das Abrufen von Hilfedaten aus der Dateimaschine erfordert nicht viel Code. Der erste Schritt besteht darin, eine Instanz der Hilfemaschine zu erstellen. Dann fragen wir die Engine nach den Links, die dem Bezeichner zugeordnet sind, in diesem Fall MyDialog::ChangeButton. Wenn ein Link gefunden wurde, was bedeutet, dass mindestens ein Hilfedokument zu diesem Thema existiert, holen wir uns den eigentlichen Hilfeinhalt durch den Aufruf von QHelpEngineCore::fileData() und zeigen dem Benutzer das Dokument 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 über die Verwendung der API finden Sie in der Klassenreferenz QHelpEngine.