第47篇 进阶（七） 定制Qt帮助系统

第47章 进阶（七）自定义Qt帮助系统介绍

一个完整的应用程序应该提供尽可能多的帮助信息。 在Qt中，可以使用工具提示、状态提示、“这是什么”等简单的帮助提示，还可以提供强大的在线帮助。 如果要介绍详细的功能和使用方法，仅仅使用这些提示信息是不够的，所以需要提供HTML格式的帮助文本。 在程序中，可以通过调用Web浏览器或使用.html文件来管理和应用这些HTML文件。 不过Qt提供了一个更强大的工具，那就是Qt，它支持索引和全文检索，可以同时为多个应用程序提供帮助。 我们可以通过定制Qt来实现一个强大的在线帮助系统。

为了将Qt定制为我们自己应用程序的帮助浏览器，我们首先需要做一些准备工作，主要是生成一些文件，最后在程序中启动Qt。 主要步骤如下：

环境：Xp+Qt 4.8.5+.8.0

内容文字

1. 创建HTML格式的帮助文档

1、新建一个Qt Gui应用程序，项目名称为 ，类名称为 ，基类保持不变。

2.然后可以用Word等各种编辑器编辑要使用的文档，最后保存为HTML格式的文件。 例如，我们在这里创建了 5 个 HTML 文件。 然后在项目目录下新建一个文件夹，命名，并将这些HTML文件放入其中。 然后在文件夹中新建一个文件夹，将一张图标图片复制进去，作为以后Qt的图标使用。 例如，这里使用.png图片。

2. 创建.qhp文件

首先在文件夹中创建一个文本文件，然后进行编辑，最后保存为.qhp，注意后缀为.qhp。 文件内容如下：

xml version="1.0"encoding="GB2312"?>
<QtHelpProjectversion="1.0">
<namespace>yafeilinux.myHelpnamespace>
<virtualFolder>docvirtualFolder>
<filterSection>
   <toc>
     <section title="我的帮助"ref="./index.html">
       <section title="关于我们"ref="./aboutUs.html">
         <section title="关于yafeilinux"ref="./about_yafeilinux.html">section>
         <section title="关于Qt Creator系列教程" ref="./about_QtCreator.html">section>
       section>
       <section title="加入我们"ref="./joinUs.html">section>
     section>
   toc>
   <keywords>
     <keyword name="关于"ref="./aboutUs.html"/>
     <keyword name="yafeilinux" ref="./about_yafeilinux.html"/>
     <keyword name="Qt Creator"ref="./about_QtCreator.html"/>
   keywords>
   <files>
     <file>about_QtCreator.htmlfile>
     <file>aboutUs.htmlfile>
     <file>about_yafeilinux.htmlfile>
     <file>index.htmlfile>
     <file>joinUs.htmlfile>
     <file>images/*.pngfile>
   files>
filterSection>
QtHelpProject>

此 .qhp 文件采用 XML 格式。 XML格式不是这里介绍的重点。 我们主要讲解一下内容。 如果您想了解有关XML格式的知识，可以参考这里。 第一行是XML前导码，其中指定编码以便可以使用中文。 如果只想使用英文，编码一般为UTF-8； 第二行指定版本为1.0； 第三行指定名称Space，每个.qhp文件的命名空间必须是唯一的，命名空间将成为Qt中页面URL的第一部分，在后面的内容中会涉及到； 第四行指定一个虚拟文件夹，这个文件夹不需要创建，仅用于区分文件； 选项卡下方的过滤器部分包含所有文档文件的目录、索引和列表。 过滤器部分可以设置过滤器属性，这样以后就可以通过Qt中的过滤器来设置文档的显示了。 不过，因为我们这里只有一份文档，所以不需要Qt的过滤功能，所以这里就不用设置了。 过滤属性； 所有HTML文件的目录都在目录的toc（table）标签中创建，并指定它们的标题和相应的路径。 这里设置的目录是：

加入我们

然后是标签，指定所有索引的关键字和对应的文件，这些文件将显示在Qt索引页上； 所有文件都列在文件标签中，包括图像文件。

3.生成.qch文件

这里为了测试创建的文件是否可用，可以先生成一个.qch文件，然后将其注册到.qch文件中。 这样运行就会看到我们添加的文档。 然而，该步骤不是必需的。 我们打开命令行控制台，然后使用cd命令跳转到项目目录的目录下，输入以下命令并回车：

qhelpgeneratormyHelp.qhp –o myHelp.qch
assistant –registermyHelp.qch

要保证命令能够正常运行，前提是Qt安装目录的bin目录的路径已经添加到系统的PATH环境变量中。 运行命令的结果如下图所示。

注册成功后，会显示“完全”提示对话框。 这时，在开始菜单中启动Qt（或者直接在命令行输入启动Qt），就可以发现我们的HTML文档已经出现了，如下图所示。

4. 创建.qhcp文件

让Qt只显示我们自己的帮助文件的最简单方法是生成一个帮助集合文件，即.qhc文件。 要生成 .qhc 文件，请首先创建 .qhcp 文件。 在文件夹中新建一个文本文档，进行编辑，最后保存为.qhcp，注意后缀为.qhcp。 这里同样创建一个名为about.txt的文本文件，并在其中输入帮助的一些描述信息，作为about菜单的显示内容。 .qhcp文件内容如下：

xml version="1.0"encoding="GB2312"?>
<QHelpCollectionProjectversion="1.0">
<assistant>
<title>我的帮助系统title>
<applicationIcon>images/yafeilinux.pngapplicationIcon>
<cacheDirectory>cache/myHelpcacheDirectory>
<homePage>qthelp://yafeilinux.myHelp/doc/index.htmlhomePage>
<startPage>qthelp://yafeilinux.myHelp/doc/index.htmlstartPage>
<aboutMenuText>
   <text>关于该帮助text>
aboutMenuText>
<aboutDialog>
   <file>./about.txtfile>
   <icon>images/yafeilinux.pngicon>
aboutDialog>
<enabledocumentationManager>falseenabledocumentationManager>
<enableAddressBar>falseenableAddressBar>
<enableFilterFunctionality>falseenableFilterFunctionality>
assistant>
<docFiles>
<generate>
   <file>
     <input>myHelp.qhpinput>
     <output>myHelp.qchoutput>
   file>
generate>
<register>
   <file>myHelp.qchfile>
register>
docFiles>
QHelpCollectionProject>

标签中是Qt的外观和功能的定制，设置了标题、图标、缓存目录、主页、起始页、about菜单文本、对话框的内容和图标等，同时还关闭了一些无用的功能 。 对于缓存目录来说，就是进行全文检索等操作时，缓存文件存放的位置。 对于主页和起始页，这里使用第二步中提到的Qt页面的URL。 该URL以://开头，然后是.qhp文件中设置的命名空间，然后是虚拟文件夹，最后是特定的HTML文件名。 因为Qt可以添加或删除文档来帮助多个应用程序，但这里只是帮助一个应用程序，而我们不想删除我们的文档，所以文档管理器被禁用； 由于这里设置的文档很小，并且只有一个过滤部分，所以地址栏栏和过滤功能也被关闭。

在上面的第三步中，我们已经生成了.qch文件并将其注册到Qt中，但这只是为了测试该文件是否可用。 其实第三步完全可以跳过，因为第三步是在这里的标签中完成的。 步骤操作。 不过与第三步不同的是，第三步是注册在默认的集合文件中，而这里是注册在我们自己的集合文件中。

5.生成.qhc文件

在命令行中输入以下命令：

qcollectiongenerator myHelp.qhcp –omyHelp.qhc

输出结果如下图所示。

为了测试我们的自定义，您可以输入以下命令：

assistant –collectionFile myHelp.qhc

这里我们在运行Qt时指定集合文件为我们自己的.qhc文件，这样运行后只会显示我们自己的HTML文档。 可以看到当前的图标也发生了变化。 打开“帮助”菜单中的“关于此帮助”菜单，这里是之前添加的about.txt文件的内容，效果如下图所示。

6.在程序中启动Qt

这里我们首先要把Qt安装目录的bin目录下的.exe程序复制到我们项目目录的目录下。 为了启动 Qt，必须首先创建一个类。 首先在项目中添加一个新文件，模板选择C++ Class，选择类名，基类留空，类型信息选择None。 然后按如下方式更改.h文件：

#ifndef ASSISTANT_H
#define ASSISTANT_H
#include 
class QProcess;
class Assistant
{
public:
    Assistant();
    ~Assistant();
    void showdocumentation(const QString &file);
private:
    bool startAssistant();
    QProcess *proc;
};
#endif // ASSISTANT_H

类中，该类主要用来创建启动Qt的进程。 这是 .cpp 文件的内容：

#include 
#include 
#include 
#include "assistant.h"
Assistant::Assistant()
   : proc(0)
{
}
Assistant::~Assistant()
{
   if (proc && proc->state() == QProcess::Running) {
       // 试图终止进程
       proc->terminate();
       proc->waitForFinished(3000);
   }
   // 销毁proc
   delete proc;
}
// 显示文档
void Assistant::showdocumentation(const QString &page)
{
   if (!startAssistant())
       return;
   QByteArray ba("SetSource ");
   ba.append("qthelp://yafeilinux.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("../myWhatsThis/documentation/assistant.exe");
       QStringList args;
       args << QLatin1String("-collectionFile")
            << QLatin1String("../myWhatsThis/documentation/myHelp.qhc");
       proc->start(app, args);
       if (!proc->waitForStarted()) {
            QMessageBox::critical(0, QObject::tr("my help"),
                QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
            return false;
       }
   }
   return true;
}

在()函数中，创建了一个进程来启动Qt。 这里，命令行参数用于使用帮助集合文件。 .exe 和 .qhc 都使用相对地址； 在()函数中，可以指定特定的页面作为参数，使Qt显示指定的页面； 在析构函数中，如果进程仍在运行，则终止进程，最后销毁进程指针。

让我们使用该类来启动 Qt。 首先向 .h 文件添加前向声明：

class Assistant;

然后添加对象指针声明：

Assistant *assistant;

然后添加一个私有槽：

private slots:
    void startAssistant();

现在转到 .cpp 文件并进行更改。 添加头文件包含#“.h”，然后在构造函数中添加以下代码：

QAction *help = new QAction("help",this);
ui->mainToolBar->addAction(help);
connect(help, SIGNAL(triggered()), this, SLOT(startAssistant()));
// 创建Assistant对象
assistant = new Assistant;

这里创建了一个“帮助”操作并将其添加到工具栏，可以通过该操作启动工具栏。 以下是 () 槽的定义：

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

最后在析构函数中销毁指针，即在::~()函数中添加如下代码：

// 销毁assistant
delete assistant;

现在运行程序并按工具栏上的“帮助”操作来启动 Qt。 这里也提醒一下，如果要发布程序，需要将目录复制到目录下，然后运行程序。

结语

使用Qt自定义帮助系统，可以创建功能强大的上下文相关帮助文档，而对于一款优秀的软件来说，帮助菜单是必须的。

涉及的代码