Qt学习——利用Qt Assistant 定制帮助文档_制作qt assitant文件

环境：windows10+Qt 5.10.1

一、概述

Qt可以通过Qt Assistant为自己的应用程序编制帮助文档，文件目录架构如下：

helpdocument
│  about.txt //说明
│  assistant.exe 
│  help.qch // .qhp生成
│  help.qhc //  .qhcp生成
│  help.qhcp// 帮助文档窗口界面描述
│  help.qhp // 帮助文档描述
│
├─htmlDocument //帮助文档，请注意html文档格式
│      about.html
│      error.html
│      function.html
│      index.html
│
└─imageDocument //文档图片
        icon.jpg
        robot.png

 

二、创建.qhp文件并生成.qch文件

2.1 文件建立

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界面中浏览帮助文档。

创建help.qhp文件并编写其内容如下

<?xml version="1.0" encoding="GB2312"?>
<QtHelpProject version="1.0">
  <namespace>software.help</namespace>
  <virtualFolder>doc</virtualFolder>
  <filterSection>
    <toc>
        <section title="首页" ref="htmlDocument/index.html">
			<section title="功能" ref="htmlDocument/function.html"></section>
            <section title="错误" ref="htmlDocument/error.html"></section>
            <section title="关于" ref="htmlDocument/about.html"></section>
        </section>
    </toc>
    <keywords>
        <keyword name = "功能" ref="htmlDocument/function.html"></keyword>
        <keyword name = "错误" ref="htmlDocument/error.html"></keyword>
    </keywords>
    <files>
      <file>htmlDocument/*.html</file>
      <file>imageDocument/*.jpg</file>
	  <file>imageDocument/*.png</file>
    </files>
  </filterSection>
</QtHelpProject>

提示：注意html文件路径及保存编码，否则会出现无法找到文件或者显示乱码的问题，修改html文件后需重新生成qch文件才会更新。

2.2 测试

不是必需用于验证，第三步中生成qhc文件时会一并生成qch文件

生成qch文件 

qhelpgenerator help.qhp -o help.qch

注册

assistant -register help.qch

显示

assistant

 

三、创建.qhcp文件并生成.qhc文件

3.1 文件建立

qhcp文件

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

qhc文件

由qhcp文件通过qcollectiongenerator命令生成的二进制文件，用于启动Assistant时获取指定collection参数。qhc文件中包含qch文件的集合，打开Assistant时，通过指定当前collection即可注册多个帮助文档。

创建help.qhcp文件并编写其内容如下

<?xml version="1.0" encoding="GB2312"?>
<QHelpCollectionProject version="1.0">
<assistant>
  <title>帮助文档</title>
  <applicationIcon>imageDocument/robot.png</applicationIcon>
  <cacheDirectory>cache/help</cacheDirectory>
  <homePage>qthelp://software.help/doc/htmlDocument/index.html</homePage>
  <startPage>qthelp://software.help/doc/htmlDocument/index.html</startPage>
  <aboutMenuText>
    <text>关于</text>
  </aboutMenuText>
  <aboutDialog>
    <file>about.txt</file>
    <icon>imageDocument/robot.png</icon>
  </aboutDialog>
  <enableDocumentationManager>false</enableDocumentationManager>
  <enableAddressBar>false</enableAddressBar>
  <enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>
<docFiles>
  <generate>
    <file>
      <input>help.qhp</input>
      <output>help.qch</output>
    </file>
  </generate>
  <register>
    <file>help.qch</file>
  </register>
</docFiles>
</QHelpCollectionProject>

提示：注意html文件路径及保存编码，否则会出现无法找到文件或者显示乱码的问题，修改html文件后需重新生成qhc文件才会更新。

生成qhc文件 

qcollectiongenerator help.qhcp -o help.qhc

3.2 测试

不是必需用于验证

注册并显示

assistant -collectionFile help.qhc

 

四、整合到程序中

创建C++ class类，命名为assistant。这里用到QProcess类，它是一个用来启动外部程序并与之通信的Qt类。

assistant.h文件

#ifndef ASSISTANT_H
#define ASSISTANT_H
 
#include <QtCore/QString>
 
class QProcess;
class assistant
{
public:
    assistant();
    ~assistant();
    void showDocumentation(const QString &file);
    bool startAssistant();
 
private:
    QProcess *proc;
};
 
#endif // ASSISTANT_H

assistant.cpp文件

#include "assistant.h"
#include <QtCore/QByteArray>
#include <QtCore/QProcess>
#include <QtWidgets/QMessageBox>
 
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://software.help/doc/htmlDocument/");
   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("../software/helpdocument/assistant.exe");
       QStringList args;
       args << QLatin1String("-collectionFile")
            << QLatin1String("../software/helpdocument/help.qhc");
       proc->start(app, args); // 相当于执行命令：assistant –collectionFile myHelp.qhc
       if (!proc->waitForStarted())
       {
            QMessageBox::critical(0, QObject::tr("help"),
                QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
            return false;
       }
   }
   return true;
}

打开帮助文档

assistant *pAssistant;
 
void MainWindow::on_helpButton_clicked()
{
    //创建帮助文档
    pAssistant = new assistant;
    if(pAssistant->startAssistant())
        pAssistant->showDocumentation("index.html");
    else
        QMessageBox::warning(this, tr("警告"), tr("无法打开帮助文档"), QMessageBox::Abort);
 
}

 

参考

https://www.cnblogs.com/Braveliu/p/5055387.html

https://doc.qt.io/archives/qt-4.8/assistant-custom-help-viewer.html