Anpassen von Qt Assistant

Die Verwendung von Qt Assistant als benutzerdefinierter Hilfe-Viewer erfordert mehr als nur die Möglichkeit, benutzerdefinierte Dokumentation anzuzeigen. Es ist ebenso wichtig, dass das Erscheinungsbild von Qt Assistant so angepasst werden kann, dass es als anwendungsspezifischer Hilfebetrachter und nicht als Qt Assistant wahrgenommen wird. Dies wird erreicht, indem der Fenstertitel oder das Symbol sowie einige anwendungsspezifische Menütexte und Aktionen geändert werden. Eine vollständige Liste der möglichen Anpassungen finden Sie unter Erstellen einer benutzerdefinierten Hilfesammlungsdatei.

Eine weitere Anforderung an einen benutzerdefinierten Hilfe-Viewer ist die Fähigkeit, Aktionen oder Befehle von der Anwendung zu empfangen, für die er Hilfe bereitstellt. Dies ist besonders wichtig, wenn die Anwendung kontextsensitive Hilfe anbietet. Wenn er auf diese Weise verwendet wird, muss der Help-Viewer möglicherweise seinen Inhalt ändern, je nachdem, in welchem Zustand sich die Anwendung gerade befindet. Das bedeutet, dass die Anwendung den aktuellen Zustand dem Hilfe-Viewer mitteilen muss. Weitere Informationen finden Sie unter Qt Assistant Remote verwenden.

Das Beispiel Simple Text Viewer verwendet die in diesem Dokument beschriebenen Techniken, um zu zeigen, wie Qt Assistant als benutzerdefinierter Hilfe-Viewer für eine Anwendung verwendet werden kann.

Qt Help Sammlungsdateien

Der erste wichtige Punkt, den Sie über Qt Assistant wissen sollten, ist, dass es alle Einstellungen, die sich auf sein Erscheinungsbild beziehen, und eine Liste der installierten Dokumentation in einer Hilfesammlungsdatei speichert. Das bedeutet, wenn Sie Qt Assistant mit verschiedenen Sammlungsdateien starten, kann Qt Assistant völlig anders aussehen. Diese vollständige Trennung der Einstellungen macht es möglich, Qt Assistant als benutzerdefinierten Hilfe-Viewer für mehr als eine Anwendung auf einem Rechner einzusetzen, ohne dass es zu Interferenzen zwischen verschiedenen Instanzen von Qt Assistant kommt.

Um eine bestimmte Hilfesammlung auf Qt Assistant anzuwenden, geben Sie die entsprechende Sammlungsdatei in der Befehlszeile an, wenn Sie das Programm starten. Ein Beispiel:

assistant -collectionFile mycollection.qhc

Die Speicherung aller Einstellungen in einer Sammlungsdatei wirft jedoch einige Probleme auf. Die Sammlungsdatei wird normalerweise im gleichen Verzeichnis wie die Anwendung selbst oder in einem ihrer Unterverzeichnisse installiert. Je nach Verzeichnis und Betriebssystem kann es sein, dass der Benutzer keine Berechtigung hat, diese Datei zu ändern, was bei der Speicherung der Benutzereinstellungen der Fall wäre. Auch kann es sein, dass es nicht möglich ist, dem Benutzer Schreibrechte zu erteilen, zum Beispiel wenn sich die Datei auf einem schreibgeschützten Medium wie einer CD-ROM befindet.

Selbst wenn es möglich ist, jedem das Recht zu geben, seine Einstellungen in einer global verfügbaren Sammeldatei zu speichern, würden die Einstellungen eines Benutzers beim Verlassen von Qt Assistant von einem anderen Benutzer überschrieben werden.

Um dieses Dilemma zu lösen, erstellt Qt Assistant benutzerspezifische Sammlungsdateien, die mehr oder weniger von der ursprünglichen Sammlungsdatei kopiert werden. Die benutzerspezifische Sammlungsdatei wird in einem Unterverzeichnis des von QDesktopServices::AppDataLocation zurückgegebenen Pfades gespeichert. Das Unterverzeichnis bzw. das Cache-Verzeichnis innerhalb dieses benutzerspezifischen Speicherorts kann in der Projektdatei der Hilfesammlung definiert werden. Ein Beispiel:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        ...
    </assistant>
</QHelpCollectionProject>

Also, wenn der Aufruf von

assistant -collectionFile mycollection.qhc

Qt Assistant tatsächlich die Sammlungsdatei verwendet:

%QDesktopServices::AppDataLocation%/mycompany/myapplication/mycollection.qhc

Es besteht keine Notwendigkeit, Qt Assistant mit der benutzerspezifischen Sammlungsdatei zu starten. Stattdessen sollte immer die mit der Anwendung ausgelieferte Sammlungsdatei verwendet werden. Auch beim Hinzufügen oder Entfernen von Dokumentation aus der Sammlungsdatei (siehe nächster Abschnitt) sollte immer die normale Sammlungsdatei verwendet werden. Qt Assistant kümmert sich um die Synchronisierung der Benutzersammlungsdateien, wenn sich die Liste der installierten Dokumentation geändert hat.

Anzeige der benutzerdefinierten Dokumentation

Bevor Qt Assistant in der Lage ist, Dokumentation anzuzeigen, muss es wissen, wo es die eigentlichen Dokumentationsdateien finden kann, d.h. es muss den Speicherort der komprimierten Qt-Hilfedatei (*.qch) kennen. Wie bereits erwähnt, speichert Qt Assistant Verweise auf die komprimierten Hilfedateien in der aktuell verwendeten Sammlungsdatei. Wenn Sie also eine neue Sammlungsdatei erstellen, können Sie alle komprimierten Hilfedateien auflisten, die Qt Assistant anzeigen soll.

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

Abhängig von der Anwendung, für die Qt Assistant als Hilfe-Viewer fungiert, muss manchmal im Laufe der Zeit mehr Dokumentation hinzugefügt werden, z.B. wenn weitere Anwendungskomponenten oder Plugins installiert werden. Dies kann manuell in Qt Assistant durch Auswahl von Bearbeiten > Voreinstellungen > Dokumentation geschehen. Dieser Ansatz hat jedoch den Nachteil, dass jeder Benutzer dies manuell tun muss, um Zugriff auf die neue Dokumentation zu erhalten.

Die bevorzugte Methode zum Hinzufügen von Dokumentation zu einer bereits existierenden Sammlungsdatei ist die Verwendung des -register Befehlszeilenflags von Qt Assistant. Wenn Qt Assistant mit diesem Flag gestartet wird, wird die Dokumentation hinzugefügt und Qt Assistant beendet sich sofort und zeigt eine Meldung an, ob die Registrierung erfolgreich war oder nicht.

Die Suchindizierung wird nur Ihre benutzerdefinierten *.html-, *.htm- und *.txt-Dateien indizieren.

assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

Das Flag -quiet kann an Qt Assistant weitergegeben werden, um zu verhindern, dass es die Statusmeldung ausgibt.

Ändern des Aussehens von Qt Assistant

Das Erscheinungsbild von Qt Assistant kann durch Übergabe verschiedener Befehlszeilenoptionen beim Start geändert werden. Diese Kommandozeilenoptionen erlauben jedoch nur das Ein- und Ausblenden bestimmter Widgets, wie der Inhalts- oder Indexansicht. Andere Anpassungen, wie das Ändern des Anwendungstitels oder des Symbols oder das Deaktivieren der Filterfunktionalität, können durch das Erstellen einer benutzerdefinierten Hilfesammlungsdatei vorgenommen werden.

Erstellen einer benutzerdefinierten Hilfesammlungsdatei

