Qt的Assistant制作自定义的软件帮助界面(记录)

      首先，需要编写好需要展示的html文档，作为Assistant显示的帮助文档，未提高效率，选择用VSCode配合Live server插件，编写html文档。（VSCode配合Live Server真好用~_~）

                                    

目录结构如下所示：

 CSS目录中存放html文件的css样式，Documents存放html文档，pictures存放html中引用的图片：

book1.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
    <link rel="stylesheet" href="../CSS/book1.css">
</head>
<body>
    <div class="outer">
        <div class="header-area">
            <div class="picture-area">
                <img src="../pictures/book1.jpg" alt="">
            </div>
            <div class="book-name">
                <p>红岩</p>
            </div>
        </div>
        <div class="info-table">
            <table border="1" cellspacing="3" cellpading="5">
                <caption>书籍.红岩</caption>
                <thead>
                    <tr align="center" valign="center">
                        <th>书名</th>
                        <th>作者</th>
                        <th>出版时间</th>
                        <th>价格</th>
                        <th>好评度</th>
                    </tr>
                </thead>
               <tbody>
                   <tr align="center" valign="center">
                        <td>Hongyan</td>
                        <td>Lisan</td>
                        <td>1994.6.6</td>
                        <td>￥10</td>
                        <td>90%</td>
                   </tr>
                   <tr align="center" valign="center">
                        <td>红岩</td>
                        <td>张三</td>
                        <td>1994年</td>
                        <td>$6</td>
                        <td>94%</td>
                   </tr>
               </tbody>
            </table>
        </div>
        <div class="summary-area">
            <p>
                文字是人类用符号记录表达信息以传之久远的方式和工具。现代文字大多是记录语言的工具。
                人类往往先有口头的语言后产生书面文字，很多小语种，有语言但没有文字。文字的不同体现了国家和民族的书面表达的方式和思维不同。
                文字使人类进入有历史记录的文明社会。
            </p>
        </div>
    </div>
</body>
</html>

 简单的样式book1.css

div.summary-area
{
    width: 40%;
    height: 120px;
    background-color: antiquewhite;
    align-content: center;
}
 
div.summary-area p
{
    font-size: 15px;
}
 
div.outer
{
    width: 65%;
    margin-top: 40px;
}
 
div.header-area
{
    margin-left: 35px;
    line-height: 65px;
    display: flex;
}
 
div.book-name
{
    vertical-align: center;
    line-height: 65px;
}
 
div.book-name p 
{
    font-weight: bold;
    font-size: 20px;
}
 
div.info-table table
{
    margin-left: 25px;
}

           按照重复的样式新建5个相同的html文件，后期为突出目录结构使用，同时，新建一个简单的index.html作为首页使用:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>首页</title>
    <link rel="stylesheet" href="../CSS/index.css">
</head>
<body>
    <div class="outer">
        <div class="img-area">
            <img src="../pictures/index.jpg" alt="">
        </div>
 
        <div class="text-area">
            <p>Welcome to the homepage</p>
        </div>
    </div>
</body>
</html>

index.css样式文件：

div.img-area img
{
    height: 150px;
    width: 165px;
    margin-left: 26px;
}
 
div.outer
{
    margin-top: 30px;
    margin-left: 50px;
}
 
div.text-area
{
    margin-top: 10px;
    height: 40px;
}
 
div.text-area p
{
    line-height: 40px;
    font-weight: bold;
}

在编写好基本的html文件之后，需要进行Qt Assistant的相关文件的编写。

其中需要编写两个重要的文件，分别是.qhp文件以及.qhcp文件，分别介绍这两个文件的作用：

