內容

• 概述
• 生成 Qt Help
• 創建 Qt Help Collection
• 使用 Qt Help
• 使用 Qt Assistant
• 使用 QHelpEngine API

Qt Help 框架

概述

Qt 幫助係統包括用於生成和查看 Qt 幫助文件的工具。此外，它提供用於以編程方式訪問幫助內容的類，為能夠將在綫幫助集成到 Qt 應用程序。

意味著內容錶、索引關鍵字或 HTML 文檔的實際幫助數據，包含在 Qt 壓縮幫助文件中。因此，一個這種幫助文件通常錶示一本手冊或文檔編製集。由於大多數産品更綜閤且由許多工具組成，因此，僅一本手冊是遠遠不夠的。相反，應同時存在更多可訪問手冊。理想情況下，將一本手冊的某些點引用到另一本手冊，應該是可能的。因此，Qt 幫助係統操作幫助集閤文件，包括任意數量的壓縮幫助文件。

不管怎樣，擁有要閤並許多文檔編製集的集閤文件，可能導緻一些問題。例如，可以在不同文檔編製集中定義一索引關鍵字。所以，當僅在索引中看到關鍵字並激活它時，將無法確保是否會展示期望文檔編製。因此，Qt 幫助係統提供在某些屬性之後，過濾幫助內容的可能性。不管怎樣，這要求在生成壓縮幫助文件之前，已將屬性賦值給幫助內容。

如前所述，Qt 壓縮幫助文件包含所有數據，因此不再需要隨附所有單 HTML 文件。相反，僅必須分發壓縮幫助文件和可選集閤文件。集閤文件是可選的，因為可以使用任何現有集閤文件 (例如：來自較舊發行)。

因此，一般有 4 個文件與幫助係統交互，2 個用於生成 Qt 幫助，2 個用於分發：

名稱	Extension	簡要描述
Qt Help Project	.qhp	The input file for the help generator consisting of the table of contents, indices, and references to the actual documentation files (*.html). It also defines a unique namespace for the documentation.
Qt Compressed Help	.qch	The output file of the help generator. This binary file contains all the information specified in the help project file along with all the compressed documentation files.
Qt Help Collection Project	.qhcp	The input file for the help collection generator. It contains references to the compressed help files that should be included in the collection; it also may contain other information for customizing Qt Assistant.
Qt Help Collection	.qhc	The output of the help collection generator. This is the file QHelpEngine operates on. It contains references to any number of compressed help files as well as additional information, such as custom filters.

生成 Qt Help

為 Qt 幫助係統構建幫助文件，假定 HTML 文檔編製文件已存在。

一旦 HTML 文檔到位， Qt Help Project 文件，采用擴展名 .qhp ，必須被創建。在此文件中指定所有相關信息後，需要編譯通過調用：

qhelpgenerator doc.qhp -o doc.qch
					

文件 doc.qch 包含所有壓縮形式的 HTML 文件、內容錶及索引關鍵字。要測試生成文件是否正確，打開 Qt Assistant 並安裝文件在 設置 > 文檔編製 .

對於標準 Qt 源代碼構建，將生成 .qhp 文件並放在如 HTML 頁麵的相同目錄下。

創建 Qt Help Collection

第一步是創建 Qt Help Collection 工程文件。由於 Qt Help Collection 存儲壓縮幫助文件的首要引用，因此工程 mycollection.qhcp 文件看起來齣人意料地簡單：

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <docFiles>
        <register>
            <file>doc.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>
					

用於實際創建集閤文件的調用：

qcollectiongenerator mycollection.qhcp -o mycollection.qhc
					

Instead of running two tools, one for generating the compressed help and another for generating the collection file, it is also possible to just run the qcollectiongenerator tool with a slightly modified project file instructing the generator to create the compressed help first.

...
<docFiles>
    <generate>
        <file>
            <input>doc.qhp</input>
            <output>doc.qch</output>
        </file>
    </generate>
    <register>
        <file>doc.qch</file>
    </register>
</docFiles>
...
					

當然，可以指定多個文件在 generate or register 章節，因此可以一次性生成和注冊任意數量的壓縮幫助文件。

使用 Qt Help

Accessing the help contents can be done in two ways: Using Qt Assistant as documentation browser or using the QHelpEngine API for embedding the help contents directly in an application.

使用 Qt Assistant

Qt Assistant operates on a collection file which can be specified before startup. If no collection file is given, a default one will be created and used. In either case, it is possible to register any Qt compressed help file and access the help contents.

When using Qt Assistant as the help browser for an application, it should be possible to customize it to fit the application better, so that it does not look like an independent, standalone help browser. To achieve this, several additional properties can be set in a Qt help collection file, to change for example the title or application icon of Qt Assistant. For more information, see the Qt Assistant 手冊 .

使用 QHelpEngine API

Instead of showing the help in an external application like the Qt Assistant, it is also possible to embed the online help in the application. The contents can then be retrieved via the QHelpEngine 類且幾乎可以按任何形式顯示。展示幫助在 QTextBrowser 可能是最常見辦法，但將其嵌入 What's This 幫助也十分可能。

從文件引擎檢索幫助數據不涉及很多代碼。第一步是創建幫助引擎實例。然後，嚮引擎詢問賦值給標識符的鏈接，在這種情況 MyDialog::ChangeButton 。若找到鏈接，意味著至少存在有關此話題的一幫助文檔，獲得實際幫助內容通過調用 QHelpEngineCore::fileData () 並嚮用戶顯示文檔。

QHelpEngineCore helpEngine("mycollection.qhc");
...
// get all file references for the identifier
QMap<QString, QUrl> links =
    helpEngine.linksForIdentifier(QLatin1String("MyDialog::ChangeButton"));
// If help is available for this keyword, get the help data
// of the first file reference.
if (links.count()) {
    QByteArray helpData = helpEngine->fileData(links.constBegin().value());
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}
					

有關如何使用 API 的更進一步信息，見 QHelpEngine 類參考。