Qt 帮助框架使用

前面我们已经简单了解了Qt帮助框架，本节我们将举例说明生成Qt帮助集，并自定义Qt Assistant。

准备工作

因为创建帮助系统建立帮助文件的前提是HTML文档文件已经存在，所以我们来弄一些简单的HTML文档（难的我还不会）。

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>首页</title>
</head>
<body>
    <div class="brief-introduction">
        <p>欢迎来到啥也不是</p>
    </div>
</body>
</html>

section1.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>第一节</title>
</head>
<body>
    <div class="section 1">
        <div class="header">
            <p>第一节，学完啥也不是</p>
        </div>
        <div class="info">
            <p>啥也不是书里面写的就是啥也不是</p>
        </div>
        <div class="summary">
            <p>
                没啥可总结，啥也不是就是啥也不是。
            </p>
        </div>
    </div>
</body>
</html>

section2.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>第二节</title>
</head>
<body>
    <div class="section 2">
        <div class="header">
            <p>第二节，学完啥也不是</p>
        </div>
        <div class="info">
            <p>啥也不是书里面写的就是啥也不是</p>
        </div>
        <div class="summary">
            <p>
                没啥可总结，啥也不是就是啥也不是。
            </p>
        </div>
    </div>
</body>
</html>

section3.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>第三节</title>
</head>
<body>
    <div class="section 3">
        <div class="header">
            <p>第三节，学完啥也不是</p>
        </div>
        <div class="info">
            <p>啥也不是书里面写的就是啥也不是</p>
        </div>
        <div class="summary">
            <p>
                没啥可总结，啥也不是就是啥也不是。
            </p>
        </div>
    </div>
</body>
</html>

创建相关文件

创建Qt帮助项目文件（.qhp）

bmhelp.qhp

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
  <namespace>bmseven.myHelp</namespace>
  <virtualFolder>doc</virtualFolder>
  <filterSection>
    <toc>
      <section title="主页" ref="index.html">
        <section title="第一节" ref="section1.html">
        </section>
        <section title="第二节" ref="section2.html">
        </section>
        <section title="第三节" ref="section3.html">
        </section>
      </section>
    </toc>
    <keywords>
      <keyword name="section1" ref="section1.html" />
      <keyword name="section2" ref="section2.html" />
      <keyword name="section3" ref="section3.html" />
    </keywords>
    <files>
      <file>index.html</file>
      <file>section1.html</file>
      <file>section2.html</file>
      <file>section3.html</file>
    </files>
  </filterSection>
</QtHelpProject>

标签说明：

namespace：指qhp文件的命名空间，并且必须唯一，该命名空间在Assistant中会作为页面URL的第一部分。
virtualFolder：指虚拟文件夹，此文件夹并不需要创建，只用来区分文件。
filterSection：指过滤器，过滤器部分包含了所有的目录，索引和文件列表，可以通过设置过滤器属性，实现在Assistant中指定文档是否显示。
toc：指目录表（table of contents），在toc中创建了所有文档的目录，标题以及文档对应的路径。
keywords：用于指定所有搜索的关键字以及指定的文件。在Assistant中搜索的时候，会显示相应的页面。
files：包含Assistant需要引用的所有文件以及图片，可使用通配符*进行匹配。

生成Qt压缩帮助（.qch）

通过Qt控制台执行：

qhelpgenerator bmhelp.qhp -o bmhelp.qch

在这里插入图片描述

生成qch文件之后，需要注册才可以在Assistant中显示，一般有两种方式：

Qt终端执行：assistant -register bmhelp.qch
使用Assistant界面进行添加：编辑->首选项->文档->Add->Apply

在这里插入图片描述

注意：其实到这一步已经可以在Qt Assistant中查看我们自己创建的帮助文档了，但是包含qt的帮助文档，那么如何只显示我们自己的文档，并且定制化Qt Assistant呢？接着往下走吧~

创建Qt帮助收集项目文件（.qhcp）

bmhelp.qhcp

<?xml version="1.0" encoding="utf-8"?>
<QHelpCollectionProject version="1.0">
  <assistant>
    <title>bmseven的帮助系统</title>
    <applicationIcon>images/awesomeface.png</applicationIcon>
    <cacheDirectory>cache/bmhelp</cacheDirectory>
    <homePage>qthelp://bmseven.bmhelp/doc/index.html</homePage>
    <startPage>qthelp://bmseven.bmhelp/doc/index.html</startPage>
    <aboutMenuText>
      <text>关于该帮助</text>
    </aboutMenuText>
    <aboutDialog>
      <file>about.txt</file>
      <icon>images/awesomeface.png</icon>
    </aboutDialog>
    <enableDocumentationManager>false</enableDocumentationManager>
    <enableAddressBar>false</enableAddressBar>
    <enableFilterFunctionality>false</enableFilterFunctionality>
  </assistant>
  <docFiles>
    <generate>
      <file>
        <input>bmhelp.qhp</input>
        <output>bmhelp.qch</output>
      </file>
    </generate>
    <register>
      <file>bmhelp.qch</file>
    </register>
  </docFiles>
</QHelpCollectionProject>

标签说明：

assistant：对Qt Assistant进行一些定制化的操作，包括外观与功能，如标题，图标，缓存目录，主页，起始页，about菜单文本/对话框内容/图标。
cacheDirectory：缓存目录，在Qt Assistant中进行全文检索时会产生缓存文件。
homePage/startPage：Qt Assistant的主页/起始页，这里使用的URL构成格式为：

qthelp://namespace(qhp文件中指定的)/doc(qhp文件中指定的虚拟文件夹)/*html

aboutMenuText/aboutDialog：包括菜单文本，帮助对话框显示内容，图标等信息。
docFIles：文件转换与注册。（就是之前的命令行操作集成到该文件中了）

生成Qt帮助集（.qhc）

Qt控制台执行：

qhelpgenerator bmhelp.qhcp -o bmhelp.qhc

在这里插入图片描述

运行自定义Qt Assistant

Qt控制台执行：

assistant -collectionFile bmhelp.qhc

在这里插入图片描述

这就完事儿了，自定义的部分都跟着变化了，当需要嵌入到自己的应用程序中可使用代码调用，这里不做介绍了。

准备工作

创建相关文件

创建Qt帮助项目文件（.qhp）

生成Qt压缩帮助（.qch）

创建Qt帮助收集项目文件（.qhcp）

生成Qt帮助集（.qhc）

运行自定义Qt Assistant

猜你喜欢