利用Qt Assistant 定制帮助文档

为了将Qt Assistant定制为自己应用程序的帮助文档浏览器。需要完成以下几步：

一、导入HTML格式的帮助文档

（1）首先，针对自己的应用程序创建HTML格式的帮助文档，请参见《Doxygen生成HTML文件》。（下面示例假设HTML文件已经存在）

（2）新建Gui应用。QtCreator-->new Project-->Qt Widgets Application 新建项目名称定义为“MyHelpThis”，类名定义为“MainWindow”，基类保持QMainWindow不变。

（3）在项目目录中新建文件夹，命名为“documentation”。在documentation文件夹中再新建一个“images”文件夹，往里面拷贝一个图标图片，以后将作为Assistant程序左上角的图标，此例中使用了lib.png。

（4）在documentation文件夹中再新建一个“demoHtml”文件夹，将（1）生成的HTML文件拷贝至其中。此例中放入已经存在的7个HTML文件。

（5）其他.....

二、创建.qhp文件，并利用命令生成.qch文件

（1）关于qhp与qch

qhp是Qt Help Project的缩写，qhp类型文件是XML格式的，负责组织实际用到的帮助文件（通常为HTML文件，即需要在Qt Assistant中浏览的文件）。

qch是Qt Compressed Help的缩写，qch类型文件是二进制格式的，qch文件是Qt Assistant能够识别的文档最小单元，可以通过Qt Assistant->编辑->首选项->文档标签页->添加/移除操作来注册或者注销一个qch文件。也可以通过命令“assistant -register doc.qch”来注册qch文件。注册后，即可在Assistant界面中浏览帮助文档。

两者关系。qhp文件通过qhelpgenerator命令生成压缩的qch文件。命令格式如下：

　　qhelpgenerator myhelp.qhp -o myhelp.qch

