Qtヘルプフレームワーク

概要

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

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

しかし、多くのドキュメントセットをマージするためにコレクションファイルを持つことは、いくつかの問題につながる可能性があります。例えば、1つのインデックスキーワードが異なるドキュメントセットで定義されている場合があります。そのため、インデックスのキーワードだけを見てアクティブにした場合、期待したドキュメントが表示されるかどうか確信が持てません。そのため、Qtヘルプシステムでは、特定の属性の後にヘルプ内容をフィルタリングする可能性を提供しています。ただし、圧縮されたヘルプファイルを生成する前に、その属性がヘルプコンテンツに割り当てられている必要があります。

すでに述べたように、Qt圧縮ヘルプファイルにはすべてのデータが含まれているので、単一のHTMLファイルをすべて出荷する必要はもうありません。代わりに、圧縮ヘルプファイルと、オプションでコレクションファイルのみを配布する必要があります。コレクションファイルはオプションで、例えば古いリリースのものなど、既存のコレクションファイルを使用することができます。

そのため、一般的に、Qtヘルプを生成するための2つのファイルと、配布するための2つのファイル、合計4つのファイルがヘルプシステムと相互作用します：

Qt ヘルプの生成

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

HTML ドキュメントを配置したら、.qhp という拡張子を持つQt Help Projectファイルを作成する必要があります。このファイルにすべての関連情報を指定した後、コンパイルする必要があります：

qhelpgenerator doc.qhp -o doc.qch

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

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

Qt ヘルプ集の作成

最初のステップは、Qt Help Collection Project ファイルを作成することです。Qtヘルプコレクションは主に圧縮されたヘルプファイルへの参照を保存するので、プロジェクトの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 クラス・リファレンスを参照してください。