カスタマイズQt Assistant

Qt Assistant をカスタムヘルプビューアとして使用するには、単にカスタムドキュメントを表示できるだけでは不十分です。Qt Assistant の外観をカスタマイズし、Qt Assistant ではなく、アプリケーション固有のヘルプビューアとして認識されるようにすることも同様に重要です。これは、ウィンドウのタイトルやアイコン、およびアプリケーション固有のメニューテキストやアクションを変更することで実現されます。 カスタマイズ可能な項目の完全な一覧については、「カスタムヘルプコレクションファイルの作成」を参照してください。

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

「Simple Text Viewer」のサンプルでは、このドキュメントで説明されている手法を用いて、Qt Assistant をアプリケーションのカスタムヘルプビューアとして使用する方法を紹介しています。

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

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

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

assistant -collectionFile mycollection.qhc

ただし、すべての設定を 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 で「編集」＞「設定」＞「ドキュメント」を選択して手動で行うことができます。しかし、この方法では、各ユーザーが新しいドキュメントにアクセスするために手動で設定を行う必要があるという欠点があります。

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

検索インデックス作成では、カスタム *.html、*.htm、および *.txt ファイルのみがインデックス対象となります。

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

-quiet フラグをQt Assistant に指定することで、ステータスメッセージの出力を抑制できます。

xml-ph-0000@deepl.internal の外観の変更Qt Assistant

Qt Assistant の外観は、起動時にさまざまなコマンドラインオプションを指定することで変更できます。ただし、これらのコマンドラインオプションでは、目次や索引ビューなどの特定のウィジェットの表示・非表示のみを設定できます。アプリケーションのタイトルやアイコンの変更、フィルタ機能の無効化など、その他のカスタマイズについては、カスタムヘルプコレクションファイルを作成することで実現できます。

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

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

これらのQt Assistant 固有のタグに加え、ドキュメントの生成および登録用のタグも使用できます。詳細については、『Qt Help コレクションファイル』のドキュメントを参照してください。

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

<?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 のリモート使用

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

したがって、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 が実行されると、プロセスのstdinチャネルを使用してコマンドを送信できます。以下のコードスニペットは、Qt Assistant にドキュメントの特定のページを表示させる方法を示しています。

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

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

短時間に複数のコマンドを送信したい場合は、コマンドごとに1行ずつ書くのではなく、プロセスの標準入力（stdin）に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);