Using Qt Assistant for Powerful Online Help

Qt Assistant is a redistributable online help application supplied by Trolltech. Its main virtues are that it supports indexing and full text search and that it can handle multiple documentation sets for multiple applications.

To make use of Qt Assistant, we must incorporate the necessary code in our application, and we must make Qt Assistant aware of our documentation.

Communication between a Qt application and Qt Assistant is handled by the QAssistantClient located in a separate library. To link this library with an application, we must add the following line to the application's .pro file:

LIBS += -lqassistantclient

We will now review the code of a new HelpBrowser class that uses Qt Assistant.

#ifndef HELPBROWSER_H
#define HELPBROWSER_H

class QAssistantClient;

class HelpBrowser
{
public:
 static void showPage(const QString &page);

private:
 static QAssistantClient *assistant;
};

#endif

Here's the new helpbrowser.cpp:

#include 

#include "helpbrowser.h"

QAssistantClient *HelpBrowser::assistant = 0;

void HelpBrowser::showPage(const QString &page)
{
 if (!assistant)
 assistant = new QAssistantClient("");
 assistant->showPage(page);
}

The QAssistantClient constructor accepts a path string as its first argument, which it uses to locate the Qt Assistant executable. By passing an empty path, we signify that QAssistantClient should look for the executable in the PATH environment variable. QAssistantClient has its own showPage() function that accepts a page name with an optional HTML anchor, just like the earlier QTextBrowser subclass's showPage() function.

The next step is to tell Qt Assistant where the documentation is located. This is done by creating a Qt Assistant profile and creating a .dcf file that provides information about the documentation. All this is explained in Qt Assistant's online documentation, so we will not duplicate that information here.

An alternative to using QTextBrowser or Qt Assistant is to use platform-specific approaches to providing online help. For Windows applications, it might be desirable to create Windows HTML Help files and to provide access to them using Microsoft Internet Explorer. You could use Qt's QProcess class or the ActiveQt framework for this. For Unix and Mac OS X applications, a suitable approach might be to provide HTML files and launch a web browser.