自定义 Qt 助手

将 Qt 助手 作为自定义帮助查看器使用，不仅需要能够显示自定义文档，同样重要的是，可以自定义 Qt 助手 的外观，使其看起来像特定应用程序的帮助查看器而不是 Qt 助手。这是通过更改窗口标题或图标，以及一些特定于应用程序的菜单文本和操作来实现的。有关可能的自定义列表的完整列表，请参阅创建自定义帮助收集文件。

自定义帮助查看器的另一个要求是能够从它提供帮助的应用程序接收动作或命令。当应用程序提供上下文相关帮助时，这一点尤为重要。当按这种方式使用时，帮助查看器可能需要根据应用程序当前的状态改变其内容。这意味着应用程序必须将当前状态传达给帮助查看器。有关更多信息，请参阅远程使用 Qt 助手。

示例简单文本查看器使用本文档中描述的技术，展示了如何将 Qt 助手 作为应用程序的自定义帮助查看器使用。

警告：为了在您的应用程序中分发 Qt 助手，您必须包含 sqlite 插件。有关如何在应用程序中包含插件的更多信息，请参阅部署文档。

Qt 帮助收集文件

关于 Qt 助手 的第一个重要之处是，它在帮助收集文件中存储与其外观相关的所有设置以及安装的文档列表。这意味着，当使用不同的收集文件启动 Qt 助手 时，Qt 助手 可能看起来完全不同。这种完整的设置分离使得可以在同一台机器上为多个应用程序部署 Qt 助手 作为自定义帮助查看器，而不会相互干扰。

要将某个帮助收集应用于 Qt 助手，在启动时在命令行上指定相应的收集文件。例如

assistant -collectionFile mycollection.qhc

然而，将所有设置存储在一个收集文件中会引发一些问题。该收集文件通常安装在应用程序本身所在的目录中，或其子目录之一。根据目录和操作系统，用户可能没有权限修改此文件（这将发生在用户设置存储时）。此外，甚至可能无法给予用户写权限，例如当文件位于只能读取的介质上时，如 CD-ROM。

即使可以为每个人提供将设置存储在全球可用集合文件的权限，用户的设置在退出 Qt 辅助工具 时也可能会被另一个用户覆盖。

为了解决这个困境，Qt 辅助工具 会创建用户特定的集合文件，这些文件从原始集合文件中复制而来。用户特定的集合文件将保存在由 QDesktopServices::AppDataLocation 返回的路径的子目录中。该子目录，即用户特定位置中的 缓存目录，可以在帮助集合项目文件中定义。例如

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        ...
    </assistant>
</QHelpCollectionProject>

因此，调用

assistant -collectionFile mycollection.qhc

Qt 辅助工具 实际上使用的是集合文件

%QDesktopServices::AppDataLocation%/mycompany/myapplication/mycollection.qhc

永远不需要用用户特定的集合文件启动 Qt 辅助工具。相反，应始终使用随应用程序提供的集合文件。此外，在添加或从集合文件中删除文档（参见下一节）时，请始终使用正常集合文件。Qt 辅助工具 会处理在已安装的文档列表更改时同步用户集合文件的问题。

显示自定义文档

在 Qt 辅助工具 能够显示文档之前，它必须知道可以在哪里找到实际的文档文件，这意味着它必须知道 Qt 压缩帮助文件 (*.qch) 的位置。正如之前提到的，Qt 辅助工具 将对压缩帮助文件的引用存储在当前使用的集合文件中。因此，在创建新的集合文件时，您可以列出 Qt 辅助工具 应显示的所有压缩帮助文件。

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    ...
    <docFiles>
        <register>
            <file>myapplication-manual.qch</file>
            <file>another-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

有时，根据 Qt 辅助工具 作为帮助查看器使用的应用程序，可能需要随着时间的推移添加更多文档；例如，在安装更多应用程序组件或插件时。这可以在 Qt 辅助工具 中通过选择编辑 > 首选项 > 文档来手动完成。然而，这种方法的缺点是每个用户都必须手动完成此操作才能访问新文档。

将文档添加到已存在的集合文件的推荐方法是使用 Qt 辅助工具 的 -register 命令行标志。当使用此标志启动 Qt 辅助工具 时，文档将被添加，并且 Qt 辅助工具 将立即退出，并显示消息以指示是否成功注册。

