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 Assistant并在“设置>文档”中安装该文件。

对于标准的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 部分中指定多个文件，因此可以一次性生成和注册任意数量的压缩帮助文件。

使用Qt Help

可以通过两种方式访问帮助内容：使用Qt Assistant作为文档浏览器，或使用QHelpEngine API将帮助内容嵌入到应用程序中。

通过Qt Assistant

Qt Assistant对一个集合文件进行操作，该文件可以在启动前指定。如果未给定集合文件，则将创建并使用默认的集合文件。在任何一种情况下，都可以注册任何Qt压缩的帮助文件并访问帮助内容。

当使用Qt Assistant作为应用程序的帮助浏览器时，应该可以对其进行自定义以更好地适应应用程序，这样它就不会看起来像一个独立的帮助浏览器。为了实现这一点，可以在Qt帮助集合文件中设置几个附加属性，例如更改Qt Assistant的标题或应用程序图标。

通过QHelpEngine API

除了在外部应用程序（如Qt Assistant）中显示帮助之外，还可以在应用程序中嵌入在线帮助。然后可以通过QHelpEngine类检索内容，并且可以以几乎任何形式显示。在QTextBrowser中显示帮助可能是最常见的方式，但将其嵌入What’s This帮助中也是完全可能的。

从文件引擎检索帮助数据不涉及大量代码。第一步是创建帮助引擎的实例。然后，我们向引擎询问分配给标识符的链接，在本例中为MyDialog::ChangeButton。如果找到了一个链接，意味着该主题至少存在一个帮助文档，我们将通过调用QHelpEngineCore::fileData()来获得实际的帮助内容，并向用户显示该文档。

QHelpEngineCore helpEngine("mycollection.qhc");
...

// 获取标识符的所有文件引用
QList<QHelpLink> links = helpEngine.documentsForIdentifier(QLatin1String("MyDialog::ChangeButton"));

// 如果此关键字有帮助，请获取帮助数据
// 第一个文件引用。
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin()->url);
    // 向用户显示文档
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

有关如何使用API的更多信息，可以参考QtHelpEngine的官方说明。