為了將Qt Assistant定制為自己應用程序的幫助文檔瀏覽器。需要完成以下幾步:
一、導入HTML格式的幫助文檔
(1)首先,針對自己的應用程序創建HTML格式的幫助文檔,請參見《Doxygen生成HTML文件》。(下面示例假設HTML文件已經存在)
(2)新建Gui應用。QtCreator-->new Project-->Qt Widgets Application 新建項目名稱定義為“MyHelpThis”,類名定義為“MainWindow”,基類保持QMainWindow不變。
(3)在項目目錄中新建文件夾,命名為“documentation”。在documentation文件夾中再新建一個“images”文件夾,往里面拷貝一個圖標圖片,以后將作為Assistant程序左上角的圖標,此例中使用了lib.png。
(4)在documentation文件夾中再新建一個“demoHtml”文件夾,將(1)生成的HTML文件拷貝至其中。此例中放入已經存在的7個HTML文件。
(5)其他.....
二、創建.qhp文件,並利用命令生成.qch文件
(1)關於qhp與qch
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)其他…..
三、創建.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,是進行全文檢索等操作時緩存文件要存放的位置。
④ 第七、八行主頁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文件。
打開命令行控制台,使用cd命令跳轉至項目目錄的documentation目錄下,然后依次輸入下面的命令(當然,要保證命令正常運行,需要將Qt安裝目錄的bin目錄路徑添加到系統的PATH環境變量中):
① 命令1:qcollectiongenerator myhelp.qhcp –o myhelp.qhc
此命令作用生成qhc文件。
② 命令2:assistant -collectionFile myhelp.qhc
此命令作用為了測試我們定制的Assistant。此時在運行Qt Assistant時指定了集合文件為我們自己的qhc文件,所以運行后只僅僅顯示我們自己的HTML文檔。
現在,可以看到Qt Assistant的圖標也更改了,打開幫助菜單中的“關於該幫助”菜單,也可以看到前面添加的about.txt文件的文本內容,效果如下圖所示:
(5)其他….
四、從程序中啟動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
② 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 }
(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 }
(4)編譯程序(注意工程的文件路徑問題)。
(5)工程文件目錄如下:
工程文件目錄:
documentation文件夾目錄:
(6)運行程序。按下工具欄的help按鈕,就可以啟動並查看幫助文檔了。
五、利用批處理啟動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!
然后,雙擊bat文件執行。可以看到四(6)中按下help按鈕同樣的效果圖。
注意 系統環境:Windows7 + Qt5.3.2 + QtCreator3.2.1
Good Good Study, Day Day Up.
順序 選擇 循環 總結