Qt Help フレームワーク

概要

Qt Helpシステムには、Qtヘルプファイルを生成および表示するためのツールが含まれています。さらに、オンラインヘルプをQtアプリケーションに統合できるように、プログラムからヘルプコンテンツにアクセスするためのクラスも提供しています。

実際のヘルプデータ、すなわち目次、索引キーワード、またはHTMLドキュメントは、Qt Help圧縮ヘルプファイルに含まれています。したがって、通常、このようなヘルプファイル1つは、1つのマニュアルまたはドキュメントセットを表します。ほとんどの製品はより包括的で、多数のツールで構成されているため、マニュアル1つでは不十分な場合がほとんどです。 その代わりに、同時にアクセス可能な複数のマニュアルが存在します。理想的には、あるマニュアルの特定の項目を別のマニュアルから参照できることも望まれます。そのため、Qt Help システムは、任意の数の圧縮ヘルプファイルを含む「ヘルプコレクションファイル」を操作します。

しかし、多数のドキュメントセットを統合するためのコレクションファイルを使用すると、いくつかの問題が生じる可能性があります。例えば、1つの索引キーワードが異なるドキュメントセットで定義されている場合があります。そのため、索引でキーワードだけを見てそれをクリックしても、期待したドキュメントが表示されるとは限りません。 そのため、Qt Helpでは、特定の属性に基づいてヘルプ内容をフィルタリングする機能を提供しています。ただし、これを利用するには、圧縮ヘルプファイルの生成前に、ヘルプ内容に属性が割り当てられている必要があります。

前述の通り、Qt Helpの圧縮ヘルプファイルにはすべてのデータが含まれているため、個々のHTMLファイルをすべて同梱する必要はなくなりました。代わりに、圧縮ヘルプファイルと、必要に応じてコレクションファイルを配布すれば十分です。コレクションファイルはオプションです。これは、例えば以前のリリースなどの既存のコレクションファイルを利用できるためです。

したがって、一般的に、ヘルプシステムと連携するファイルは4つあり、そのうち2つはQt Helpの生成に使用され、残りの2つは配布用となっています：

生成Qt Help

Qt Help用のヘルプファイルをビルドするには、HTMLドキュメントファイルがすでに存在していることが前提となります。

HTMLドキュメントの準備が整ったら、拡張子が.qhpのQt Help プロジェクトファイルを作成する必要があります。このファイルにすべての関連情報を指定した後、以下のコマンドを実行してコンパイルする必要があります：

qhelpgenerator doc.qhp -o doc.qch

ファイル`doc.qch` には、目次や索引キーワードとともに、すべての HTML ファイルが圧縮された形で含まれています。生成されたファイルが正しいかどうかを確認するには、Qt Assistant を起動し、`Settings >Documentation` にそのファイルをインストールしてください。

標準的な Qt ソースビルドの場合、.qhp ファイルが生成され、HTML ページと同じディレクトリに配置されます。

Qt Help コレクションの作成

まず、Qt Help コレクションのプロジェクトファイルを作成します。Qt Helpコレクションは主に圧縮されたヘルプファイルへの参照を格納するため、mycollection.qhcpプロジェクトファイルの内容は、予想通り非常にシンプルです：

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

コレクションファイルを実際に作成するには、次のように呼び出します：

qhelpgenerator mycollection.qhcp -o mycollection.qhc

圧縮ヘルプとコレクションファイルを一度に生成するには、ヘルプコレクションのプロジェクトファイルを修正し、ヘルプジェネレータが最初に圧縮ヘルプを作成するように指示します:

...
<docFiles>
    <generate>
        <file>
            <input>doc.qhp</input>
            <output>doc.qch</output>
        </file>
    </generate>
    <register>
        <file>doc.qch</file>
    </register>
</docFiles>
...

もちろん、generate またはregister セクションで複数のファイルを指定することも可能なので、任意の数の圧縮済みヘルプファイルを一度に生成して登録することができます。

QHelpEngine API の使用

QHelpEngine を使用することで、ヘルプの内容をアプリケーションに直接埋め込むことができます。

Webブラウザなどの外部アプリケーションでヘルプを表示する代わりに、オンラインヘルプをアプリケーション内に組み込むことも可能です。その場合、QHelpEngine クラスを介してコンテンツを取得し、ほぼあらゆる形式で表示することができます。QTextBrowser でヘルプを表示するのがおそらく最も一般的な方法ですが、「What's This」ヘルプに組み込むことも十分に可能です。

ファイルエンジンからヘルプデータを取得するのに、多くのコードは必要ありません。 まず、ヘルプエンジンのインスタンスを作成します。次に、識別子（この場合は `MyDialog::ChangeButton`）に割り当てられたリンクをエンジンに問い合わせます。リンクが見つかった場合、つまりそのトピックに関するヘルプドキュメントが少なくとも1つ存在する場合、`QHelpEngineCore::fileData()` を呼び出して実際のヘルプコンテンツを取得し、ユーザーにドキュメントを表示します。

QHelpEngineCore helpEngine("mycollection.qhc");
...

// get all file references for the identifier
QList<QHelpLink> links =
    helpEngine.documentsForIdentifier(QLatin1String("MyDialog::ChangeButton"));

// If help is available for this keyword, get the help data
// of the first file reference.
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin()->url);
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

API の使用方法に関する詳細については、QHelpEngine のクラスリファレンスを参照してください。