（2）创建qhp文件。在documentation文件夹中创建一个文本文件，命名为“myhelp”，修改文件后缀为qhp，用Notepad++工具打开文件，编辑内容如下：

 <?xml version="1.0" encoding="GB2312"?>
 <QtHelpProject version="1.0">
   <namespace>bookmisClient.myhelp</namespace>
   <virtualFolder>doc</virtualFolder>
   <filterSection>
     <toc>
         <section title="首页" ref="./demoHtml/index.html">
             <section title="用户登录" ref="./demoHtml/userlogon.html"></section>
             <section title="书籍查询" ref="./demoHtml/bookquery.html"></section>
             <section title="续借书籍" ref="./demoHtml/Renewal.html"></section>
             <section title="系统管理" ref="./demoHtml/systemmanage.html"></section>
             <section title="日志管理" ref="./demoHtml/log.html"></section>
             <section title="关于" ref="./demoHtml/about.html"></section>
         </section>
     </toc>
     <keywords>
         <keyword name = "登录" ref="./demoHtml/userlogon.html"></keyword>
         <keyword name = "续借" ref="./demoHtml/Renewal.html"></keyword>
         <keyword name = "日志" ref="./demoHtml/log.html"></keyword>
     </keywords>
     <files>
       <file>demoHtml/*.html</file>
       <file>image/*.png</file>
     </files>
   </filterSection>
 </QtHelpProject>

（3）解读qhp文件。这个qhp文件是XML格式的。

　　①　第一行是XML序言，注意这里指定encoding为GB2312，这样是为了使用中文。如果只想使用英文，那么编码一般为UTF-8。

　　②　第二行指定了QtHelpProject版本为1.0

　　③　第三行指定了命名空间namespace，每一个qhp文件的命名空间都必须是唯一的，命名空间会成为Qt Assistant中页面的URL的第一部分。

　　④　第四行指定了一个虚拟文件夹virtualFolder，这个文件夹并不需要创建，它是指用来区分文件的。

　　⑤　过滤器。下面的过滤器部分filterSection标签包含了目录表、索引和所有文档文件的列表。过滤器部分可以设置过滤器属性，这样以后可以在Qt Assistant中通过过滤器来设置文档是否显示，不过，因为此例只有一个文档，所以不需要Qt Assistant的过滤器功能，这里也就不需要设置过滤器属性。

　　⑥　目录表。toc（table of contents）标签中创建了所有HTML文件的目录，指定了它们的标题和对应的路径，此例目录表为：

　　　　> 首页

　　　　　　> 用户登录

　　　　　　> 书籍查询

　　　　　　> 续借书籍

　　　　　　> 系统管理

　　　　　　> 日志管理

　　　　　　> 关于

　　⑦　keywords标签。指定了所有索引的关键字和对应的文件，这些关键字会显示在Qt Assistant的索引页面。

　　⑧　files标签。Files标签中列出了所有的文件，其中有HTML文件和图片文件。注意：如果有许多的同类型文件，直接可以写为：

<file>文件夹名称/*.文件类型</file>

　　⑨　其他....

（4）生成qch文件。

　　打开命令行控制台，使用cd命令跳转至项目目录的documentation目录下，然后依次输入下面的命令（当然，要保证命令正常运行，需要将Qt安装目录的bin目录路径添加到系统的PATH环境变量中）：

　　①　命令1：qhelpgenerator myhelp.qhp -o myhelp.qch

　　此命令作用生成qch文件。

　　②　命令2：assistant -register myhelp.qch

　　此命令作用注册qch文件。当注册成功后，会显示“documentation successfully registered”提示框。

　　③　命令3：assistant

　　此命令作用启动Assistant。当然，也可以从开始菜单中启动Qt Assistant。启动后可以在Assistant的内容Tab中目录表的最末尾找到我们的目录表，同时可以发现我们的HTML文档内容。

（5）不过，（4）不是必须的。只是为了测试qhp文件是否正确可用。另外，想象一下，生成一个帮助文档还追随在别人下面多俗呀~~~如果您仅仅为了想验证一下可行性，也可到此为止。否则，请再继续看下面内容。

（6）其他…..

三、创建.qhcp文件，并利用命令生成.qhc文件

　　欲使Qt Assistant只显示我们自己的帮助文档？最简单的方法就是生成帮助集合文件即.qhc文件。

（1）关于qhcp与qhc

qhcp是Qt Help Collection Project的缩写，该文件是XML格式的，其主要作用是将qch二进制文件组织成为一个collection，定制客户化的Assistant。

　　 qhc则是由qhcp文件通过qcollectiongenerator命令生成的二进制文件，启动Assistant时需要指定collection参数，即qhc文件。qhc文件中是qch文件的集合，打开Assistant时，通过指定当前collection即可注册多个帮助文档。命令格式如下：qcollectiongenerator myHelp.qhcp -o myHelp.qhc

（2）创建qhcp文件。在documentation文件夹中创建一个文本文件，命名为“myHelp”，修改文件后缀为qhcp，用Notepad++工具打开文件，编辑内容如下：

 <?xml version="1.0" encoding="GB2312"?>
 <QHelpCollectionProject version="1.0">
 <assistant>
   <title>图书管理客户端帮助文档</title>
   <applicationIcon>image/lib.png</applicationIcon>
   <cacheDirectory>cache/myhelp</cacheDirectory>
   <homePage>qthelp://bookmisClient.myhelp/doc/index.html</homePage>
   <startPage>qthelp://bookmisClient.myhelp/doc/index.html</startPage>
   <aboutMenuText>
     <text>关于</text>
   </aboutMenuText>
   <aboutDialog>
     <file>./about.txt</file>
     <icon>image/lib.png</icon>
   </aboutDialog>
   <enableDocumentationManager>false</enableDocumentationManager>
   <enableAddressBar>false</enableAddressBar>
   <enableFilterFunctionality>false</enableFilterFunctionality>
 </assistant>
 <docFiles>
   <generate>
     <file>
       <input>myhelp.qhp</input>
       <output>myhelp.qch</output>
     </file>
   </generate>
   <register>
     <file>myhelp.qch</file>
   </register>
 </docFiles>
 </QHelpCollectionProject>

（3）解读qhcp文件。这个qhcp文件也是XML格式的。

　　①　第一行、第二行同qhp文件解释。

　　②　第三行起始，assistant标签中是对Qt Assistant的外观和功能的定制。其中设置了标题、图标、缓存目录、主页、起始页、About菜单文本、关于对话框的内容和图标等，还关闭了一些没有用的功能。

　　③　第六行缓存目录cacheDirectory，是进行全文检索等操作时缓存文件要存放的位置。

　　④　第七、八行主页homePage、起始页startPage。这里使用了第二步中提到的Qt Assistant的页面的URL，这个URL由“qthelp://”开始，然后是在.qhp文件中设置的命名空间，然后是虚拟文件夹，最后是具体的HTML文件名。

　　⑤　关闭功能。因为Qt Assistant可以添加或者删除文档来为多个应用程序提供帮助，但此例只是为一个应用程序提供帮助，并且不希望删除我们的文档，所以禁用了文档管理器documentation manager；而且这里的文档集很小，而且只有一个过滤器部分，所以也关闭了地址栏address bar和过滤器功能filter functionality。

　　⑥　关于about.txt文件。在documentation目录下新建一个文本文件，命名为“about”，在其中输入此制作的帮助的说明信息，作为Qt Assistant的about菜单的显示内容。

　　⑦　docFiles标签。此标签其实就是完成了第二步中的所有命令操作，不过与第二步不同的是，第二步是在默认的集合文件中注册的，而这里是在我们自己的集合文件中注册的。

　　⑧　其他….

（4）生成.qhc文件。

　　打开命令行控制台，使用cd命令跳转至项目目录的documentation目录下，然后依次输入下面的命令（当然，要保证命令正常运行，需要将Qt安装目录的bin目录路径添加到系统的PATH环境变量中）：

　　①　命令1：qcollectiongenerator myhelp.qhcp –o myhelp.qhc

　　此命令作用生成qhc文件。

　　②　命令2：assistant -collectionFile myhelp.qhc

　　此命令作用为了测试我们定制的Assistant。此时在运行Qt Assistant时指定了集合文件为我们自己的qhc文件，所以运行后只仅仅显示我们自己的HTML文档。

　　现在，可以看到Qt Assistant的图标也更改了，打开帮助菜单中的“关于该帮助”菜单，也可以看到前面添加的about.txt文件的文本内容，效果如下图所示：

　　

（5）其他….

四、从程序中启动Qt Assistant查看帮助

（1）添加assistant类。添加新文件—>选择C++ class类，类名为assistant，基类不填写，类型信息选择无。

　　①　assistant.h文件如下（详见注释）：

 #ifndef ASSISTANT_H
 #define ASSISTANT_H

 #include <QtCore/QString>

 class QProcess;
 class Assistant
 {
 public:
     Assistant();
     ~Assistant();
     void showDocumentation(const QString &file);

 private:
     bool startAssistant();

 private:
     QProcess *proc;
 };

 #endif // ASSISTANT_H

　　②　assistant.cpp文件如下（详见注释）：

 #include <QtCore/QByteArray>
 #include <QtCore/QProcess>
 #include <QtWidgets/QMessageBox>
 #include "assistant.h"

 Assistant::Assistant(): proc()
 {
 }

 Assistant::~Assistant()
 {
    if (proc && proc->state() == QProcess::Running)
    {
        // 试图终止进程
        proc->terminate();
        proc->waitForFinished();
    }
    // 销毁proc
    delete proc;
 }

 // 显示文档
 void Assistant::showDocumentation(const QString &page)
 {
    if (!startAssistant())
        return;

    QByteArray ba("SetSource ");
    ba.append("qthelp://bookmisClient.myhelp/doc/");
    proc->write(ba + page.toLocal8Bit() + '\n');
 }

 // 启动Qt Assistant
 bool Assistant::startAssistant()
 {
    // 如果没有创建进程，则新创建一个
    if (!proc)
        proc = new QProcess();
    // 如果进程没有运行，则运行assistant，并添加参数
    if (proc->state() != QProcess::Running)
    {
        QString app = QLatin1String("../MyHelpThis/documentation/assistant.exe");
        QStringList args;
        args << QLatin1String("-collectionFile")
             << QLatin1String("../MyHelpThis/documentation/myhelp.qhc");
        proc->start(app, args); // 相当于执行命令：assistant –collectionFile myHelp.qhc
        if (!proc->waitForStarted())
        {
             QMessageBox::critical(, QObject::tr("my help"),
                 QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
             return false;
        }
    }
    return true;
 }

（2）准备assistant.exe程序。将Qt安装目录的bin目录中的assistant.exe程序复制到项目目录的documentation目录中。

（3）修改mainwindow.cpp文件。修改后具体如下（详见注释）：

 #include "mainwindow.h"
 #include "ui_mainwindow.h"
 #include "assistant.h"

 MainWindow::MainWindow(QWidget *parent)
     : QMainWindow(parent)
     , ui(new Ui::MainWindow)
     , pAssistant(nullptr)
 {
     ui->setupUi(this);
     // 创建命令按钮
     QAction* pHelp = new QAction("help", this);
     ui->mainToolBar->addAction(pHelp);
     // 绑定信号与槽
     connect(pHelp, SIGNAL(triggered()), this, SLOT(startAssistant()));
     // 创建Assistant对象
     pAssistant = new Assistant;
 }

 MainWindow::~MainWindow()
 {
     delete ui;
     delete pAssistant;
 }

 void MainWindow::startAssistant()
 {
     // 按下“help”按钮，运行Qt Assistant，显示index.html页面
     pAssistant->showDocumentation("index.html");
 }

（4）编译程序（注意工程的文件路径问题）。

（5）工程文件目录如下：

工程文件目录：

documentation文件夹目录：

（6）运行程序。按下工具栏的help按钮，就可以启动并查看帮助文档了。

五、利用批处理启动Qt Assistant查看帮助

　 利用程序启动Qt Assistant显得比较麻烦点！那么，如何可以快速启动Qt Assistant，不用每次都敲命令呢？我们可以选择使用批处理文件。

　 在documentation文件夹中新建一个文本文件，命名为“myhelp”,修改文件类型为bat。用Notepad++工具打开文件，编辑内容如下：

 echo off
 echo Setting up environment for Qt usage...
 set PATH=C:\Qt\Qt5.3.2\5.3\msvc2010_opengl\bin;%PATH%
 cd /D C:\Qt\Qt5.3.2\5.3\msvc2010_opengl
 cd /D F:\qtHelpDemoDoc\MyHelpThis\documentation
 qhelpgenerator myhelp.qhp -o myhelp.qch
 qcollectiongenerator myhelp.qhcp -o myhelp.qhc
 assistant -collectionFile myhelp.qhc
 echo Remember to call vcvarsall.bat to complete environment setup!

　　然后，双击bat文件执行。可以看到四（6）中按下help按钮同样的效果图。

注意 系统环境：Windows7 + Qt5.3.2 + QtCreator3.2.1

Good Good Study, Day Day Up.

顺序  选择  循环  总结