The Qt Help Framework

Integrating Documentation in Applications

Overview

The Qt help system includes tools for generating and viewing Qt help files. In addition, it provides classes for accessing help contents programmatically to be able to integrate online help into Qt applications.

The actual help data, meaning the table of contents, index keywords, or HTML documents, is contained in Qt compressed help files. So, one such a help file represents usually one manual or documentation set. Since most products are more comprehensive and consist of a number of tools, one manual is rarely enough. Instead, more manuals, which should be accessible at the same time, exist. Ideally, it should also be possible to reference certain points of interest of one manual to another. Therefore, the Qt help system operates on help collection files, which include any number of compressed help files.

However, having collection files to merge many documentation sets may lead to some problems. For example, one index keyword may be defined in different documentation sets. So, when only seeing a keyword in the index and activating it, you cannot be sure that the expected documentation will be shown. Therefore, the Qt help system offers the possibility to filter the help contents after certain attributes. This requires, however, that the attributes have been assigned to the help contents before the generation of the compressed help file.

As already mentioned, the Qt compressed help file contains all data, so there is no need any longer to ship all the single HTML files. Instead, only the compressed help file and, optionally, the collection file have to be distributed. The collection file is optional since any existing collection file, for example from an older release, could be used.

So, in general, there are four files interacting with the help system, two used for generating Qt help and two meant for distribution:

Name	Extension	Brief Description
Qt Help Project	.qhp	Contains the table of contents, indices, and references to the actual documentation files (*.html). It also defines a unique namespace for the documentation. This file is passed to the help generator for creating a compressed help file.
Qt Compressed Help	.qch	Contains all the information specified in the help project file along with all the compressed documentation files.
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	The help collection file that QHelpEngine operates on. It can contain references to any number of compressed help files as well as additional information.

Generating Qt Help

Building help files for the Qt help system assumes that the HTML documentation files already exist.

Once the HTML documents are in place, a Qt Help Project file, with an extension of .qhp , has to be created. After specifying all the relevant information in this file, it needs to be compiled by calling:

qhelpgenerator doc.qhp -o doc.qch

The file doc.qch contains all the HTML files in compressed form along with the table of contents and index keywords. To test if the generated file is correct, open Qt Assistant and install the file in Settings > Documentation.

For the standard Qt source build, the .qhp file is generated and placed in the same directory as the HTML pages.

Creating a Qt Help Collection

The first step is to create a Qt Help Collection Project file. Since a Qt help collection stores primarily references to compressed help files, the project mycollection.qhcp file looks unsurprisingly simple:

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

For actually creating the collection file call:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

To generate both the compressed help and the collection file in one go, modify the help collection project file so that it instructs the help 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>
...

Of course, it is possible to specify more than one file in the generate or register section, so any number of compressed help files can be generated and registered in one go.

Using 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.

Using 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 Manual.

Using 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 class and can be displayed in nearly any form. Showing the help in a QTextBrowser is probably the most common way, but embedding it in What’s This help is also perfectly possible.

Retrieving help data from the file engine does not involve a lot of code. The first step is to create an instance of the help engine. Then we ask the engine for the links assigned to the identifier, in this case MyDialog::ChangeButton . If a link was found, meaning at least one help document exists on this topic, we get the actual help contents by calling fileData() and display the document to the user.

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);
}

For further information on how to use the API, have a look at the QHelpEngine class reference.