1. qhp文件，qhp指Qt Help Project的缩写，格式为xml格式（注意在编写xml文件的时候，一定要保持文件的格式正确），其主要的作用是负责组织Assistant中       需要用到的文档(即前面编写的html文件)，其格式如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
	<namespace>ApplicationHelp</namespace>
	<virtualFolder>doc</virtualFolder>
	<filterSection>
		<toc>
			<section title="Simple Application Help" ref="Documents/index.html">
				<section title="第一章 介绍">
					<section title="Book1 Detail" ref="Documents/book1.html"/>
					<section title="Book2 Detail" ref="Documents/book2.html"/>
				</section>
				<section title="第二章 书籍">
					<section title="Book3 Apply" ref="Documents/book3.html"/>
					<section title="book4 Apply" ref="Documents/book4.html"/>
				</section>
				<section title="第三章 应用">
					<section title="Book5" ref="Documents/book5.html"/>
					<section title="Book4" ref="Documents/book4.html"/>
				</section>
			</section>
		</toc>
		<keywords>
			<keyword name="index" ref="Documents/index.html"/>
			<keyword name="book1" ref="Documents/book1.html"/>
			<keyword name="book2" ref="Documents/book2.html"/>
			<keyword name="book3" ref="Documents/book3.html"/>
			<keyword name="book4" ref="Documents/book4.html"/>
			<keyword name="book5" ref="Documents/book5.html"/>
		</keywords>
		<files>
			<file>Documents/*.html</file>
			<file>CSS/*.css</file>
			<file>pictures/*.jpg</file>
		</files>
	</filterSection>
</QtHelpProject>

（1）encoding指编码，如果需要使用中文，需指定为GB2312，如果只有英文，可指定为UTF-8格式的编码。

（2）namespace指qhp文件的命名空间，qhp文件的命名空间必须是唯一的，这个命名空间在Assistant中会作为页面URL的第一部分。

（3）virtualFolder指定虚拟文件夹，此文件夹并不需要创建，只用来区分文件。

（4）filterSection指过滤器。过滤器部分包含了所有的目录，索引和文件列表，可以通过设置过滤器属性，实现在Assistant中指定文档是否显示。

（5）toc指 table of contents,表示目录表，在toc中创建了所有文档的目录，标题，以及文档对应的路径。

（6）keywords用于指定所有搜索的关键字以及指定的文件。在Assistant中进行搜索的时候，会显示相应的页面。

（7）files中包含了Assistant需要引用的所有的文件，图片，可使用通配符来表示。

在编写好qhp文件之后，需要对qhp文件转化为qch文件，才能被Assistant识别。qch是指Qt Compressed Help，为二进制格式的文件，是Assistant能够识别的最小单元。可通过命令

 qhelpgenerator src.qhp -o dest.qch

来生成qch文件，在生成qch文件之后，需要进行注册才能够在Assistant中进行文档的浏览。注册的方法有两种：

第一种：命令行方法 assistant -register dest.qch来进行注册。

第二种：在Assistant中，编辑-->首选项-->文档标签页-->添加/移除

通过上述方法，已经能够在Assistant中显示已经注册的文档。

如果需要在Assistant中仅仅显示我们自己编写的文档，则需要进行一些定制化的操作。

如果需要定制客户化的Assistant,则需要编写qhcp文件，qhcp指Qt help collect project的缩写，文件的格式是xml文档，起主要作用是将二进制文件qch组织成一个collect.

qhcp文件的格式如下所示：

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
	<assistant>
		<title>Application Help</title>
		<startPage>qthelp://ApplicationHelp/doc/Documents/index.html</startPage>
		<homePage>qthelp://ApplicationHelp/doc/Documents/index.html</homePage>
		<applicationIcon>pictures/icon.jpg</applicationIcon>
		<enableFilterFunctionality>false</enableFilterFunctionality>
		<enableDocumentationManager>false</enableDocumentationManager>
		<enableAddressBar visible="true">true</enableAddressBar>
		<cacheDirectory>cache/data</cacheDirectory>
		<aboutMenuText>
			<text>About</text>
		</aboutMenuText>
		<aboutDialog>
			<file>Documents/about.txt</file>
			<icon>pictures/about.jpg</icon>
		</aboutDialog>
	</assistant>
	<docFiles>
		<generate>
			<file>
				<input>ApplicationInst.qhp</input>
				<output>ApplicationInst.qch</output>
			</file>
		</generate>
		<register>
			<file>ApplicationInst.qch</file>
		</register>
	</docFiles>
</QHelpCollectionProject>

(1)assistant标签中的内容是对Assistant进行一些定制化的操作，包括外观与功能，如标题，图标，缓存目录，主页，起始页，about菜单文本/对话框内容/图标。

(2)cacheDirectory表示缓存目录，在Assistant中进行全文检索时会将缓存文件放在指定的缓存目录中。

(3) startPage/homePage分别是设置Assistant的起始页和home页，这里用到Assistant页面的URL，URL的构成格式为:

qthelp://namespace(qhp文件中指定的)/doc(qhp文件中指定的虚拟文件夹)/*html

（4）Assistant可以添加或者删除文档来为多个应用程序提供帮助文档，主要依赖靠文档管理器document mamager,地址栏adress bar, 过滤器filter functionality来实现，这些功能暂时用不到，因此先关闭。

（5）About用于设置跟“关于”菜单以及对话框相关的内容，包括菜单文本，帮助对话框显示内容，图标等信息。

（6）docFiles完成文件的转换以及注册功能。

编写好qhcp文件之后，通过qcollectgenerator将qhcp文件转化为qhc文件，qhcp文件也为二进制文件，在启动assistant的时候，需要指定当前的qch文件，实现文档的注册。

在Qt中通过代码方式调用Assistant:

void ICMainWindow::slotShowInstructionBook()
{
	// 此处自定义一个说明文档，借助Qt中的assistant
	if (!m_processor)
	{
		m_processor = new QProcess();
	}
 
#ifdef WIN32
	// windows版本
	QString appDir = QCoreApplication::applicationDirPath();
	appDir.replace("\\", "/");
	appDir = appDir.left(appDir.indexOf("x64/Debug"));
	appDir = appDir.endsWith("/") ? appDir : appDir.append("/");
 
	QString cmd = appDir + "QtApp/qcollectiongenerator.exe";
 
	QStringList args;
	args << appDir + "doc/ApplicationInst.qhcp";
 
	if (m_processor->state() == QProcess::Running)
	{
		m_processor->waitForFinished();
	}
 
	m_processor->start(cmd, args);
	m_processor->waitForFinished();
 
	QString cmdAssistant = appDir + "QtApp/assistant.exe";
	args.clear();
 
	QString docPath = appDir + "doc/ApplicationInst.qhc";
	QFile docfile(docPath);
	if (!docfile.exists())
		return;
 
	QString url("qthelp://ApplicationHelp/doc/Documents/index.html");
 
	args << "-enableRemoteControl"; 
	args << "-collectionFile";
	args << docPath;
	args << "-showUrl";
	args << url;
	//args << "-hide" << "search";
	//args << "-hide" << "bookmarks";
 
	if (m_processor->state() == QProcess::Running)
	{
		QMessageBox::warning(this, tr("Warning"), tr("The Process is running, please wait for finished"));
		return;
	}
 
	m_processor->start(cmdAssistant, args);
	
	if (!m_processor->waitForStarted(5000))
	{
		return;
	}
	
#elif
	// linux版本
#endif
	
}

调用效果如下所示：

posted @   Alpha205  阅读(341)  评论(3)  编辑  收藏  举报
相关博文：
· c++日志库-log4cplus
· CMAKE学习记录
· 【QCustomPlot】配置帮助文档
· Qt-Creator-应用开发（全）
· 在Qt Creator中添加cmake的帮助文档
阅读排行：
· 全程不用写代码，我用AI程序员写了一个飞机大战
· DeepSeek 开源周回顾「GitHub 热点速览」
· 记一次.NET内存居高不下排查解决与启示
· 物流快递公司核心技术能力-地址解析分单基础技术分享
· .NET10 - 预览版1新功能体验（一）
点击右上角即可分享
微信分享提示
AI FOR CODE 大赛