Anpassung Qt Assistant

Die Verwendung von „ Qt Assistant “ als benutzerdefinierten Hilfe-Viewer erfordert mehr als nur die Fähigkeit, benutzerdefinierte Dokumentation anzuzeigen. Ebenso wichtig ist es, dass das Erscheinungsbild von „ Qt Assistant “ so angepasst werden kann, dass es als anwendungsspezifischer Hilfe-Viewer und nicht als „ Qt Assistant “ wahrgenommen wird. Dies wird durch die Änderung des Fenstertitels oder des Symbols sowie einiger anwendungsspezifischer Menütexte und Aktionen erreicht. 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. Bei einer solchen Verwendung muss der Hilfe-Viewer seinen Inhalt möglicherweise je nach dem aktuellen Zustand der Anwendung anpassen. Das bedeutet, dass die Anwendung den aktuellen Zustand an den Hilfe-Viewer übermitteln muss. Weitere Informationen finden Sie unter „ Qt Assistant remote verwenden“.

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

Qt Help Sammlungsdateien

Qt Assistant Der erste wichtige Punkt, den Sie über „ Qt Assistant “ wissen sollten, ist, dass das Programm alle Einstellungen zu seinem Erscheinungsbild sowie eine Liste der installierten Dokumentationen in einer Hilfe-Sammlungsdatei speichert. Das bedeutet, dass „ Qt Assistant “ beim Starten mit unterschiedlichen Sammlungsdateien völlig anders aussehen kann. Diese vollständige Trennung der Einstellungen ermöglicht es, „ Qt Assistant “ als benutzerdefinierten Hilfe-Viewer für mehrere Anwendungen auf einem Rechner bereitzustellen, ohne dass es zu Interferenzen zwischen verschiedenen Instanzen von „ Qt Assistant “ kommt.

Um eine bestimmte Hilfesammlung auf Qt Assistant anzuwenden, geben Sie beim Start die entsprechende Sammlungsdatei über die Befehlszeile an. Beispiel:

assistant -collectionFile mycollection.qhc

Die Speicherung aller Einstellungen in einer einzigen Sammlungsdatei wirft jedoch einige Probleme auf. Die Sammlungsdatei wird in der Regel im selben Verzeichnis wie die Anwendung selbst oder in einem ihrer Unterverzeichnisse installiert. Je nach Verzeichnis und Betriebssystem verfügt der Benutzer möglicherweise nicht über die erforderlichen Berechtigungen, um diese Datei zu ändern, was jedoch erforderlich wäre, wenn die Benutzereinstellungen gespeichert werden. Außerdem ist es unter Umständen gar nicht möglich, dem Benutzer Schreibrechte zu erteilen, beispielsweise wenn sich die Datei auf einem schreibgeschützten Medium wie einer CD-ROM befindet.

Selbst wenn es möglich wäre, allen Benutzern das Recht zu gewähren, ihre Einstellungen in einer global verfügbaren Sammeldatei zu speichern, würden die Einstellungen eines Benutzers beim Beenden von „ Qt Assistant “ von denen eines anderen Benutzers überschrieben.

Um dieses Dilemma zu lösen, erstellt „ Qt Assistant “ benutzerspezifische Sammeldateien, die mehr oder weniger aus der ursprünglichen Sammeldatei kopiert werden. Die benutzerspezifische Sammeldatei wird in einem Unterverzeichnis des Pfads gespeichert, der von „QDesktopServices::AppDataLocation“ zurückgegeben wird. Das Unterverzeichnis bzw. das Cache-Verzeichnis innerhalb dieses benutzerspezifischen Speicherorts kann in der Projektdatei des Hilfe-Sammlungsprojekts definiert werden. Beispiel:

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

Wenn also

assistant -collectionFile mycollection.qhc

Qt Assistant tatsächlich die Sammeldatei verwendet:

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

Es ist niemals erforderlich, Qt Assistant mit der benutzerspezifischen Sammlungsdatei zu starten. Stattdessen sollte immer die mit der Anwendung ausgelieferte Sammlungsdatei verwendet werden. Verwenden Sie auch beim Hinzufügen oder Entfernen von Dokumentation aus der Sammlungsdatei (siehe nächster Abschnitt) stets die normale Sammlungsdatei. Qt Assistant übernimmt die Synchronisierung der benutzerspezifischen Sammlungsdateien, sobald sich die Liste der installierten Dokumentation geändert hat.

Anzeigen benutzerdefinierter Dokumentation

Bevor „ Qt Assistant “ Dokumentation anzeigen kann, muss es wissen, wo sich die eigentlichen Dokumentationsdateien befinden, 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 Sammeldatei. Beim Erstellen einer neuen Sammeldatei können Sie also 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>

Manchmal müssen, je nach der Anwendung, für die „ Qt Assistant “ als Hilfe-Viewer dient, im Laufe der Zeit weitere Dokumentationsinhalte hinzugefügt werden; beispielsweise bei der Installation weiterer Anwendungskomponenten oder Plugins. Dies kann manuell in „ Qt Assistant “ erfolgen, indem man „Bearbeiten > Einstellungen > Dokumentation“ auswählt. 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 vorhandenen Sammeldatei ist die Verwendung des -register -Befehlszeilenparameters von Qt Assistant. Wenn „ Qt Assistant “ mit diesem Parameter gestartet wird, wird die Dokumentation hinzugefügt und „ Qt Assistant “ wird sofort beendet, wobei eine Meldung angezeigt wird, ob die Registrierung erfolgreich war oder nicht.

Die Suchindizierung indiziert ausschließlich Ihre benutzerdefinierten *.html-, *.htm- und *.txt-Dateien.

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

Das Flag „ -quiet “ kann an „ Qt Assistant “ übergeben werden, um zu verhindern, dass die Statusmeldung ausgegeben wird.

Ändern des Erscheinungsbilds von Qt Assistant

Das Erscheinungsbild von „ Qt Assistant “ kann durch die Übergabe verschiedener Befehlszeilenoptionen beim Start geändert werden. Diese Befehlszeilenoptionen ermöglichen jedoch nur das Ein- oder Ausblenden bestimmter Widgets, wie beispielsweise der Inhalts- oder Indexansicht. Andere Anpassungen, wie das Ändern des Anwendungstitels oder -symbols oder das Deaktivieren der Filterfunktion, können durch das Erstellen einer benutzerdefinierten Hilfesammlungsdatei vorgenommen werden.

Erstellen einer benutzerdefinierten Hilfe-Sammlungsdatei

Die von „ Qt Assistant “ verwendete Hilfe-Sammlungsdatei (*.qhc) wird erstellt, wenn das Tool „ qhelpgenerator “ auf eine Hilfe-Sammlungs-Projektdatei (*.qhcp) angewendet wird. Das Projektdateiformat ist XML und unterstützt die folgenden Tags:

Zusätzlich zu diesen Qt Assistant -spezifischen Tags können die Tags zum Erstellen und Registrieren von Dokumentation verwendet werden. Weitere Informationen finden Sie in der Dokumentation zu Qt Help -Sammlungsdateien.

Ein Beispiel für eine Hilfe-Sammlungsdatei, die alle verfügbaren Tags verwendet, ist unten aufgeführt:

<?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 generierte Sammlungsdatei zu testen, starten Sie „ Qt Assistant “ wie folgt:

assistant -collectionFile mycollection.qhc

Remote-Verwendung von „ Qt Assistant “

Obwohl der Hilfe-Viewer eine eigenständige Anwendung ist, wird er meist von der Anwendung gestartet, für die er Hilfe bereitstellt. Dieser Ansatz ermöglicht es der Anwendung, bestimmte Hilfeinhalte anzufordern, die angezeigt werden sollen, sobald der Hilfe-Viewer gestartet wird. Ein weiterer Vorteil dieses Ansatzes besteht darin, dass die Anwendung mit dem Hilfe-Viewer-Prozess kommunizieren und somit je nach aktuellem Zustand der Anwendung die Anzeige weiterer Hilfeinhalte anfordern kann.

Um „ Qt Assistant “ als benutzerdefinierten Hilfe-Viewer für Ihre Anwendung zu verwenden, erstellen Sie einfach einen QProcess und geben Sie den Pfad zur ausführbaren Datei „ Qt Assistant “ an. Damit „ Qt Assistant “ auf Ihre Anwendung reagiert, aktivieren Sie die Fernsteuerungsfunktion, indem Sie die Befehlszeilenoption „ -enableRemoteControl “ übergeben.

Das folgende Beispiel zeigt, wie dies umgesetzt werden 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 “ läuft, können Sie Befehle über den stdin-Kanal des Prozesses senden. Der folgende Codeausschnitt zeigt, wie Sie „ Qt Assistant “ anweisen, eine bestimmte Seite in 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 kurzer Zeit senden möchten, empfiehlt es sich, nur eine einzige Zeile an die Eingabe (stdin) des Prozesses zu schreiben, anstatt für jeden Befehl eine eigene Zeile. 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);