Qt学习——利用Qt Assistant 定制帮助文档

环境：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文件

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文件并编写其内容如下

  software.help
  doc
  
    
        

			

            

            

        
    
    
        
        
    
    
      htmlDocument/*.html
      imageDocument/*.jpg
	  imageDocument/*.png
    
  

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

2、测试（不是必需用于验证，第三步中生成qhc文件时会一并生成qch文件）

生成qch文件 

qhelpgenerator help.qhp -o help.qch

 

注册

assistant -register help.qch

显示

assistant

 

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

1、文件建立

qhcp文件

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

qhc文件

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

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

  
  imageDocument/robot.png
  cache/help
  qthelp://software.help/doc/htmlDocument/index.html
  qthelp://software.help/doc/htmlDocument/index.html
  
    关于
  
  
    about.txt
    imageDocument/robot.png
  
  false
  false
  false


  
    
      help.qhp
      
help.qch
    
  
  
    help.qch
  

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

生成qhc文件 

qcollectiongenerator help.qhcp -o help.qhc

2、测试（不是必需用于验证）

注册并显示

assistant -collectionFile help.qhc

 

 

四、整合到程序中

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

assistant.h文件

#ifndef ASSISTANT_H
#define ASSISTANT_H

#include 

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 
#include 
#include 

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