利用Qt Assistant 定制帮助文档

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

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

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

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

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

(4)添加HTML文件。在documentation文件夹中再新建一个“demoHtml”文件夹,将从步骤(1)生成的HTML文件拷贝至其中。此例中放入已经存在的7个HTML文件。

二、创建.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++工具打开文件,编辑内容如下:

 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文件是否正确可用。另外,想象一下,生成一个帮助文档还追随在别人下面多俗呀~~~如果您仅仅为了想验证一下可行性,也可到此为止。否则,请再继续看下面内容。

三、创建.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,是进行全文检索等操作时缓存文件要存放的位置。

  ④ 第七、八行主页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文件的文本内容,效果如下图所示:

  

四、从程序中启动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按钮,就可以启动并查看帮助文档了。

五、利用批处理启动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按钮同样的效果图。

六、实现过程中可能遇到的问题

(1)在qhp文件中,设置ref错误,导致跳转不符合预期。

(2)在qhp文件中,设置html文件路径错误,导致无法正常显示相应内容。

 

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

posted @ 2015-12-17 21:37  kaizenly  阅读(12498)  评论(20编辑  收藏  举报
打赏