Die von Qt Assistant verwendete Hilfesammlungsdatei (*.qhc) wird erstellt, wenn das Werkzeug qhelpgenerator auf einer Hilfesammlungsprojektdatei (*.qhcp) ausgeführt wird. Das Projektdateiformat ist XML und unterstützt die folgenden Tags:

Zusätzlich zu diesen Qt Assistant -spezifischen Tags können auch die Tags für die Erstellung und Registrierung von Dokumentation verwendet werden. Weitere Informationen finden Sie in der Dokumentation Qt Help Sammeldateien.

Ein Beispiel für eine Hilfesammlungsdatei, die alle verfügbaren Tags verwendet, wird unten gezeigt:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
        <currentFilter>myfilter</currentFilter>
        <applicationIcon>application.png</applicationIcon>
        <enableFilterFunctionality>false</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar visible="true">true</enableAddressBar>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        <aboutMenuText>
            <text>About My Application</text>
            <text language="de">Über meine Applikation...</text>
        </aboutMenuText>
        <aboutDialog>
            <file>about.txt</file>
            <file language="de">ueber.txt</file>
            <icon>about.png</icon>
        </aboutDialog>
    </assistant>
    <docFiles>
        <generate>
            <file>
                <input>myapplication-manual.qhp</input>
                <output>myapplication-manual.qch</output>
            </file>
        </generate>
        <register>
            <file>myapplication-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

Um die binäre Sammlungsdatei zu erstellen, führen Sie das Tool qhelpgenerator aus:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Um die erzeugte Sammlungsdatei zu testen, starten Sie Qt Assistant auf die folgende Weise:

assistant -collectionFile mycollection.qhc

Qt Assistant ferngesteuert verwenden

Auch wenn der Hilfe-Viewer eine eigenständige Anwendung ist, wird er meist von der Anwendung gestartet, für die er Hilfe bereitstellt. Dieser Ansatz gibt der Anwendung die Möglichkeit, bestimmte Hilfeinhalte anzufordern, die angezeigt werden sollen, sobald der Hilfe-Viewer gestartet wird. Ein weiterer Vorteil dieses Ansatzes ist, dass die Anwendung mit dem Hilfe-Viewer-Prozess kommunizieren kann und daher andere Hilfeinhalte anfordern kann, die abhängig vom aktuellen Zustand der Anwendung angezeigt werden.

Um also Qt Assistant als benutzerdefinierten Hilfebetrachter für Ihre Anwendung zu verwenden, erstellen Sie einfach einen QProcess und geben Sie den Pfad zur ausführbaren Datei Qt Assistant an. Um Qt Assistant dazu zu bringen, auf Ihre Anwendung zu hören, aktivieren Sie seine Fernsteuerungsfunktionalität, indem Sie die Kommandozeilenoption -enableRemoteControl übergeben.

Das folgende Beispiel zeigt, wie dies geschehen kann:

QProcess *process = new QProcess;
QStringList args;
args << QLatin1String("-collectionFile")
    << QLatin1String("mycollection.qhc")
    << QLatin1String("-enableRemoteControl");
process->start(QLatin1String("assistant"), args);
if (!process->waitForStarted())
    return;

Sobald Qt Assistant ausgeführt wird, können Sie Befehle über den stdin-Kanal des Prozesses senden. Der folgende Codeausschnitt zeigt, wie man Qt Assistant anweist, eine bestimmte Seite der Dokumentation anzuzeigen.

QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

Die folgenden Befehle können zur Steuerung von Qt Assistant verwendet werden:

Wenn Sie mehrere Befehle innerhalb einer kurzen Zeitspanne senden wollen, ist es empfehlenswert, nur eine einzige Zeile in die stdin des Prozesses zu schreiben, anstatt eine Zeile für jeden Befehl. Die Befehle müssen durch ein Semikolon getrennt werden, wie im folgenden Beispiel gezeigt:

QByteArray ba;
ba.append("hide bookmarks;");
ba.append("hide index;");
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);