利用Qt Assistant 定製幫助文檔

時間 2019-11-09

標籤利用 assistant 定製幫助文檔简体版

原文原文鏈接

爲了將Qt Assistant定製爲本身應用程序的幫助文檔瀏覽器。須要完成如下幾步：html

1、導入HTML格式的幫助文檔瀏覽器

（1）首先，針對本身的應用程序建立HTML格式的幫助文檔，請參見《Doxygen生成HTML文件》。（下面示例假設HTML文件已經存在）緩存

（2）新建Gui應用。QtCreator-->new Project-->Qt Widgets Application 新建項目名稱定義爲「MyHelpThis」，類名定義爲「MainWindow」，基類保持QMainWindow不變。app

（3）在項目目錄中新建文件夾，命名爲「documentation」。在documentation文件夾中再新建一個「images」文件夾，往裏面拷貝一個圖標圖片，之後將做爲Assistant程序左上角的圖標，此例中使用了lib.png。ide

（4）在documentation文件夾中再新建一個「demoHtml」文件夾，將（1）生成的HTML文件拷貝至其中。此例中放入已經存在的7個HTML文件。工具

（5）其餘.....測試

2、建立.qhp文件，並利用命令生成.qch文件ui

（1）關於qhp與qchthis

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界面中瀏覽幫助文檔。

二者關係。qhp文件經過qhelpgenerator命令生成壓縮的qch文件。命令格式以下：

　　qhelpgenerator myhelp.qhp -o myhelp.qch

（2）建立qhp文件。在documentation文件夾中建立一個文本文件，命名爲「myhelp」，修改文件後綴爲qhp，用Notepad++工具打開文件，編輯內容以下：

 1 <?xml version="1.0" encoding="GB2312"?>
 2 <QtHelpProject version="1.0">
 3   <namespace>bookmisClient.myhelp</namespace>
 4   <virtualFolder>doc</virtualFolder>
 5   <filterSection>
 6     <toc>
 7         <section title="首頁" ref="./demoHtml/index.html">
 8             <section title="用戶登陸" ref="./demoHtml/userlogon.html"></section>
 9             <section title="書籍查詢" ref="./demoHtml/bookquery.html"></section>
