Customizing Qt Assistant

Using Qt Assistant as custom help viewer requires more than just being able to display custom documentation. It is equally important that the appearance of Qt Assistant can be customized so that it is seen as a application-specific help viewer rather than Qt Assistant. This is achieved by changing the window title or icon, as well as some application-specific menu texts and actions. For a complete list of possible customizations, see Creating a Custom Help Collection File.

Another requirement of a custom help viewer is the ability to receive actions or commands from the application it provides help for. This is especially important when the application offers context sensitive help. When used in this way, the help viewer may need to change its contents depending on the state the application is currently in. This means that the application has to communicate the current state to the help viewer. For more information, see Using Qt Assistant Remotely.

The Simple Text Viewer example uses the techniques described in this document to show how to use Qt Assistant as a custom help viewer for an application.

Warning: In order to ship Qt Assistant in your application, it is crucial that you include the sqlite plugin. For more information on how to include plugins in your application, refer to the deployment documentation.

Qt Help Collection Files

The first important point to know about Qt Assistant is that it stores all settings related to its appearance and a list of installed documentation in a help collection file. This means, when starting Qt Assistant with different collection files, Qt Assistant may look totally different. This complete separation of settings makes it possible to deploy Qt Assistant as a custom help viewer for more than one application on one machine without risk of interference between different instances of Qt Assistant.

To apply a certain help collection to Qt Assistant, specify the respective collection file on the command line when starting it. For example:

  assistant -collectionFile mycollection.qhc

However, storing all settings in one collection file raises some problems. The collection file is usually installed in the same directory as the application itself, or one of its subdirectories. Depending on the directory and the operating system, the user may not have any permissions to modify this file which would happen when the user settings are stored. Also, it may not even be possible to give the user write permissions, for example when the file is located on a read-only medium like a CD-ROM.

Even if it is possible to give everybody the right to store their settings in a globally available collection file, the settings from one user would be overwritten by another user when exiting Qt Assistant.

To solve this dilemma, Qt Assistant creates user specific collection files which are more or less copied from the original collection file. The user-specific collection file will be saved in a subdirectory of the path returned by QDesktopServices::DataLocation. The subdirectory, or cache directory within this user-specific location, can be defined in the help collection project file. For example:

  <?xml version="1.0" encoding="utf-8" ?>
  <QHelpCollectionProject version="1.0">
      <assistant>
          <title>My Application Help</title>
          <cacheDirectory>mycompany/myapplication</cacheDirectory>
          ...
      </assistant>
  </QHelpCollectionProject>

So, when calling

  assistant -collectionFile mycollection.qhc

Qt Assistant actually uses the collection file:

  %QDesktopServices::DataLocation%/mycompany/myapplication/mycollection.qhc

There is no need ever to start Qt Assistant with the user specific collection file. Instead, the collection file shipped with the application should always be used. Also, when adding or removing documentation from the collection file (see next section) always use the normal collection file. Qt Assistant will take care of synchronizing the user collection files when the list of installed documentation has changed.

Displaying Custom Documentation

Before Qt Assistant is able to show documentation, it has to know where it can find the actual documentation files, meaning that it has to know the location of the Qt compressed help file (*.qch). As already mentioned, Qt Assistant stores references to the compressed help files in the currently used collection file. So, when creating a new collection file you can list all compressed help files Qt Assistant should display.

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

Sometimes, depending on the application for which Qt Assistant acts as a help viewer, more documentation needs to be added over time; for example, when installing more application components or plugins. This can be done manually in Qt Assistant by selecting Edit > Preferences > Documentation. However, this approach has the disadvantage that every user has to do it manually to get access to the new documentation.

The preferred way of adding documentation to an already existing collection file is to use the -register command line flag of Qt Assistant. When starting Qt Assistant with this flag, the documentation will be added and Qt Assistant will exit right away displaying a message if the registration was successful or not.

The search indexing will only index your custom *.html, *.htm, and *.txt files.

  assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

The -quiet flag can be passed on to Qt Assistant to prevent it from writing out the status message.

Note: Qt Assistant shows the documentation in the Contents view in the same order as it was registered.

Changing the Appearance of Qt Assistant

