カスタマイズQt Assistant

Qt Assistant をカスタムヘルプビューアとして使用するには、単にカスタムドキュメントを表示できるだけではありません。Qt Assistantウィンドウのタイトルやアイコン、アプリケーション固有のメニューテキストやアクションを変更することで、Qt Assistant の外観をカスタマイズすることができます。可能なカスタマイズの完全なリストについては、カスタムヘルプコレクションファイルの作成を参照してください。

カスタムヘルプビューアのもう1つの要件は、ヘルプを提供するアプリケーションからアクションやコマンドを受け取る機能です。これは、アプリケーションがコンテキスト依存ヘルプを提供している場合に特に重要です。このように使用される場合、ヘルプビューアは、アプリケーションが現在どのような状態にあるかによって内容を変更する必要があります。これは、アプリケーションが現在の状態をヘルプ・ビューワに伝える必要があることを意味します。詳しくはUsingQt Assistant Remotelyを参照してください。

Simple Text Viewer の例では、このドキュメントで説明されているテクニックを使用して、アプリケーションのカスタムヘルプビューアとしてQt Assistant を使用する方法を示しています。

Qt Help コレクションファイル

Qt Assistant について知っておくべき最初の重要な点は、外観に関するすべての設定と、インストールされているドキュメントのリストをヘルプ・コレクション・ファイルに保存することです。つまり、Qt Assistant を異なるコレクションファイルで起動すると、Qt Assistant の外観はまったく異なるものになります。このように設定が完全に分離されているため、Qt Assistant の異なるインスタンス間で干渉のリスクを負うことなく、Qt Assistant を 1 台のマシン上の複数のアプリケーション用のカスタムヘルプビューアとして展開することができます。

Qt Assistant に特定のヘルプ・コレクションを適用するには、起動時にコマンド・ライ ンでそれぞれのコレクション・ファイルを指定します。例えば

assistant -collectionFile mycollection.qhc

ただし、すべての設定を1つのコレクションファイルに保存すると、いくつかの問題が発生します。コレクションファイルは通常、アプリケーション自体と同じディレクトリか、そのサブディレクトリの1つにインストールされます。ディレクトリとオペレーティング・システムによっては、ユーザがこのファイルを変更する権限を持っていないかもしれません。また、ファイルが CD-ROM のような読み込み専用の媒体にある場合など、ユーザに書き込み権限を与 えることすらできないかもしれません。

グローバルに利用可能なコレクションファイルに設定を保存する権利を全員に与えることが可能だとしても、あるユーザーの設定は、Qt Assistant を終了するときに別のユーザーによって上書きされてしまいます。

このジレンマを解決するために、Qt Assistant は、オリジナルのコレクションファイルから多かれ少なかれコピーされたユーザー固有のコレクションファイルを作成します。ユーザー固有のコレクションファイルは、QDesktopServices::AppDataLocationによって返されるパスのサブディレクトリに保存されます。サブディレクトリ、またはこのユーザー固有の場所内のキャッシュディレクトリは、ヘルプ・コレクション・プロジェクト・ファイルで定義できます。たとえば、以下のようになります：

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

つまり

assistant -collectionFile mycollection.qhc

Qt Assistant を呼び出すと、実際にコレクションファイルが使用されます：

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

ユーザ固有のコレクションファイルでQt Assistant 。代わりに、アプリケーションに同梱されているコレクション・ファイルを常に使用する必要があります。また、コレクションファイルからドキュメントを追加または削除する場合（次のセクションを参照）、常に通常のコレクションファイルを使用してください。インストールされているドキュメントのリストが変更された場合、Qt Assistant がユーザーコレクションファイルの同期を行います。

カスタムドキュメントの表示

Qt Assistant がドキュメントを表示する前に、実際のドキュメントファイルがどこにあるかを知る必要があります。つまり、Qt の圧縮ヘルプファイル(*.qch)の場所を知る必要があります。すでに述べたように、Qt Assistant は、圧縮ヘルプファイルへの参照を、現在使用しているコレクションファイルに保存します。そのため、新しいコレクションファイルを作成するときに、Qt Assistant が表示すべきすべての圧縮ヘルプファイルをリストすることができます。

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