搜索索引只会索引您的自定义 *.html、*.htm 和 *.txt 文件。

assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

可以使用 -quiet 标志传递到 Qt 辅助工具，以防止它写出状态消息。

注意：Qt 辅助工具 按照注册的顺序在内容视图中显示文档。

更改 Qt 辅助工具的外观

可以通过启动时传递不同的命令行选项来更改 Qt 辅助工具 的外观。然而，这些命令行选项只能用来显示或隐藏特定小部件，例如内容或索引视图。其他自定义，例如更改应用程序标题或图标，或禁用过滤器功能，可以通过创建自定义帮助集合文件来完成。

创建自定义帮助集合文件

Qt 辅助工具 使用的帮助集合文件 (*.qhc) 是在运行 qhelpgenerator 工具时在帮助集合项目文件 (*.qhcp) 上创建的。项目文件格式是 XML，它支持以下标签

标签	简要说明
`<title>`	指定 Qt 辅助工具的窗口标题。
`<homePage>`	指定在 Qt 辅助工具主窗口中选择主页时要显示的页面。
`<startPage>`	指定在使用帮助集合时最初要显示的页面。
`<currentFilter>`	指定最初使用的过滤器。如果没有指定此过滤器，则不会对文档进行过滤。如果一个文档集已经安装，则此设置没有影响。
`<applicationIcon>`	描述了一个将用来替代常规 Qt Assistant 应用程序图标的图标。这一点被指定为相对于包含集合文件的目录的相对路径。
`<enableFilterFunctionality>`	启用或禁用用户可访问的过滤功能，使得在运行 Qt Assistant 时用户无法更改任何过滤器。这不意味着内部过滤功能完全被禁用。如果您要禁用过滤，请将值设置为 `false`。如果默认显示过滤器工具栏，请将属性 `visible` 设置为 `true`。
`<enableDocumentationManager>`	在首选项对话框中显示或隐藏文档选项卡。禁用文档选项卡可以限制 Qt Assistant 显示特定的文档集合或防止最终用户意外删除或安装文档。要隐藏文档选项卡，请将标签值设置为 `false`。
`<enableAddressBar>`	启用或禁用地址栏功能。默认情况下是启用的。要禁用它，请将标签值设置为 `false`。如果地址栏功能已启用，可以通过设置标签属性 `visible` 为 `true` 来显示地址栏。
`<aboutMenuText>, <text>`	列出在帮助菜单中的关于菜单项的本地化版本，例如关于应用程序。文本在 `text` 标签中指定。`language` 属性采用两位语言名称。如果没有指定语言属性，则使用该文本作为默认文本。
`<aboutDialog>, <file>, <icon>`	指定可从帮助菜单中打开的关于对话框的文本。文本来自 `file` 标签中的文件。可以指定不同的文件或任何语言。`icon` 标签定义的图标应用于所有语言。
`<cacheDirectory>, <cacheDirectory base="collection">`	指定用于存储全文搜索所需的索引文件和集合文件副本的缓存目录。副本是因为 Qt Assistant 将所有设置存储在集合文件中，因此它必须可由用户写入。目录是作为相对路径指定。如果 `base` 属性设置为 "collection"，则路径相对于包含集合文件的目录。如果属性设置为 "default" 或未设置，则路径相对于由 QDesktopServices::AppDataLocation 给定的目录。第一种形式对于在移动中使用的集合很有用，例如在 U 盘上携带。
`<enableFullTextSearchFallback>`	启用或禁用在索引中找不到关键字时回退并使用全文搜索的能力。在远程控制 Qt Assistant 的过程中可以使用此功能。要使其可用于远程控制，请将标签值设置为 `true`。

除了上述 Qt Assistant 特定标签之外，还可以使用用于生成和注册文档的标签。有关更多信息，请参阅 Qt 帮助集合文件文档。