The appearance of Qt Assistant can be changed by passing different command line options on startup. However, these command line options only allow to show or hide specific widgets, like the contents or index view. Other customizations, such as changing the application title or icon, or disabling the filter functionality, can be done by creating a custom help collection file.

Creating a Custom Help Collection File

The help collection file (*.qhc) used by Qt Assistant is created when running the qcollectiongenerator tool on a help collection project file (*.qhcp). The project file format is XML and it supports the following tags:

In addition to those Qt Assistant specific tags, the tags for generating and registering documentation can be used. See Qt Help Collection Files documentation for more information.

An example of a help collection file that uses all the available tags is shown below:

  <?xml version="1.0" encoding="utf-8" ?>
  <QHelpCollectionProject version="1.0">
      <assistant>
          <title>My Application Help</title>
          <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
          <currentFilter>myfilter</currentFilter>
          <applicationIcon>application.png</applicationIcon>
          <enableFilterFunctionality>false</enableFilterFunctionality>
          <enableDocumentationManager>false</enableDocumentationManager>
          <enableAddressBar visible="true">true</enableAddressBar>
          <cacheDirectory>mycompany/myapplication</cacheDirectory>
          <aboutMenuText>
              <text>About My Application</text>
              <text language="de">Über meine Applikation...</text>
          </aboutMenuText>
          <aboutDialog>
              <file>about.txt</file>
              <file language="de">ueber.txt</file>
              <icon>about.png</icon>
          </aboutDialog>
      </assistant>
      <docFiles>
          <generate>
              <file>
                  <input>myapplication-manual.qhp</input>
                  <output>myapplication-manual.qch</output>
              </file>
          </generate>
          <register>
              <file>myapplication-manual.qch</file>
          </register>
      </docFiles>
  </QHelpCollectionProject>

To create the binary collection file, run the qcollectiongenerator tool:

  qcollectiongenerator mycollection.qhcp -o mycollection.qhc

To test the generated collection file, start Qt Assistant in the following way:

  assistant -collectionFile mycollection.qhc

Using Qt Assistant Remotely

Even though the help viewer is a standalone application, it will mostly be launched by the application it provides help for. This approach gives the application the possibility to ask for specific help contents to be displayed as soon as the help viewer is started. Another advantage with this approach is that the application can communicate with the help viewer process and can therefore request other help contents to be shown depending on the current state of the application.

So, to use Qt Assistant as the custom help viewer of your application, simply create a QProcess and specify the path to the Qt Assistant executable. In order to make Qt Assistant listen to your application, turn on its remote control functionality by passing the -enableRemoteControl command line option.

The following example shows how this can be done:

  QProcess *process = new QProcess;
  QStringList args;
  args << QLatin1String("-collectionFile")
      << QLatin1String("mycollection.qhc")
      << QLatin1String("-enableRemoteControl");
  process->start(QLatin1String("assistant"), args);
  if (!process->waitForStarted())
      return;

Once Qt Assistant is running, you can send commands by using the stdin channel of the process. The code snippet below shows how to tell Qt Assistant to show a certain page in the documentation.

  QByteArray ba;
  ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
  process->write(ba);

Note: The trailing newline character is required to mark the end of the input.

The following commands can be used to control Qt Assistant:

If you want to send several commands within a short period of time, it is recommended that you write only a single line to the stdin of the process instead of one line for every command. The commands have to be separated by a semicolon, as shown in the following example:

  QByteArray ba;
  ba.append("hide bookmarks;");
  ba.append("hide index;");
  ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
  process->write(ba);

Compatibility with Old Formats

In Qt versions up to 4.3, the help system was based on Document Content File (DCF) and Qt Assistant Documentation Profile (ADP) formats. Unfortunately, the old file formats are not compatible with the new ones that are described in this manual and that are used from Qt 4.4 on, also in Qt 5. In general, the differences are not that big — in most cases is the old format is just a subset of the new one. One example is the namespace tag in the Qt Help Project format, which was not part of the old format, but plays a vital role in the new one. To help you to move to the new file format, we have created a conversion wizard.

The wizard is started by executing qhelpconverter. It guides you through the conversion of different parts of the file and generates a new qch or qhcp file.

Once the wizard is finished and the files created, run the qhelpgenerator or the qcollectiongenerator tool to generate the binary help files used by Qt Assistant.