Qt 帮助框架¶

概述¶

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

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

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

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

因此，通常有四个文件与帮助系统交互，其中两个用于生成Qt帮助，另外两个用于分发：

名称	扩展名	简要描述
Qt 帮助项目	.qhp	包含目录、索引和实际文档文件（*.html）的引用。它还定义了文档的唯一命名空间。此文件传递给帮助生成器以创建压缩的帮助文件。
Qt 压缩帮助	.qch	包含帮助项目文件中指定的所有信息以及所有压缩的文档文件。
Qt 帮助集合项目	.qhcp	一个包含对压缩帮助文件引用的 XML 文件，这些帮助文件应包含在帮助集合中。此文件可以传递给帮助生成器以创建帮助集合文件。
Qt 帮助集合	.qhc	帮助集合文件，QHelpEngine 操作的文件。它可以包含对任意数量的压缩帮助文件的引用以及附加信息。

生成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。如果找到了链接，意味着至少存在一个关于此主题的帮助文档，我们通过调用fileData()获取实际的帮助内容，并将文档显示给用户。

helpEngine = QHelpEngineCore("mycollection.qhc")
...
# get all file references for the identifier
links =
    helpEngine.documentsForIdentifier("MyDialog.ChangeButton")
# If help is available for this keyword, get the help data
# of the first file reference.
if links.count():
    helpData = helpEngine.fileData(links.constBegin().url)
    # show the documentation to the user
    if not helpData.isEmpty():
        displayHelp(helpData)

有关如何使用API的更多信息，请查看QHelpEngine类参考。