Qt Help 框架

概述

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

实际的帮助数据，即目录、索引关键字或 HTML 文档，都包含在 Qt 压缩的帮助文件中。因此，一个这样的帮助文件通常代表一个手册或文档集。由于大多数产品都比较全面，并由多个工具组成，因此一份手册很少是足够的。取而代之的是更多的手册，这些手册应该可以同时访问。理想情况下，还可以将一本使用手册中的某些兴趣点引用到另一本使用手册中。因此，Qt 帮助系统在帮助集合文件上运行，其中包括任意数量的压缩帮助文件。

不过，用集合文件来合并许多文档集可能会导致一些问题。例如，一个索引关键字可能在不同的文档集中都有定义。因此，如果只在索引中看到一个关键字并激活它，就不能确保会显示预期的文档。因此，Qt Help 系统提供了根据特定属性过滤帮助内容的可能性。不过，这要求在生成压缩帮助文件之前，已将属性分配给帮助内容。

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

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

生成Qt Help

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

一旦 HTML 文档就绪，就必须创建一个Qt Help 项目文件，扩展名为.qhp 。在该文件中指定所有相关信息后，需要调用以下命令对其进行编译：

qhelpgenerator doc.qhp -o doc.qch

文件doc.qch包含所有压缩的 HTML 文件以及目录和索引关键字。要测试生成的文件是否正确，请打开Qt Assistant 并将文件安装到Settings >Documentation 。

对于标准 Qt 源代码构建，会生成 .qhp 文件，并将其与 HTML 页面放置在同一目录下。

创建Qt Help 集合

第一步是创建Qt Help Collection 项目文件。由于 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 应用程序接口

QHelpEngine 可以将帮助内容直接嵌入应用程序。

与其在 Web 浏览器等外部应用程序中显示帮助，还不如将在线帮助嵌入到应用程序中。然后可以通过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 类参考。