Back to Blog home

New Qt Assistant/Help System

Published on Wednesday December 19, 2007 by thomas in Qt Uncategorized | Comments

Since Qt 3.1, Assistant hasn't been changed that much. In fact, I looks and works almost the same way as it did in Qt 3 times. We have received many suggestions for new features but were not able to implement them since most of them wouldn't work well together with the Assistant structure, meaning they would have required fundamental changes to the code base. Now, for Qt 4.4. we are finally making a step forward by introducing a completely new help system.

The problem with the old Assistant as custom help viewer was that most people wanted to customize it more than it was possible. Some didn't want the side bar at all, some others wanted it to be shown on the right instead of the left side and others wanted to have only the table of contents or indices shown. We also received suggestions to make only some of the menus or toolbars visible. Combining all those customizations would have added a lot of complexity which, in the end, may not even have satisfied all customers. That is why we went for the solution of providing a help library which offers the most important components for online help. The new Qt Assistant is basically just a reference application on top of the help library.

The new help library, called QtHelp, can be used for generating online help as well as retrieving its contents. The task of the retrieving part should be quite clear, but what about the generation part? Well, in contrast to the old Assistant, the new help system does not operate directly on html files any more. Instead, a new binary help file format was introduced which contains all the html files in compressed form along with the table of contents and indices. This should significantly ease up deployment since only one file has to be taken care of.

There are two ways of retrieving and displaying online help, either by using the help library or Assistant. Assistant, at first sight, looks pretty much like the old one, but having a closer look will show some differences. First of all, it is now possible to filter help contents according to their associated help attributes. This is especially helpful when having more than one (yes this is now possible as well!) Qt reference documentation installed. Secondly, navigating through the help contents can also be done by directly entering an url in the address bar. However, the most important fact is that Assistant does not contain any hard coded references to Qt documentation any more. So, every custom documentation integrated in Assistant has now the same possibilities, but also restrictions, as Qt documentation has.

The entire concept of having profiles has been given up in favor of using help collections. The main purpose of a help collection is to collect or reference one or more Qt binary help files. In addition, it can store nearly any data. In case of Assistant, the current help filter, the url of the currently displayed page or the location of its dock widgets - just to mention a few - will be saved. This removes the need of storing anything in the registry or .ini file which eliminates possible side effects seen with the old profiles approach. So, starting Assistant with a different help collection does not only change the set of help files but may also change its visual appearance.

The possibilities to change the visual appearance of Assistant are pretty much comparable to those existing in the old Assistant. However, some new ones like showing or hiding indices, bookmarks or table of contents were added.

Using Assistant as the help browser for an application saves a lot of time and effort. The downside is, that even though Assistant allows some customization it might still be too restrictive for some users. If this is the case, the help library should be deployed.

The help library provides models and views for indices and the table of contents, classes for full text search, functionality for accessing context sensitive help as well as functions for retrieving the actual help contents (usually html files). With the help of those components, it is easily possible to either implement a stand alone help viewer or, more conveniently, embed online help directly in an application.

Now, I guess it's high time to let you know where you can find all this. Well, it has been integrated to our code base and you can get it by downloading a daily snapshot. Examples of how to use the QtHelp API (not 100% finished yet) can be found in the examples directory or in the Qt reference documentation.

The new Assistant is started by executing "assistant_new" (will be renamed). Since the new documentation format is not part of the daily snapshot yet, you have to either generate it yourself or download it from our help server. To generate it, simply call "make qch" in the root directory of Qt. Once the script is finished, restart Assistant and all Qt documentation will be shown.

Instead of generating the documentation yourself, it is much faster to download it from our help server. The help server can be accessed by opening the Edit|Preferences dialog in Assistant and activating the "Documentation" tab. Then select the "Download from Help Server" option from the "Install..." button. After a moment you'll see a collection of currently available Qt documentation files. Select the ones you're interested in and press "Install". That's it!

Subscribe to Our Blog

Stay up to date with the latest marketing, sales and service tips and news.

The blog comment system has been migrated to a new platform. If you face any issues, please let us know via