环境: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文件并编写其内容如下
<?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文件后需重新生成qhp文件才会更新。
生成qhp文件
qhelpgenerator help.qhp -o help.qch
2、测试(不是必需用于验证)
注册
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文件并编写其内容如下
<?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
2、测试(不是必需用于验证)
注册
assistant -collectionFile help.qhc
显示
assistant
四、整合到程序中
创建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);
}
参考: