該文章原創於Qter開源社區（www.qter.org），作者yafeilinux，轉載請注明出處！

環境：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圖片。

首先在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文件，然後在QtAssistant中注冊它。這樣運行QtAssistant就會看到我們添加的文檔了。不過，這一步不是必須的。我們打開命令行控製台，然後使用cd命令跳轉到項目目錄的documentation目錄中，分別輸入下麵的命令後按下回車：

       要保證命令可以正常運行，前提是已經將Qt安裝目錄的bin目錄的路徑添加到了係統的PATH環境變量中。命令運行結果如下圖所示。

當注冊成功時，會顯示“Documentationsuccessfully registered”提示對話框。這時在開始菜單中啟動Qt Assistant（或者直接在命令行輸入assistant來啟動Qt Assistant），可以發現已經出現了我們的HTML文檔，如下圖所示。

要想使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標簽中就完成了第三步的操作。不過與第三步不同的是，第三步是在默認的集合文件中注冊的，而這裏是在我們自己的集合文件中注冊的。

qcollectiongenerator myHelp.qhcp –omyHelp.qhc

       輸出結果如下圖所示。

為了測試我們定製的QtAssistant，可以在輸入如下命令：

assistant –collectionFile myHelp.qhc

這裏在運行Qt Assistant時指定了集合文件為我們自己的.qhc文件，所以運行後隻會顯示我們自己的HTML文檔。可以看到，現在QtAssistant的圖標也更改了，打開“Help”菜單中的“關於該幫助”菜單，這裏是前麵添加的about.txt文件的內容，效果如下圖所示。

這裏先要將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);

// 創建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定製幫助係統，可以製作功能強大的上下文相關的幫助文檔，而對於一個優秀的軟件而言，幫助菜單是必須有的。