利用Qt Assistant 定制帮助文档

时间 2019-11-09

标签利用 assistant 定制帮助文档繁體版

原文原文链接

为了将Qt Assistant定制为本身应用程序的帮助文档浏览器。须要完成如下几步：html

1、导入HTML格式的帮助文档浏览器

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

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

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

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

（5）其余.....测试

2、建立.qhp文件，并利用命令生成.qch文件ui

（1）关于qhp与qchthis

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++工具打开文件，编辑内容以下：

 1 <?xml version="1.0" encoding="GB2312"?>
 2 <QtHelpProject version="1.0">
 3   <namespace>bookmisClient.myhelp</namespace>
 4   <virtualFolder>doc</virtualFolder>
 5   <filterSection>
 6     <toc>
 7         <section title="首页" ref="./demoHtml/index.html">
 8             <section title="用户登陆" ref="./demoHtml/userlogon.html"></section>
 9             <section title="书籍查询" ref="./demoHtml/bookquery.html"></section>
10             <section title="续借书籍" ref="./demoHtml/Renewal.html"></section>
11             <section title="系统管理" ref="./demoHtml/systemmanage.html"></section>
12             <section title="日志管理" ref="./demoHtml/log.html"></section>
13             <section title="关于" ref="./demoHtml/about.html"></section>
14         </section>
15     </toc>
16     <keywords>
17         <keyword name = "登陆" ref="./demoHtml/userlogon.html"></keyword>
18         <keyword name = "续借" ref="./demoHtml/Renewal.html"></keyword>
19         <keyword name = "日志" ref="./demoHtml/log.html"></keyword>
20     </keywords>
21     <files>
22       <file>demoHtml/*.html</file>
23       <file>image/*.png</file>
24     </files>
25   </filterSection>
26 </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）其余…..

3、建立.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++工具打开文件，编辑内容以下：

 1 <?xml version="1.0" encoding="GB2312"?>
 2 <QHelpCollectionProject version="1.0">
 3 <assistant>
 4   <title>图书管理客户端帮助文档</title>
 5   <applicationIcon>image/lib.png</applicationIcon>
 6   <cacheDirectory>cache/myhelp</cacheDirectory>
 7   <homePage>qthelp://bookmisClient.myhelp/doc/index.html</homePage>
 8   <startPage>qthelp://bookmisClient.myhelp/doc/index.html</startPage>
 9   <aboutMenuText>
10     <text>关于</text>
11   </aboutMenuText>
12   <aboutDialog>
13     <file>./about.txt</file>
14     <icon>image/lib.png</icon>
15   </aboutDialog>
16   <enableDocumentationManager>false</enableDocumentationManager>
17   <enableAddressBar>false</enableAddressBar>
18   <enableFilterFunctionality>false</enableFilterFunctionality>
19 </assistant>
20 <docFiles>
21   <generate>
22     <file>
23       <input>myhelp.qhp</input>
24       <output>myhelp.qch</output>
25     </file>
26   </generate>
27   <register>
28     <file>myhelp.qch</file>
29   </register>
30 </docFiles>
31 </QHelpCollectionProject>

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

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

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

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

　　④　第7、八行主页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文件。

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

　　此命令做用生成qhc文件。

　　②　命令2：assistant -collectionFile myhelp.qhc

　　此命令做用为了测试咱们定制的Assistant。此时在运行Qt Assistant时指定了集合文件为咱们本身的qhc文件，因此运行后只仅仅显示咱们本身的HTML文档。

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

（5）其余….

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

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

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

 1 #ifndef ASSISTANT_H
 2 #define ASSISTANT_H
 3 
 4 #include <QtCore/QString>
 5 
 6 class QProcess;
 7 class Assistant
 8 {
 9 public:
10     Assistant();
11     ~Assistant();
12     void showDocumentation(const QString &file);
13 
14 private:
15     bool startAssistant();
16 
17 private:
18     QProcess *proc;
19 };
20 
21 #endif // ASSISTANT_H

View Code

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

 1 #include <QtCore/QByteArray>
 2 #include <QtCore/QProcess>
 3 #include <QtWidgets/QMessageBox>
 4 #include "assistant.h"
 5 
 6 Assistant::Assistant(): proc(0)
 7 {
 8 }
 9 
10 Assistant::~Assistant()
11 {
12    if (proc && proc->state() == QProcess::Running)
13    {
14        // 试图终止进程
15        proc->terminate();
16        proc->waitForFinished(3000);
17    }
18    // 销毁proc
19    delete proc;
20 }
21 
22 // 显示文档
23 void Assistant::showDocumentation(const QString &page)
24 {
25    if (!startAssistant())
26        return;
27 
28    QByteArray ba("SetSource ");
29    ba.append("qthelp://bookmisClient.myhelp/doc/");
30    proc->write(ba + page.toLocal8Bit() + '\n');
31 }
32 
33 // 启动Qt Assistant
34 bool Assistant::startAssistant()
35 {
36    // 若是没有建立进程，则新建立一个
37    if (!proc)
38        proc = new QProcess();
39    // 若是进程没有运行，则运行assistant，并添加参数
40    if (proc->state() != QProcess::Running)
41    {
42        QString app = QLatin1String("../MyHelpThis/documentation/assistant.exe");
43        QStringList args;
44        args << QLatin1String("-collectionFile")
45             << QLatin1String("../MyHelpThis/documentation/myhelp.qhc");
46        proc->start(app, args); // 至关于执行命令：assistant –collectionFile myHelp.qhc
47        if (!proc->waitForStarted())
48        {
49             QMessageBox::critical(0, QObject::tr("my help"),
50                 QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
51             return false;
52        }
53    }
54    return true;
55 }

View Code

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

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

 1 #include "mainwindow.h"
 2 #include "ui_mainwindow.h"
 3 #include "assistant.h"
 4 
 5 MainWindow::MainWindow(QWidget *parent)
 6     : QMainWindow(parent)
 7     , ui(new Ui::MainWindow)
 8     , pAssistant(nullptr)
 9 {
10     ui->setupUi(this);
11     // 建立命令按钮
12     QAction* pHelp = new QAction("help", this);
13     ui->mainToolBar->addAction(pHelp);
14     // 绑定信号与槽
15     connect(pHelp, SIGNAL(triggered()), this, SLOT(startAssistant()));
16     // 建立Assistant对象
17     pAssistant = new Assistant;
18 }
19 
20 MainWindow::~MainWindow()
21 {
22     delete ui;
23     delete pAssistant;
24 }
25 
26 void MainWindow::startAssistant()
27 {
28     // 按下“help”按钮，运行Qt Assistant，显示index.html页面
29     pAssistant->showDocumentation("index.html");
30 }

View Code

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

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

工程文件目录：

documentation文件夹目录：

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

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

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

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

1 echo off
2 echo Setting up environment for Qt usage...
3 set PATH=C:\Qt\Qt5.3.2\5.3\msvc2010_opengl\bin;%PATH%
4 cd /D C:\Qt\Qt5.3.2\5.3\msvc2010_opengl
5 cd /D F:\qtHelpDemoDoc\MyHelpThis\documentation
6 qhelpgenerator myhelp.qhp -o myhelp.qch
7 qcollectiongenerator myhelp.qhcp -o myhelp.qhc
8 assistant -collectionFile myhelp.qhc
9 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.

顺序选择循环总结