Qt Help 框架

概述

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

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

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

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

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

名稱	Extension	簡要描述
Qt Help Project	.qhp	包含內容錶、索引及實際文檔編製文件 (* .html) 引用。它還為文檔編製定義唯一名稱空間。此文件被傳遞給幫助生成器，為創建壓縮幫助文件。
Qt Compressed Help	.qch	包含在幫助工程文件中指定的所有信息，及所有壓縮文檔編製文件。
Qt Help Collection Project	.qhcp	An XML file that contains references to the compressed help files that should be included in the help collection. In addition, it may contain information for customizing Qt Assistant. This file can be passed to the help generator for creating a help collection file.
Qt Help Collection	.qhc	幫助集閤文件 QHelpEngine operates on. It can contain references to any number of compressed help files as well as additional information.

生成 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>

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

qhelpgenerator mycollection.qhcp -o mycollection.qhc

要一次性生成壓縮幫助和集閤文件，修改幫助集閤工程文件，以便指導幫助生成器首先創建壓縮幫助：

...
<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 類參考。