10             <section title="續借書籍" ref="./demoHtml/Renewal.html"></section>
11             <section title="系統管理" ref="./demoHtml/systemmanage.html"></section>
12             <section title="日誌管理" ref="./demoHtml/log.html"></section>
13             <section title="關於" ref="./demoHtml/about.html"></section>
14         </section>
15     </toc>
16     <keywords>
17         <keyword name = "登陸" ref="./demoHtml/userlogon.html"></keyword>
18         <keyword name = "續借" ref="./demoHtml/Renewal.html"></keyword>
19         <keyword name = "日誌" ref="./demoHtml/log.html"></keyword>
20     </keywords>
21     <files>
22       <file>demoHtml/*.html</file>
23       <file>image/*.png</file>
24     </files>
25   </filterSection>
26 </QtHelpProject>

（3）解讀qhp文件。這個qhp文件是XML格式的。

　　①　第一行是XML序言，注意這裏指定encoding爲GB2312，這樣是爲了使用中文。若是隻想使用英文，那麼編碼通常爲UTF-8。

　　②　第二行指定了QtHelpProject版本爲1.0

　　③　第三行指定了命名空間namespace，每個qhp文件的命名空間都必須是惟一的，命名空間會成爲Qt Assistant中頁面的URL的第一部分。

　　④　第四行指定了一個虛擬文件夾virtualFolder，這個文件夾並不須要建立，它是指用來區分文件的。

　　⑤　過濾器。下面的過濾器部分filterSection標籤包含了目錄表、索引和全部文檔文件的列表。過濾器部分能夠設置過濾器屬性，這樣之後能夠在Qt Assistant中經過過濾器來設置文檔是否顯示，不過，由於此例只有一個文檔，因此不須要Qt Assistant的過濾器功能，這裏也就不須要設置過濾器屬性。

　　⑥　目錄表。toc（table of contents）標籤中建立了全部HTML文件的目錄，指定了它們的標題和對應的路徑，此例目錄表爲：

　　　　> 首頁

　　　　　　> 用戶登陸

　　　　　　> 書籍查詢

　　　　　　> 續借書籍

　　　　　　> 系統管理

　　　　　　> 日誌管理

　　　　　　> 關於

　　⑦　keywords標籤。指定了全部索引的關鍵字和對應的文件，這些關鍵字會顯示在Qt Assistant的索引頁面。

　　⑧　files標籤。Files標籤中列出了全部的文件，其中有HTML文件和圖片文件。注意：若是有許多的同類型文件，直接能夠寫爲：

<file>文件夾名稱/*.文件類型</file>

　　⑨　其餘....

（4）生成qch文件。

　　打開命令行控制檯，使用cd命令跳轉至項目目錄的documentation目錄下，而後依次輸入下面的命令（固然，要保證命令正常運行，須要將Qt安裝目錄的bin目錄路徑添加到系統的PATH環境變量中）：

　　①　命令1：qhelpgenerator myhelp.qhp -o myhelp.qch

　　此命令做用生成qch文件。

　　②　命令2：assistant -register myhelp.qch

　　此命令做用註冊qch文件。當註冊成功後，會顯示「documentation successfully registered」提示框。

　　③　命令3：assistant

　　此命令做用啓動Assistant。固然，也能夠從開始菜單中啓動Qt Assistant。啓動後能夠在Assistant的內容Tab中目錄表的最末尾找到咱們的目錄表，同時能夠發現咱們的HTML文檔內容。

（5）不過，（4）不是必須的。只是爲了測試qhp文件是否正確可用。另外，想象一下，生成一個幫助文檔還追隨在別人下面多俗呀~~~若是您僅僅爲了想驗證一下可行性，也可到此爲止。不然，請再繼續看下面內容。

（6）其餘…..

3、建立.qhcp文件，並利用命令生成.qhc文件

　　欲使Qt Assistant只顯示咱們本身的幫助文檔？最簡單的方法就是生成幫助集合文件即.qhc文件。

（1）關於qhcp與qhc

qhcp是Qt Help Collection Project的縮寫，該文件是XML格式的，其主要做用是將qch二進制文件組織成爲一個collection，定製客戶化的Assistant。

　　 qhc則是由qhcp文件經過qcollectiongenerator命令生成的二進制文件，啓動Assistant時須要指定collection參數，即qhc文件。qhc文件中是qch文件的集合，打開Assistant時，經過指定當前collection便可註冊多個幫助文檔。命令格式以下：qcollectiongenerator myHelp.qhcp -o myHelp.qhc

（2）建立qhcp文件。在documentation文件夾中建立一個文本文件，命名爲「myHelp」，修改文件後綴爲qhcp，用Notepad++工具打開文件，編輯內容以下：

 1 <?xml version="1.0" encoding="GB2312"?>
 2 <QHelpCollectionProject version="1.0">
 3 <assistant>
 4   <title>圖書管理客戶端幫助文檔</title>
 5   <applicationIcon>image/lib.png</applicationIcon>
 6   <cacheDirectory>cache/myhelp</cacheDirectory>
 7   <homePage>qthelp://bookmisClient.myhelp/doc/index.html</homePage>
 8   <startPage>qthelp://bookmisClient.myhelp/doc/index.html</startPage>
 9   <aboutMenuText>
10     <text>關於</text>
11   </aboutMenuText>
12   <aboutDialog>
13     <file>./about.txt</file>
14     <icon>image/lib.png</icon>
15   </aboutDialog>
16   <enableDocumentationManager>false</enableDocumentationManager>
17   <enableAddressBar>false</enableAddressBar>
18   <enableFilterFunctionality>false</enableFilterFunctionality>
19 </assistant>
20 <docFiles>
21   <generate>
22     <file>
23       <input>myhelp.qhp</input>
24       <output>myhelp.qch</output>
25     </file>
26   </generate>
27   <register>
28     <file>myhelp.qch</file>
29   </register>
30 </docFiles>
31 </QHelpCollectionProject>

（3）解讀qhcp文件。這個qhcp文件也是XML格式的。

　　①　第一行、第二行同qhp文件解釋。

　　②　第三行起始，assistant標籤中是對Qt Assistant的外觀和功能的定製。其中設置了標題、圖標、緩存目錄、主頁、起始頁、About菜單文本、關於對話框的內容和圖標等，還關閉了一些沒有用的功能。

　　③　第六行緩存目錄cacheDirectory，是進行全文檢索等操做時緩存文件要存放的位置。

　　④　第7、八行主頁homePage、起始頁startPage。這裏使用了第二步中提到的Qt Assistant的頁面的URL，這個URL由「qthelp://」開始，而後是在.qhp文件中設置的命名空間，而後是虛擬文件夾，最後是具體的HTML文件名。

　　⑤　關閉功能。由於Qt Assistant能夠添加或者刪除文檔來爲多個應用程序提供幫助，但此例只是爲一個應用程序提供幫助，而且不但願刪除咱們的文檔，因此禁用了文檔管理器documentation manager；並且這裏的文檔集很小，並且只有一個過濾器部分，因此也關閉了地址欄address bar和過濾器功能filter functionality。

　　⑥　關於about.txt文件。在documentation目錄下新建一個文本文件，命名爲「about」，在其中輸入此製做的幫助的說明信息，做爲Qt Assistant的about菜單的顯示內容。

　　⑦　docFiles標籤。此標籤其實就是完成了第二步中的全部命令操做，不過與第二步不一樣的是，第二步是在默認的集合文件中註冊的，而這裏是在咱們本身的集合文件中註冊的。

　　⑧　其餘….

（4）生成.qhc文件。

　　①　命令1：qcollectiongenerator myhelp.qhcp –o myhelp.qhc

　　此命令做用生成qhc文件。

　　②　命令2：assistant -collectionFile myhelp.qhc

　　此命令做用爲了測試咱們定製的Assistant。此時在運行Qt Assistant時指定了集合文件爲咱們本身的qhc文件，因此運行後只僅僅顯示咱們本身的HTML文檔。

　　如今，能夠看到Qt Assistant的圖標也更改了，打開幫助菜單中的「關於該幫助」菜單，也能夠看到前面添加的about.txt文件的文本內容，效果以下圖所示：

（5）其餘….

4、從程序中啓動Qt Assistant查看幫助

（1）添加assistant類。添加新文件—>選擇C++ class類，類名爲assistant，基類不填寫，類型信息選擇無。

　　①　assistant.h文件以下（詳見註釋）：

 1 #ifndef ASSISTANT_H
 2 #define ASSISTANT_H
 3 
 4 #include <QtCore/QString>
 5 
 6 class QProcess;
 7 class Assistant
 8 {
 9 public:
10     Assistant();
11     ~Assistant();
12     void showDocumentation(const QString &file);
13 
14 private:
15     bool startAssistant();
16 
17 private:
18     QProcess *proc;
19 };
20 
21 #endif // ASSISTANT_H

View Code

　　②　assistant.cpp文件以下（詳見註釋）：

 1 #include <QtCore/QByteArray>
 2 #include <QtCore/QProcess>
 3 #include <QtWidgets/QMessageBox>
 4 #include "assistant.h"
 5 
 6 Assistant::Assistant(): proc(0)
 7 {
 8 }
 9 
10 Assistant::~Assistant()
11 {
12    if (proc && proc->state() == QProcess::Running)
13    {
14        // 試圖終止進程
15        proc->terminate();
16        proc->waitForFinished(3000);
17    }
18    // 銷燬proc
19    delete proc;
20 }
21 
22 // 顯示文檔
23 void Assistant::showDocumentation(const QString &page)
24 {
25    if (!startAssistant())
26        return;
27 
28    QByteArray ba("SetSource ");
29    ba.append("qthelp://bookmisClient.myhelp/doc/");
30    proc->write(ba + page.toLocal8Bit() + '\n');
31 }
32 
33 // 啓動Qt Assistant
34 bool Assistant::startAssistant()
35 {
36    // 若是沒有建立進程，則新建立一個
37    if (!proc)
38        proc = new QProcess();
39    // 若是進程沒有運行，則運行assistant，並添加參數
40    if (proc->state() != QProcess::Running)
41    {
42        QString app = QLatin1String("../MyHelpThis/documentation/assistant.exe");
43        QStringList args;
44        args << QLatin1String("-collectionFile")
45             << QLatin1String("../MyHelpThis/documentation/myhelp.qhc");
46        proc->start(app, args); // 至關於執行命令：assistant –collectionFile myHelp.qhc
47        if (!proc->waitForStarted())
48        {
49             QMessageBox::critical(0, QObject::tr("my help"),
50                 QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
51             return false;
52        }
53    }
54    return true;
55 }

View Code

（2）準備assistant.exe程序。將Qt安裝目錄的bin目錄中的assistant.exe程序複製到項目目錄的documentation目錄中。

（3）修改mainwindow.cpp文件。修改後具體以下（詳見註釋）：

 1 #include "mainwindow.h"
 2 #include "ui_mainwindow.h"
 3 #include "assistant.h"
 4 
 5 MainWindow::MainWindow(QWidget *parent)
 6     : QMainWindow(parent)
 7     , ui(new Ui::MainWindow)
 8     , pAssistant(nullptr)
 9 {
10     ui->setupUi(this);
11     // 建立命令按鈕
12     QAction* pHelp = new QAction("help", this);
13     ui->mainToolBar->addAction(pHelp);
14     // 綁定信號與槽
15     connect(pHelp, SIGNAL(triggered()), this, SLOT(startAssistant()));
16     // 建立Assistant對象
17     pAssistant = new Assistant;
18 }
19 
20 MainWindow::~MainWindow()
21 {
22     delete ui;
23     delete pAssistant;
24 }
25 
26 void MainWindow::startAssistant()
27 {
28     // 按下「help」按鈕，運行Qt Assistant，顯示index.html頁面
29     pAssistant->showDocumentation("index.html");
30 }

View Code

（4）編譯程序（注意工程的文件路徑問題）。

（5）工程文件目錄以下：

工程文件目錄：

documentation文件夾目錄：

（6）運行程序。按下工具欄的help按鈕，就能夠啓動並查看幫助文檔了。

5、利用批處理啓動Qt Assistant查看幫助

　利用程序啓動Qt Assistant顯得比較麻煩點！那麼，如何能夠快速啓動Qt Assistant，不用每次都敲命令呢？咱們能夠選擇使用批處理文件。

　在documentation文件夾中新建一個文本文件，命名爲「myhelp」,修改文件類型爲bat。用Notepad++工具打開文件，編輯內容以下：

1 echo off
2 echo Setting up environment for Qt usage...
3 set PATH=C:\Qt\Qt5.3.2\5.3\msvc2010_opengl\bin;%PATH%
4 cd /D C:\Qt\Qt5.3.2\5.3\msvc2010_opengl
5 cd /D F:\qtHelpDemoDoc\MyHelpThis\documentation
6 qhelpgenerator myhelp.qhp -o myhelp.qch
7 qcollectiongenerator myhelp.qhcp -o myhelp.qhc
8 assistant -collectionFile myhelp.qhc
9 echo Remember to call vcvarsall.bat to complete environment setup!