[Qt教程]?第47篇 進階（七） 定制Qt幫助系統

樓主 ?發表于 2013-10-7 09:32:39?|?查看: 93|?回復: 0

定制Qt幫助系統 版權聲明 該文章原創于Qter開源社區（www.qter.org），作者yafeilinux，轉載請注明出處！ 導語 ? ?? ? 一個完善的應用程序應該提供盡可能豐富的幫助信息。在Qt中可以使用工具提示、狀態提示以及“What’s This”等簡單的幫助提示，也可以使用QtAssistant來提供強大的在線幫助。如果要進行詳細的功能和使用的介紹，單單使用這些提示信息是不行的，這就需要提供HTML格式的幫助文本。在程序中可以通過調用Web瀏覽器或者使用QTextBrowser來管理和應用這些HTML文件。不過，Qt提供了更加強大的工具，那就是Qt Assistant，它支持索引和全文檢索，而且可以為多個應用程序同時提供幫助，我們可以通過定制Qt Assistant來實現強大的在線幫助系統。 ? ?? ? 為了將Qt Assistant定制為我們自己的應用程序的幫助瀏覽器，需要先進行一些準備工作，主要是生成一些文件，最后再在程序中啟動Qt Assistant。主要的步驟如下： 1.創建HTML格式的幫助文檔； 2.創建Qt幫助項目（Qt help project）.qhp文件，該文件是XML格式的，用來組織文檔，并且使它們可以在Qt Assistant中使用； 3.生成Qt壓縮幫助（Qt compressed help）.qch文件，該文件由.qhp文件生成，是二進制文件； 4.創建Qt幫助集合項目（Qt help collection project）.qhcp文件，該文件是XML格式的，用來生成下面的.qhc文件； 5.生成Qt幫助集合（Qt help collection）.qhc文件，該文件是二進制文件，可以使Qt Assistant只顯示一個應用程序的幫助文檔，也可以定制Qt Assistant的外觀和一些功能； 6.在程序中啟動Qt Assistant。 環境：Windows Xp + Qt 4.8.5+QtCreator2.8.0 目錄 一、創建HTML格式的幫助文檔 二、創建.qhp文件 三、生成.qch文件 四、創建.qhcp文件 五、生成.qhc文件 六、在程序中啟動QtAssistant 正文 一、創建HTML格式的幫助文檔 1.新建Qt Gui應用，項目名稱為“myWhatsThis”，類名為“MainWindow”，基類保持QMainWindow不變。 2.然后可以通過各種編輯器例如Microsoft Word來編輯要使用的文檔，最后保存為HTML格式的文件，例如這里我們創建了5個HTML文件。然后在項目目錄中新建文件夾，命名為“documentation”，再將這些HTML文件放入其中。再在documentation文件夾中再新建一個“images”文件夾，往里面復制一個圖標圖片，以后將作為Qt Assistant的圖標，例如這里使用了yafeilinux.png圖片。 二、創建.qhp文件 首先在documentation文件夾中創建一個文本文件，然后進行編輯，最后另存為“myHelp.qhp”，注意后綴為.qhp。文件的內容如下： <?xml version="1.0"encoding="GB2312"?> <QtHelpProjectversion="1.0"> <namespace>yafeilinux.myHelp</namespace> <virtualFolder>doc</virtualFolder> <filterSection> <toc> <section title="我的幫助"ref="./index.html"> <section title="關于我們"ref="./aboutUs.html"> <section title="關于yafeilinux"ref="./about_yafeilinux.html"></section> <section title="關于Qt Creator系列教程" ref="./about_QtCreator.html"></section> </section> <section title="加入我們"ref="./joinUs.html"></section> </section> </toc> <keywords> <keyword name="關于"ref="./aboutUs.html"/> <keyword name="yafeilinux" ref="./about_yafeilinux.html"/> <keyword name="Qt Creator"ref="./about_QtCreator.html"/> </keywords> <files> <file>about_QtCreator.html</file> <file>aboutUs.html</file> <file>about_yafeilinux.html</file> <file>index.html</file> <file>joinUs.html</file> <file>images/*.png</file> </files> </filterSection> </QtHelpProject> 這個.qhp文件是XML格式的，對于XML格式不是這里介紹的重點，我們主要講解其中的內容，如果大家想了解XML格式相關的知識，可以參考這里。在第一行是XML序言，這里指定了編碼encoding為GB2312，這樣就可以使用中文了，如果只想使用英文，那么編碼一般是UTF-8；第二行指定了QtHelpProject版本為1.0；第三行指定了命名空間namespace，每一個.qhp文件的命名空間都必須是唯一的，命名空間會成為Qt Assistant中的頁面的URL的第一部分，這個在后面的內容中會涉及到；第四行指定了一個虛擬文件夾virtualFolder，這個文件夾并不需要創建，它只是用來區分文件的；再下面的過濾器部分filterSection標簽包含了目錄表、索引和所有文檔文件的列表。過濾器部分可以設置過濾器屬性，這樣以后可以在Qt Assistant中通過過濾器來設置文檔的顯示有否，不過，因為我們這里只有一個文檔，所以不需要Qt Assistant的過濾器功能，這里也就不需要設置過濾器屬性；在目錄表toc（table ofcontents）標簽中創建了所有HTML文件的目錄，指定了它們的標題和對應的路徑，這里設定的目錄表為： ???我的幫助 ? ? ???關于我們 ? 關于yafeilinux ? 關于Qt Creator系列教程 ? 加入我們 然后是keywords標簽，它指定了所有索引的關鍵字和對應的文件，這些關鍵字會顯示在Qt Assistant的索引頁面；在files標簽中列出了所有的文件，也包含圖片文件。 三、生成.qch文件 這里為了測試創建的文件是否可用，可以先生成.qch文件，然后在QtAssistant中注冊它。這樣運行QtAssistant就會看到我們添加的文檔了。不過，這一步不是必須的。我們打開命令行控制臺，然后使用cd命令跳轉到項目目錄的documentation目錄中，分別輸入下面的命令后按下回車： qhelpgeneratormyHelp.qhp –o myHelp.qch assistant –registermyHelp.qch 要保證命令可以正常運行，前提是已經將Qt安裝目錄的bin目錄的路徑添加到了系統的PATH環境變量中。命令運行結果如下圖所示。 當注冊成功時，會顯示“Documentationsuccessfully registered”提示對話框。這時在開始菜單中啟動Qt Assistant（或者直接在命令行輸入assistant來啟動Qt Assistant），可以發現已經出現了我們的HTML文檔，如下圖所示。 四、創建.qhcp文件 要想使Qt Assistant只顯示我們自己的幫助文檔的最簡單的方法就是生成幫助集合文件即.qhc文件，要生成.qhc文件，首先要創建.qhcp文件。在documentation文件夾中新建文本文檔，對其進行編輯，最后另存為“myHelp.qhcp”，注意后綴為.qhcp。這里還要創建一個名為“about.txt”的文本文件，在其中輸入一些該幫助的說明信息，作為QtAssistant的About菜單的顯示內容。myHelp.qhcp文件的內容如下： <?xml version="1.0"encoding="GB2312"?> <QHelpCollectionProjectversion="1.0"> <assistant> <title>我的幫助系統</title> <applicationIcon>images/yafeilinux.png</applicationIcon> <cacheDirectory>cache/myHelp</cacheDirectory> <homePage>qthelp://yafeilinux.myHelp/doc/index.html</homePage> <startPage>qthelp://yafeilinux.myHelp/doc/index.html</startPage> <aboutMenuText> <text>關于該幫助</text> </aboutMenuText> <aboutDialog> <file>./about.txt</file> <icon>images/yafeilinux.png</icon> </aboutDialog> <enableDocumentationManager>false</enableDocumentationManager> <enableAddressBar>false</enableAddressBar> <enableFilterFunctionality>false</enableFilterFunctionality> </assistant> <docFiles> <generate> <file> <input>myHelp.qhp</input> <output>myHelp.qch</output> </file> </generate> <register> <file>myHelp.qch</file> </register> </docFiles> </QHelpCollectionProject> 在assistant標簽中是對Qt Assistant的外觀和功能的定制，其中設置了標題、圖標、緩存目錄、主頁、起始頁、About菜單文本、關于對話框的內容和圖標等，還關閉了一些沒有用的功能。對于緩存目錄cacheDirectory，是進行全文檢索等操作時緩存文件要存放的位置。對于主頁homePage和起始頁startPage，這里使用了第二步中提到的Qt Assistant的頁面的URL，這個URL由“qthelp://”開始，然后是在.qhp文件中設置的命名空間，然后是虛擬文件夾，最后是具體的HTML文件名。因為Qt Assistant可以添加或者刪除文檔來為多個應用程序提供幫助，但是這里只是為一個應用程序提供幫助，并且不希望刪除我們的文檔，所以禁用了文檔管理器documentation manager；因為這里的文檔集很小，而且只有一個過濾器部分，所以也關閉了地址欄address bar和過濾器功能filter functionality。 在前面第三步中我們已經生成了.qch文件并且在Qt Assistant中進行了注冊，但那只是為了測試文件是否可用，其實完全可以跳過第三步，因為在這里的docFiles標簽中就完成了第三步的操作。不過與第三步不同的是，第三步是在默認的集合文件中注冊的，而這里是在我們自己的集合文件中注冊的。 五、生成.qhc文件 在命令行輸入如下命令： qcollectiongenerator myHelp.qhcp –omyHelp.qhc 輸出結果如下圖所示。 為了測試我們定制的QtAssistant，可以在輸入如下命令： assistant –collectionFile myHelp.qhc 這里在運行Qt Assistant時指定了集合文件為我們自己的.qhc文件，所以運行后只會顯示我們自己的HTML文檔。可以看到，現在QtAssistant的圖標也更改了，打開“Help”菜單中的“關于該幫助”菜單，這里是前面添加的about.txt文件的內容，效果如下圖所示。 六、在程序中啟動Qt Assistant 這里先要將Qt安裝目錄的bin目錄中的assistant.exe程序復制到我們項目目錄的documentation目錄中。為了啟動Qt Assistant，先要創建了一個Assistant類。首先向項目中添加新文件，模板選擇C++ Class，類名為“Assistant”，基類不填寫，類型信息選擇無。然后將assistant.h文件更改如下： #ifndef?ASSISTANT_H #define?ASSISTANT_H #include?<QtCore/QString> class?QProcess; class?Assistant { public: ? ??Assistant(); ? ??~Assistant(); ? ??void?showDocumentation(const QString &file); private: ? ??bool?startAssistant(); ? ??QProcess?*proc; }; #endif?//?ASSISTANT_H 在Assistant類中主要是使用QProcess類創建一個進程來啟動Qt Assistant。下面是assistant.cpp文件的內容： #include?<QtCore/QByteArray> #include?<QtCore/QProcess> #include?<QtGui/QMessageBox> #include?"assistant.h" 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://yafeilinux.myHelp/doc/"); ? ?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("../myWhatsThis/documentation/assistant.exe"); ? ?? ??QStringList?args; ? ?? ??args?<<?QLatin1String("-collectionFile") ? ?? ?? ?? ?<<?QLatin1String("../myWhatsThis/documentation/myHelp.qhc"); ? ?? ??proc->start(app, args); ? ?? ??if?(!proc->waitForStarted()) { ? ?? ?? ?? ?QMessageBox::critical(0, QObject::tr("my help"), ? ?? ?? ?? ?? ??QObject::tr("Unable to launch Qt Assistant (%1)").arg(app)); ? ?? ?? ?? ?return?false; ? ?? ??} ? ?} ? ?return?true; } 在startAssistant()函數中使用QProcess創建了一個進程來啟動Qt Assistant，這里使用了命令行參數來使用幫助集合文件，對于assistant.exe和myHelp.qhc都使用了相對地址；在showDocumentation()函數中可以指定具體的頁面作為參數來使Qt Assistant顯示指定的頁面；在析構函數中，如果進程還在運行，則終止進程，最后銷毀了進程指針。 下面來使用Assistant類來啟動Qt Assistant。在mainwindow.h文件中先添加前置聲明： class?Assistant; 再添加private對象指針聲明： Assistant?*assistant; 然后添加一個私有槽： private?slots: ? ??void?startAssistant(); 現在到mainwindow.cpp文件中進行更改。添加頭文件包含#include?"assistant.h"，然后在構造函數中添加如下代碼： QAction?*help?=?new?QAction("help",this); ui->mainToolBar->addAction(help); connect(help, SIGNAL(triggered()), this, SLOT(startAssistant())); //?創建Assistant對象 assistant?=?new?Assistant; 這里創建了一個“help”動作，并將它添加到了工具欄中，可以使用該動作啟動QtAssistant。下面是startAssistant()槽的定義： void?MainWindow::startAssistant() { ? ?//?按下“help”按鈕，運行Qt?Assistant，顯示index.html頁面 ? ?assistant->showDocumentation("index.html"); } 最后在析構函數中銷毀assistant指針，即在MainWindow::~MainWindow()函數中添加如下代碼： //?銷毀assistant delete?assistant; 現在運行程序，按下工具欄上的“help”動作，就可以啟動Qt Assistant了。這里還要提示一下，如果要發布該程序，那么需要將documentation目錄復制到發布目錄中，這時運行程序。 結語 使用Qt定制幫助系統，可以制作功能強大的上下文相關的幫助文檔，而對于一個優秀的軟件而言，幫助菜單是必須有的。 涉及到的代碼：??myWhatsThis.rar?(642.58 KB, 下載次數: 0)?

總結

以上是生活随笔為你收集整理的[Qt教程] 第47篇 进阶（七） 定制Qt帮助系统的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。