Qt Help 框架

概述

Qt Help 系统包含用于生成和查看 Qt 帮助文件的工具。此外，它还提供了通过编程方式访问帮助内容的类，以便将在线帮助集成到 Qt 应用程序中。

实际的帮助数据（即目录、索引关键词或 HTML 文档）包含在 Qt Help 压缩帮助文件中。因此，通常一个此类帮助文件代表一本手册或一组文档。由于大多数产品内容较为全面且包含多种工具，仅靠一本手册往往难以满足需求。 相反，通常会存在多本手册，且应能同时访问。理想情况下，还应能够在一本手册中引用另一本手册中的特定内容。因此，Qt Help 系统基于帮助集合文件进行操作，这些文件包含任意数量的压缩帮助文件。

然而，使用集合文件来合并多个文档集可能会导致一些问题。例如，一个索引关键词可能在不同的文档集中被定义。因此，当仅在索引中看到一个关键词并点击它时，您无法确定是否会显示预期的文档。 因此，Qt Help 提供了根据特定属性过滤帮助内容的功能。但这要求在生成压缩帮助文件之前，已将这些属性分配给相应的帮助内容。

如前所述，Qt Help 压缩帮助文件包含所有数据，因此不再需要分发所有单独的 HTML 文件。取而代之的是，只需分发压缩帮助文件，并可选地分发集合文件。集合文件是可选的，因为可以使用任何现有的集合文件，例如来自旧版本的文件。

因此，总体而言，有四个文件与帮助系统相关联：其中两个用于生成 Qt Help，另外两个用于分发：

生成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 可将帮助内容直接嵌入到应用程序中。

与其在外部应用程序（如网页浏览器）中显示帮助，也可以将在线帮助嵌入到应用程序中。随后，可以通过QHelpEngine 类检索内容，并以几乎任何形式进行显示。在QTextBrowser 中显示帮助可能是最常见的方式，但将其嵌入“什么是这个”（What's This）帮助中也是完全可行的。

从文件引擎中检索帮助数据并不需要太多代码。 第一步是创建帮助引擎的实例。然后，我们向引擎查询分配给该标识符（本例中为MyDialog::ChangeButton ）的链接。如果找到了链接（即该主题下至少存在一份帮助文档），我们通过调用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 类参考文档。