Qt 帮助框架

概述

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

实际的帮助数据，即目录、索引关键字或 HTML 文档，包含在 Qt 压缩帮助文件中。因此，这样的帮助文件通常代表一本手册或文档集。由于大多数产品都更加全面，由多个工具组成，一本手册通常是不够的。相反，存在更多手册，这些手册应该可以同时访问。理想情况下，还应该能够参考一本手册中某些有趣点的另一个手册。因此，Qt 帮助系统操作于帮助集合文件，这些文件包含任意数量的压缩帮助文件。

但是，将多个文档集合并为一个集合文件可能会导致一些问题。例如，一个索引关键字可能在不同的文档集中定义。因此，当只看到一个关键字在索引中并激活它时，您无法确定将要显示的是预期的文档。因此，Qt 帮助系统提供在特定属性后筛选帮助内容的功能。但是，这需要属性在生成压缩帮助文件之前已经分配给帮助内容。

如前所述，Qt 压缩帮助文件包含所有数据，因此不再需要分发所有单独的 HTML 文件。相反，只需分发压缩的帮助文件和可选的集合文件。集合文件是可选的，因为可以使用任何现有的集合文件，例如旧版本的集合文件。

因此，通常与帮助系统交互的文件有四个，用于生成 Qt 帮助的两个文件和用于分发的两个文件

生成 Qt 帮助

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

一旦 HTML 文档就绪，需要创建一个扩展名为 .qhp 的 Qt 帮助项目 文件。在文件中指定所有相关信息后，需要调用

qhelpgenerator doc.qhp -o doc.qch

文件 doc.qch 包含所有压缩的 HTML 文件以及目录和索引关键字。要测试生成的文件是否正确，请打开 Qt 助手并在 设置 > 文档 中安装该文件。

对于标准的 Qt 源构建，.qhp 文件将在与 HTML 页面相同的目录中生成。

创建 Qt 帮助集合

第一步是创建一个 Qt 帮助集合项目文件。由于 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 允许将帮助内容直接嵌入到应用程序中。

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

从文件引擎检索帮助数据不涉及大量的代码。第一步是创建一个帮助引擎实例。然后我们请求引擎获取分配给标识符的链接，在这种情况下为 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 类参考。