We have already briefly understood the Qt help framework. In this section, we will give an example to generate the Qt help set and customize the Qt Assistant.
Preparation
Because the premise of creating a help system to create a help file is that the HTML document file already exists, so let's get some simple HTML documents (I don't know how to do it).
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>首页</title>
</head>
<body>
<div class="brief-introduction">
<p>欢迎来到啥也不是</p>
</div>
</body>
</html>
section1.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>第一节</title>
</head>
<body>
<div class="section 1">
<div class="header">
<p>第一节，学完啥也不是</p>
</div>
<div class="info">
<p>啥也不是书里面写的就是啥也不是</p>
</div>
<div class="summary">
<p>
没啥可总结，啥也不是就是啥也不是。
</p>
</div>
</div>
</body>
</html>
section2.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>第二节</title>
</head>
<body>
<div class="section 2">
<div class="header">
<p>第二节，学完啥也不是</p>
</div>
<div class="info">
<p>啥也不是书里面写的就是啥也不是</p>
</div>
<div class="summary">
<p>
没啥可总结，啥也不是就是啥也不是。
</p>
</div>
</div>
</body>
</html>
section3.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>第三节</title>
</head>
<body>
<div class="section 3">
<div class="header">
<p>第三节，学完啥也不是</p>
</div>
<div class="info">
<p>啥也不是书里面写的就是啥也不是</p>
</div>
<div class="summary">
<p>
没啥可总结，啥也不是就是啥也不是。
</p>
</div>
</div>
</body>
</html>
Create related files
Create a Qt Help project file (.qhp)
bmhelp.qhp
<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>bmseven.myHelp</namespace>
<virtualFolder>doc</virtualFolder>
<filterSection>
<toc>
<section title="主页" ref="index.html">
<section title="第一节" ref="section1.html">
</section>
<section title="第二节" ref="section2.html">
</section>
<section title="第三节" ref="section3.html">
</section>
</section>
</toc>
<keywords>
<keyword name="section1" ref="section1.html" />
<keyword name="section2" ref="section2.html" />
<keyword name="section3" ref="section3.html" />
</keywords>
<files>
<file>index.html</file>
<file>section1.html</file>
<file>section2.html</file>
<file>section3.html</file>
</files>
</filterSection>
</QtHelpProject>
Label description:
- namespace: refers to the namespace of the qhp file, and must be unique. This namespace will be used as the first part of the page URL in the Assistant.
- virtualFolder: Refers to the virtual folder, this folder does not need to be created, it is only used to distinguish files.
- filterSection: Refers to the filter. The filter section contains all directories, indexes and file lists. You can specify whether the document is displayed in the Assistant by setting the filter attribute.
- toc: Refers to the table of contents (table of contents), in which the directories, titles, and paths corresponding to all documents are created.
- keywords: Used to specify all search keywords and specified files. When searching in Assistant, the corresponding page will be displayed.
- files: Contains all files and pictures that the Assistant needs to reference, and wildcard * can be used for matching.
Generate Qt compressed help (.qch)
Execute through the Qt console:
qhelpgenerator bmhelp.qhp -o bmhelp.qch
After the qch file is generated, it needs to be registered before it can be displayed in the Assistant. Generally, there are two ways:
- Qt terminal execution: assistant -register bmhelp.qch
- Use the Assistant interface to add: Edit->Preferences->Documents->Add->Apply
Note: In fact, at this point, we can view the help documents we created ourselves in Qt Assistant, but it includes qt help documents, so how to only display our own documents and customize Qt Assistant? Let's go down~
Create a Qt help collection project file (.qhcp)
bmhelp.qhcp
<?xml version="1.0" encoding="utf-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
<title>bmseven的帮助系统</title>
<applicationIcon>images/awesomeface.png</applicationIcon>
<cacheDirectory>cache/bmhelp</cacheDirectory>
<homePage>qthelp://bmseven.bmhelp/doc/index.html</homePage>
<startPage>qthelp://bmseven.bmhelp/doc/index.html</startPage>
<aboutMenuText>
<text>关于该帮助</text>
</aboutMenuText>
<aboutDialog>
<file>about.txt</file>
<icon>images/awesomeface.png</icon>
</aboutDialog>
<enableDocumentationManager>false</enableDocumentationManager>
<enableAddressBar>false</enableAddressBar>
<enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>
<docFiles>
<generate>
<file>
<input>bmhelp.qhp</input>
<output>bmhelp.qch</output>
</file>
</generate>
<register>
<file>bmhelp.qch</file>
</register>
</docFiles>
</QHelpCollectionProject>
Label description:
- assistant: Perform some customized operations on Qt Assistant, including appearance and functions, such as title, icon, cache directory, home page, start page, about menu text/dialog content/icon.
- cacheDirectory: Cache directory, which will generate cache files when performing full-text search in Qt Assistant.
- homePage/startPage: The home page/start page of Qt Assistant, the format of the URL used here is:
qthelp://namespace(qhp文件中指定的)/doc(qhp文件中指定的虚拟文件夹)/*html
- aboutMenuText/aboutDialog: including menu text, help dialog display content, icons and other information.
- docFIles: Document conversion and registration. (That is, the previous command line operations are integrated into this file)
Generate Qt help set (.qhc)
Qt console executes:
qhelpgenerator bmhelp.qhcp -o bmhelp.qhc
Run custom Qt Assistant
Qt console executes:
assistant -collectionFile bmhelp.qhc
This is the end of the matter, and the customized parts have changed accordingly. When you need to embed it into your own application, you can use the code to call it, so I won’t introduce it here.