Qt Assistant がヘルプビューアとして動作するアプリケーションによっては、より多くのドキュメントを追加する必要がある場合があります。これは、Qt Assistant で「編集」 > 「環境設定」 > 「ドキュメント」を選択することで手動で行うことができます。しかし、この方法は、すべてのユーザーが新しいドキュメントにアクセスするために手動で行わなければならないという欠点があります。

すでに存在するコレクションファイルにドキュメントを追加する好ましい方法は、Qt Assistant の-register コマンドラインフラグを使用することです。このフラグを使用してQt Assistant を起動すると、ドキュメントが追加され、Qt Assistant は登録が成功したかどうかのメッセージを表示してすぐに終了します。

検索インデックスは、カスタム*.html、*.htm、および*.txtファイルのみをインデックスします。

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

-quiet フラグをQt Assistant に渡すと、ステータス・メッセージを書き出さないようにすることができます。

外観の変更Qt Assistant

起動時にさまざまなコマンドラインオプションを渡すことで、Qt Assistant の外観を変更することができる。ただし、これらのコマンドラインオプションで変更できるのは、コンテンツビューやインデックスビューのような特定のウィジェットの表示/非表示のみです。アプリケーションのタイトルやアイコンの変更、フィルター機能の無効化など、その他のカスタマイズはカスタムヘルプコレクションファイルを作成することで行うことができます。

カスタムヘルプコレクションファイルの作成

Qt Assistant で使用されるヘルプコレクションファイル (*.qhc) は、ヘルプコレクションプロジェクトファイル (*.qhcp) 上でqhelpgenerator ツールを実行すると作成されます。プロジェクトファイルの形式はXMLで、以下のタグをサポートしています：

これらのQt Assistant 固有のタグに加えて、ドキュメントの生成および登録用のタグも使用できます。詳しくはQt Help Collection Files のドキュメントを参照してください。

使用可能なすべてのタグを使用するヘルプ・コレクション・ファイルの例を、以下に示します：

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

バイナリ・コレクション・ファイルを作成するには、qhelpgenerator ツールを実行します：

qhelpgenerator mycollection.qhcp -o mycollection.qhc

生成されたコレクションファイルをテストするには、Qt Assistant を次のように起動します：

assistant -collectionFile mycollection.qhc

Qt Assistant をリモートで使用する

ヘルプ・ビューアはスタンドアロン・アプリケーションですが、ほとんどの場合、ヘルプを提供するアプリケーションによって起動されます。この方法では、ヘルプ・ビューワが起動するとすぐに、特定のヘルプ・コンテンツを表示するようアプリケーションに要求することができます。この方法のもう1つの利点は、アプリケーションがヘルプビューアプロセスと通信できるため、アプリケーションの現在の状態に応じて他のヘルプコンテンツの表示を要求できることです。

したがって、Qt Assistant をアプリケーションのカスタム・ヘルプ・ビューアーとして使用するには、QProcess を作成し、Qt Assistant 実行ファイルへのパスを指定するだけです。Qt Assistant 、アプリケーションをリッスンするようにするには、-enableRemoteControl コマンドラインオプションを指定して、リモートコントロール機能をオンにします。

次の例は、この方法を示しています：

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

Qt Assistant が実行されると、プロセスの標準入 力チャンネルを使用してコマンドを送信できます。以下のコード・スニペットは、Qt Assistant にドキュメントの特定のページを表示するように指示する方法を示しています。

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

Qt Assistant を制御するには、以下のコマンドを使用できます：

短時間に複数のコマンドを送信する場合は、コマンドごとに1行ではなく、プロセスの標準入力に1行だけ書き込むことをお勧めします。コマンドは以下の例のようにセミコロンで区切らなければならない：

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