以下是一个使用所有可用的标签的帮助集合文件的示例

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
        <title>My Application Help</title>
        <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
        <currentFilter>myfilter</currentFilter>
        <applicationIcon>application.png</applicationIcon>
        <enableFilterFunctionality>false</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar visible="true">true</enableAddressBar>
        <cacheDirectory>mycompany/myapplication</cacheDirectory>
        <aboutMenuText>
            <text>About My Application</text>
            <text language="de">Über meine Applikation...</text>
        </aboutMenuText>
        <aboutDialog>
            <file>about.txt</file>
            <file language="de">ueber.txt</file>
            <icon>about.png</icon>
        </aboutDialog>
    </assistant>
    <docFiles>
        <generate>
            <file>
                <input>myapplication-manual.qhp</input>
                <output>myapplication-manual.qch</output>
            </file>
        </generate>
        <register>
            <file>myapplication-manual.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

要创建二进制集合文件，请运行 qhelpgenerator 工具

qhelpgenerator mycollection.qhcp -o mycollection.qhc

要测试生成的集合文件，请按以下方式启动 Qt Assistant

assistant -collectionFile mycollection.qhc

在远程使用 Qt Assistant

尽管帮助查看器是一个独立的应用程序，但它通常会由它提供帮助的应用程序启动。这种方法使得应用程序有机会在帮助查看器启动时请求显示特定帮助内容。这种方法的另一个优点是，应用程序可以与帮助查看器进程进行通信，并根据应用程序的当前状态请求显示其他帮助内容。

因此，要将Qt Assistant作为您应用的定制帮助查看器，只需创建一个QProcess并指定Qt Assistant可执行文件的路径。为了让Qt Assistant监听您的应用程序，通过传递-enableRemoteControl命令行选项启用其远程控制功能。

以下示例展示了如何实现

QProcess *process = new QProcess;
QStringList args;
args << QLatin1String("-collectionFile")
    << QLatin1String("mycollection.qhc")
    << QLatin1String("-enableRemoteControl");
process->start(QLatin1String("assistant"), args);
if (!process->waitForStarted())
    return;

一旦Qt Assistant启动，您可以通过使用进程的stdin通道发送命令。以下代码片段展示了如何告诉Qt Assistant显示文档中的某个页面。

QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

注意：尾部的新行字符是必要的，用于标记输入的结束。

以下命令可用于控制Qt Assistant

命令	简要说明
`show <Widget>`	显示由<Widget>指定的侧边栏窗口（浮动小部件）。如果该小部件已显示，并且再次发送此命令，则小部件将被激活，这意味着它将被提升并获得输入焦点。<Widget>的可能值是"contents"，"index"，"bookmarks"或"search"。
`hide <Widget>`	隐藏指定的浮动小部件。<Widget>的可能值是"contents"，"index"，"bookmarks"和"search"。
`setSource <Url>`	显示给定的<Url>。该URL可以是绝对路径，也可以是相对于当前显示页面的相对路径。如果URL是绝对路径，则必须是有效的Qt帮助系统URL。也就是说，以"qthelp://"开头。
`activateKeyword <Keyword>`	将指定的<Keyword>插入索引浮动小部件的行编辑中，并激活索引列表中相应的项目。如果该项目与多个链接相关联，则将显示一个主题选择器。
`activateIdentifier <Id>`	显示给定<Id>的帮助内容。ID在每个命名空间中唯一，且只有一个链接与之关联，因此主题选择器永远不会弹出。
`syncContents`	选择与当前显示页面对应的内容小部件中的项目。
`setCurrentFilter <filter>`	选择指定的过滤器并更新相应的可视化表示。
`expandToc <Depth>`	将目录树展开到指定的深度。如果深度为0，树将完全折叠。如果深度为-1，树将完全展开。
`register <help file>`	将给定的Qt压缩帮助文件添加到集合中。
`unregister <help file>`	从集合中移除给定的Qt压缩帮助文件。

如果您想在短时间内发送多个命令，建议您只向进程的stdin写入单行，而不是为每个命令写一行。命令必须用分号分隔，如下例所示

QByteArray ba;
ba.append("hide bookmarks;");
ba.append("hide index;");
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

使用Qt Assistant 许可和归属

自定义 Qt 助手

Qt 帮助收集文件

显示自定义文档

更改 Qt 辅助工具 的外观

创建自定义帮助集合文件

在远程使用 Qt Assistant

更改 Qt 辅助工具的外观