Qtアシスタントのカスタマイズ

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

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

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

Qtヘルプ・コレクション・ファイル

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

特定のヘルプ・コレクションをQt Assistantに適用するには、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 Assistant は実際のドキュメントファイルがどこにあるかを知る必要があります。既に述べたように、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で「Edit（編集）」>「Preferences（環境設定）」>「 Documentation（ドキュメンテーション）」を選択して手動で行うことができます。しかし、この方法には、新しいドキュメントにアクセスするために、すべてのユーザーが手動で行う必要があるという欠点があります。

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

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

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

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

Qt アシスタントの外観を変更する

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 コマンド・ライン・オプションを指定して、Qt Assistant のリモート・コントロール機能をオンにします。

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

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