为Qt应用程序的用户添加帮助文档

qt5：简单文本查看器例子

Qt Assistant支持交互式帮助，并使您能够向Qt应用程序的用户显示客户文档。
以下示例说明如何将Qt Assistant用作应用程序的帮助查看器。

使用Qt Assistant作为应用程序的自定义help查看器

如何使用Qt Assistant作为应用程序的自定义help查看器。包括两个步骤：1.创建文档和自定义Qt Assistant；2.在应用程序中添加启动和控制Qt Assistant的功能。

简单文本查看器应用允许用户选择和查看现有的文件。应用提供了它自己自定义的文档，这个文档可以从主窗口的Help按钮获得，也可以通过点击应用中的find file dialog中Help按钮获得。

这个例子由四个类组成：

• Assitant提供启动Qt Assistant的功能
• MainWindow是主程序窗口
• FindFileDialog允许用户使用wildcard matching查找文件
• TextEdit提供一个富文本浏览器以确保HTML文档中引用的图片显示适当

创建文档和自定义Qt Assistant

如何创建一个真实的HTML网页文档不是本例子讨论的范围。通常，HTML网页可以手写或使用文档工具如qdoc或Doxygen生成help文档。在本例子，我们假设HTML文档已经创建好了。因此，我们只需要告诉Qt Assistant如何结构化和显示help信息。

为Qt Assistant组织文档

纯HTML文件只包含关于某个主题的文本或文档，但他们不包含几个HTML文档如何关联的或应该按照什么顺序阅读的信息。缺少一个索引目录来快速访问某个help内容，查找某个文档时不用浏览大量文档。

为了组织这些文档十七可以被Qt Assistant可用，我们需要创建一个Qt help project file(.qhp)。这个project 文件最先也是最重要的部分是定义namespace。命名空间必须唯一，而且Qt Assistant page URL的第一部分。另外，我们设置一个virtual folder作为文档集的公共文件夹。这就意味着，由两个不同命名空间标识的两个文档集可以交叉引用HTML文件，因为他们的文件在同一个大虚拟文件夹下。然而，在本案例中，我们只有一个文档集可用，因此virtual文件夹名和功能并不重要。

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
  <namespace>org.qt-project.examples.simpletextviewer</namespace>
  <virtualFolder>doc</virtualFolder>

下一个步骤是定义过滤器部分。一个过滤器部分包括目录、索引和所有文档文件的完整列表，可以为其分配任意数量过滤器属性。一个过滤器属性时一个普通字符串，可以自由选择。然后再Qt Assistant,用户可以参考这些属性自定一个过滤器。如果一个过滤器部分的属性匹配文档自定义过滤器属性，Qt Assistant会显示文档，否则隐藏这个文档。

因为我们只有一个文档集，我们并不需要Qt Assistant的过滤功能，从而跳过过滤器属性。

现在，我们建立目录。表中的项目由section标记定义，该标记包含项目标题的属性以及到实际页面的链接。section标记可以无限嵌套，但出于实际原因，不建议将其嵌套深度超过三层或四层。对于我们的示例，我们希望使用以下大纲作为目录：

在help项目文件中，上面的大纲由以下内容表示：

<filterSection>
  <toc>
    <section title="Simple Text Viewer" ref="index.html">
      <section title="Find File" ref="findfile.html">
        <section title="File Dialog" ref="filedialog.html"/>
        <section title="Wildcard Matching" ref="wildcardmatching.html"/>
        <section title="Browse" ref="browse.html"/>
      </section>
      <section title="Open File" ref="openfile.html"/>
    </section>
  </toc>

定义目录后，我们将列出所有索引关键字：

<keywords>
  <keyword name="Display" ref="index.html"/>
  <keyword name="Rich text" ref="index.html"/>
  <keyword name="Plain text" ref="index.html"/>
  <keyword name="Find" ref="findfile.html"/>
  <keyword name="File menu" ref="findfile.html"/>
  <keyword name="File name" ref="filedialog.html"/>
  <keyword name="File dialog" ref="filedialog.html"/>
  <keyword name="File globbing" ref="wildcardmatching.html"/>
  <keyword name="Wildcard matching" ref="wildcardmatching.html"/>
  <keyword name="Wildcard syntax" ref="wildcardmatching.html"/>
  <keyword name="Browse" ref="browse.html"/>
  <keyword name="Directory" ref="browse.html"/>
  <keyword name="Open" ref="openfile.html"/>
  <keyword name="Select" ref="openfile.html"/>
</keywords>

作为最后一步，我们必须列出构成文档的所有文件。这里需要注意的一点是，必须列出所有文件，包括图像文件，甚至样式表（如果使用）。

    <files>
      <file>browse.html</file>
      <file>filedialog.html</file>
      <file>findfile.html</file>
      <file>index.html</file>
      <file>intro.html</file>
      <file>openfile.html</file>
      <file>wildcardmatching.html</file>
      <file>images/browse.png</file>
      <file>images/fadedfilemenu.png</file>
      <file>images/filedialog.png</file>
      <file>images/handbook.png</file>
      <file>images/mainwindow.png</file>
      <file>images/open.png</file>
      <file>images/wildcard.png</file>
    </files>
  </filterSection>
</QtHelpProject>

help project文件现在已完成。如果您想在Qt Assistant中查看生成的文档，则必须生成一个Qt压缩帮助文件，并将其注册到Qt Assistant的默认帮助集合中。

qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
assistant -register simpletextviewer.qch

如果现在启动Qt Assistant，您将看到Qt文档旁边的Simple Text Viewer文档。这对于测试来说是可以的，但对于最终版本，我们只希望在Qt Assistant中有Simple Text Viewer文档。

自定义Qt Assistant

Qt助手只显示Simple Text Viewer文档，最简单方法是创建我们自己的帮助集合文件。集合文件以二进制格式存储，类似于压缩的帮助文件，并从help集合项目文件（*.qhcp）生成。在集合文件的帮助下，我们可以自定义外观以及Qt Assistant提供的一些功能。

首先，我们更改窗口标题和图标。显示“简单文本查看器”，而不是显示“Qt助手”，这样用户可以更清楚地知道这个帮助查看器是我们应用程序的帮助查看器。

<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
    <title>Simple Text Viewer</title>
    <applicationIcon>images/handbook.png</applicationIcon>
    <cacheDirectory>QtProject/SimpleTextViewer</cacheDirectory>

通过Assistant类控制Qt Assistant

总结

参考文档

Simple Text Viewer Example
生成 qch 帮助文档
qt help collection files
Customizing Qt Assistant