Qt Help フレームワーク

概要

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

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

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

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

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

生成Qt Help

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

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

qhelpgenerator doc.qhp -o doc.qch

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

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

Qt Help コレクションの作成

最初のステップは、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 クラス・リファレンスを参照してください。