|  | Home · Overviews · Examples

# Using Qt Assistant as Custom Help Viewer

Using Qt Assistant as custom help viewer requires more than just being able to display custom documentation, i.e. displaying also documentation not related to Qt. It is equally important that the appearance of Qt Assistant can be customized so that it is seen as a homemade help viewer rather than Qt Assistant. This is achieved by changing the window title or icon as well as some application name specific menu texts and actions. The complete list of possible customizations can be found in the Creating a Custom Help Collection File section.

The third requirement needed to use Qt Assistant as 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. Then, the help viewer should 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. The section about Using Qt Assistant Remotely explains how this can be done.

- Qt Help Collection Files
- Displaying Custom Documentation
- Changing the Appearance of Qt Assistant
- Using Qt Assistant Remotely
- Compatibility with Old Formats

## Qt Help Collection Files

What is important to know is that Qt Assistant stores both 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 custom help viewer for more than one application on one machine without any interference.

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

        1: > assistant -collectionFile mycollection.qhc

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

But even if it would be possible to give everybody the right to store the settings in the 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 as it is called in other places of the documentation can be defined in the help collection project file.

        <?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

        1: > 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 syncronising 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 it has to know the location of the Qt compressed help file (*.qch). As already mentioned, Qt Assistant stores the 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 help viewer, more documentation needs to be added over time, e.g. when installing more application components or plugins. This can be done manually by starting Qt Assistant, opening the Edit|Preferences dialog and navigating to the Documentation tab page. Then click the Add... button, select a Qt compressed help file (*.qch) and press Open. However, this approach has the big disadvantage that every user has to do it manually to get access to the new documentation.

The prefered way of add 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.

        1: > assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

To avoid the displaying of the status message, the `-quiet` flag can be passed on to Qt Assistant.

Note:Qt Assistant will show 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, those command line options only allow to show or hide specific widgets like the contents or index view. Other customizations like 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 supports the following tags:

Tag name | Brief Description
--- | ---
<title> | This property is used to specify a window title for Qt Assistant.
<startPage> | This tag specifies which page Qt Assistant should initially display when the help collection is used. This property also describes the default location to go to when pressing the home button in Qt Assistant's main user interface.
<currentFilter> | This tag specifies the current filter that is initialy set. If this filter is not specified, the documentation will not be filtered. This has no impact if only one documentation is installed.
<applicationIcon> | This tag describes an icon that will be used as Qt Assistant application icon. The path needs to be relativ to the collection file.
<enableFilterFunctionality> | This tag is used to enable or disable user accessible filter functionality, i.e. the user cannot change any filter when running Qt Assistant. It does not mean that the internal filter functionality is completely disabled. Set the value to `false` if you want to disable the filtering. If the filter toolbar should be shown by default, set the attribute `visible` to `true`.
<enableDocumentationManager> | This tag describes if the documentation manager in the preferences dialog is shown or not. Disabling the Documentation Manager allows you to limit Qt Assistant to display a specific documentation or make it impossible to accidentally remove or install documentation by the end user. To hide the documentation manager set the tag value to `false`.
<enableAddressBar> | This tag describes if the address bar exists at all or not. By default it is enabled, if you want to disable it set the tag value to `false`. If the address bar functionality is enabled, the address bar can be shown by setting the tag attribute `visible` to `true`.
<aboutMenuText>, <text> | The `aboutMenuText` tag lists texts for different languages, e.g. "About Application", which will later appear in the Help menu. A text is specified within the `text` tags, the `language` attribute takes the two letter language name. The text is taken as the default text if no language attribute is specified.
<aboutDialog>, <file>, <icon> | The `aboutDialog` tag can be used to specify the text for the About dialog that is opened for the Help menu. The text is taken from the file in the `file` tags. It is possible to specify a different file or any language. The icon defined by the `icon` tags is applied to any language.
<cacheDirectory> | Path relative to the user's home directory. The cache path is used to store index files needed for the fulltext search and a copy of the collection file. The copy is needed because Qt Assistant stores all its settings in the collection file, i.e. it must be writable for the user.

In addition to those Qt Assistant specific tags, the tags for generating and registering documentation can be used. See Qt Help Collection 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`:

        1: > qcollectiongenerator mycollection.qhcp -o mycollection.qhc

To test the generated collection file, start Qt Assistant:

        1: > assistant -collectionFile mycollection.qhc

## Using Qt Assistant Remotely

Even though the help viewer is a stand alone application, it will mostly be launched from within 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 Assistant executable. In order to make Assistant listening to your application, turn on its remote control functionality by passing the "-enableRemoteControl" command line option.

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

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

        QTextStream str(p);
        str << QLatin1String("setSource qthelp://com.mycompany.1_0_0/doc/index.html\0") << endl;

The following commands are possible:

Command | Brief Description
--- | ---
show <Widget> | Shows the specified dock widget <Widget>. If the widget is already shown and this command is sent again, the widget will be activated, meaning it will be raised and receives the focus. Possible values for <Widget> are "contents", "index", "bookmarks" or "search".
hide <Widget> | Hides the specified dock widget <Widget>. Possible values for <Widget> are "contents", "index", "bookmarks" or "search".
setSource <Url> | Displays the given <Url>. The url can be absolute or relative to the currently displayed page. If the url is absolute, it has to be a valid qt help url, i.e. starting with "qthelp://".
activateKeyword <Keyword> | Inserts the specified <Keyword> into the line edit of the index dock widget and activates the corresponding item in the index list. If such an item has more than one link associated with it, a topic chooser will be shown.
activateIdentifier <Id> | Displays the help contents for the given <Id>. An id is unique in at least one namespace and has only one link associated to it, so the topic chooser will never pop up.
syncContents | Selects the item in the contents widget which corresponds to the currently displayed page.
expandToc <Depth> | Expands the table of contents tree to the given depth. If depth is less than 1, the tree will be collapsed.

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 process' stdin instead of one line for every command. The commands have to be separated by a simicolon.

        QTextStream str(p);
        str << QLatin1String("hide bookmarks;")
            << QLatin1String("hide index;")
            << QLatin1String("setSource qthelp://com.mycompany.1_0_0/doc/index.html\0")
            << endl;

## Compatibility with Old Formats

In older versions of Qt, the help system was based on Document Content File (DCF) and Qt Assistant Documentation Profile (ADP) formats. In contrast, Qt Assistant and the help system used in Qt 4.4 use the formats described earlier in this manual.

Unfortunately, the old file formats are not compatible with the new ones. 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.