Qt Help 框架

概述

Qt 帮助系统包括用于生成和查看 Qt 帮助文件的工具。此外，它提供用于以编程方式访问帮助内容的类，为能够将在线帮助集成到 Qt 应用程序。

意味着内容表、索引关键字或 HTML 文档的实际帮助数据，包含在 Qt 压缩帮助文件中。因此，一个这种帮助文件通常表示一本手册或文档编制集。由于大多数产品更综合且由许多工具组成，因此，仅一本手册是远远不够的。相反，应同时存在更多可访问手册。理想情况下，将一本手册的某些点引用到另一本手册，应该是可能的。因此，Qt 帮助系统操作帮助集合文件，包括任意数量的压缩帮助文件。

不管怎样，拥有要合并许多文档编制集的集合文件，可能导致一些问题。例如，可以在不同文档编制集中定义一索引关键字。所以，当仅在索引中看到关键字并激活它时，将无法确保是否会展示期望文档编制。因此，Qt 帮助系统提供在某些属性之后，过滤帮助内容的可能性。不管怎样，这要求在生成压缩帮助文件之前，已将属性赋值给帮助内容。

如前所述，Qt 压缩帮助文件包含所有数据，因此不再需要随附所有单 HTML 文件。相反，仅必须分发压缩帮助文件和可选集合文件。集合文件是可选的，因为可以使用任何现有集合文件 (例如：来自较旧发行)。

因此，一般有 4 个文件与帮助系统交互，2 个用于生成 Qt 帮助，2 个用于分发：

名称	Extension	简要描述
Qt Help Project	.qhp	包含内容表、索引及实际文档编制文件 (* .html) 引用。它还为文档编制定义唯一名称空间。此文件被传递给帮助生成器，为创建压缩帮助文件。
Qt Compressed Help	.qch	包含在帮助工程文件中指定的所有信息，及所有压缩文档编制文件。
Qt Help Collection Project	.qhcp	An XML file that contains references to the compressed help files that should be included in the help collection. In addition, it may contain information for customizing Qt Assistant. This file can be passed to the help generator for creating a help collection file.
Qt Help Collection	.qhc	帮助集合文件 QHelpEngine operates on. It can contain references to any number of compressed help files as well as additional information.

生成 Qt Help

为 Qt 帮助系统构建帮助文件，假定 HTML 文档编制文件已存在。

一旦 HTML 文档到位， Qt Help Project 文件，采用扩展名 .qhp ，必须被创建。在此文件中指定所有相关信息后，需要编译通过调用：

qhelpgenerator doc.qhp -o doc.qch

文件 doc.qch 包含所有压缩形式的 HTML 文件、内容表及索引关键字。要测试生成文件是否正确，打开 Qt Assistant 并安装文件在设置 > 文档编制 .

对于标准 Qt 源代码构建，将生成 .qhp 文件并放在如 HTML 页面的相同目录下。

创建 Qt Help Collection

第一步是创建 Qt Help Collection 工程文件。由于 Qt Help Collection 存储压缩帮助文件的首要引用，因此工程 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 or register 章节，因此可以一次性生成和注册任意数量的压缩帮助文件。

使用 Qt Help

Accessing the help contents can be done in two ways: Using Qt Assistant as documentation browser or using the QHelpEngine API for embedding the help contents directly in an application.

使用 Qt Assistant

Qt Assistant operates on a collection file which can be specified before startup. If no collection file is given, a default one will be created and used. In either case, it is possible to register any Qt compressed help file and access the help contents.

When using Qt Assistant as the help browser for an application, it should be possible to customize it to fit the application better, so that it does not look like an independent, standalone help browser. To achieve this, several additional properties can be set in a Qt help collection file, to change for example the title or application icon of Qt Assistant. For more information, see the Qt Assistant 手册 .

使用 QHelpEngine API

Instead of showing the help in an external application like the Qt Assistant, it is also possible to embed the online help in the application. The contents can then be retrieved via the QHelpEngine 类且几乎可以按任何形式显示。展示帮助在 QTextBrowser 可能是最常见办法，但将其嵌入 What's This 帮助也十分可能。

从文件引擎检索帮助数据不涉及很多代码。第一步是创建帮助引擎实例。然后，向引擎询问赋值给标识符的链接，在这种情况 MyDialog::ChangeButton 。若找到链接，意味着至少存在有关此话题的一帮助文档，获得实际帮助内容通过调用 QHelpEngineCore::fileData () 并向用户显示文档。

QHelpEngineCore helpEngine("mycollection.qhc");
...
// get all file references for the identifier
QMap<QString, QUrl> links =
    helpEngine.linksForIdentifier(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().value());
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

有关如何使用 API 的更进一步信息，见 QHelpEngine 类参考。