Qt 4.4: Qt Assistant Manual

|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# Qt Assistant Manual

## Introduction

This document introduces Qt Assistant, a tool for presenting on-line documentation. The document is divided into the following sections:

Table of contents:

- Introduction
- The One-Minute Guide to Using Qt Assistant
- Qt Assistant in More Detail
- Full Text Searching
- Customizing Qt Assistant

## The One-Minute Guide to Using Qt Assistant

Under Windows, Qt Assistant is available as a menu option on the Qt menu. On Unix, run `assistant` from an xterm.

When you start up Qt Assistant, you will be presented with a standard main-window style application, with a menu bar and toolbar. Below these, on the left hand side are navigation windows called Index, Contents and Bookmarks, as well on the right, taking up most of the space, is the Documentation window. By default, the Qt Assistant documentation is shown in the Documentation window.

To be able to start using the Qt Assistant you have to setup one or more compressed help files. This could be done by navigating to the Edit|Preferences dialog and install a compressed help file (.qch) by pointing to an path containig these on your local hard drive. See The Preferences Dialog for how to do this.

Qt Assistant works in a similar way to a web browser. If you click underlined text (which signifies a cross-reference), the Documentation window will present the relevant page. You can bookmark pages of particular interest and you can click the Previous and Next toolbar buttons to navigate within the pages you've visited.

Although Qt Assistant can be used just like a web browser to navigate through the documentation, Qt Assistant offers a powerful means of navigation that web browsers don't provide. Qt Assistant uses an advanced full text search engine to index all the pages in the compressed help file that it presents so that you can search for particular words and phrases.

To perform an index search, click the Index tab on the Sidebar (or click Ctrl+I). In the 'Look For' line edit enter a word, e.g. 'homedirpath'. As you type, words are found and highlighted in a list beneath the line edit. If the highlighted text matches what you're looking for, double click it, (or press Enter) and the Documentation window will display the relevant page. You rarely have to type in the whole word before Qt Assistant finds a match. Note that for some words there may be more than one possible page that is relevant.

Qt Assistant also provides full text searching for finding specific words in the documentation. Documents with the highest occurrences of the word that you are looking for appear first, and every occurrence of the word within the documentation is highlighted.

## Qt Assistant in More Detail

### The Toolwindows

The toolwindows provide four ways of navigating documentation:

- The Index window is used to look up key words or phrases. See The One-Minute Guide to Using Qt Assistant for how to use this window.
- The Contents window presents a table of contents implemented as an tree view for the documentation that is available. If you click an item, its documentation will appear in the Documentation window. If you double click an item or click a '+' sign to the left of an item, the item's sub-items will appear. Click a sub-item to make its page appear in the Documentation window. Click a '-' sign to the left of an item to hide its sub-items.
- Both the Index and Contents window is providing a dropdown with filtersets to specify the documentation where the search is performed on.
- The Bookmarks window lists any bookmarks you've made. Double click a bookmark to make its page appear in the Documentation window. The Bookmarks window provides a context menu with Show Item, Delete Item as well as Rename Item. Click in the main menu Bookmark|Add Bookmark... (or press Ctrl+B) to bookmark the page that is currently showing in the Documentation window. Right click a bookmark in the list, to rename or delete the highlighted bookmark.

If you want the Documentation window to use as much space as possible, you can easily group, move or hide the toolwindows. To group the windows drag one on the other and release the mouse. If one or all toolwindows are not shown, press Ctrl+T, Ctrl+I or Ctrl+O to show the individual window.

The toolwindows are dock windows, so you can drag them to the top, left, right or bottom of Qt Assistant's window, or you can drag it outside Qt Assistant to float it.

### The Documentation Window

The Documentation window offers a feature for viewing documentation by enabling you to create tabs for each documentation page that you view. Click the Add Tab button and a new tab will appear with the page name as the tab's caption. This makes it convenient to switch between pages when you are working with different documentation. You can delete a tab by clicking the Close Tab button located on the right side of the Documentation window.

### The Toolbar

The toolbar provides fast access to the most common actions.

- Previous takes you to the previous page. The menu option is Go|Previous and the keyboard shortcut is Alt+Left Arrow.
- Next takes you to the next page. The menu option is Go|Next and the keyboard shortcut is Alt+Right Arrow.
- Home takes you to the home page (normally the home page of the Qt Reference Documentation). The menu option is Go|Home and the keyboard shortcut is Ctrl+Home.
- Sync with Table of Contents will sync the Contents toolwindow to the currently shown page in the Documentation window. The menu option is Go|Sync with Table of Contents.
- Copy copies any selected text to the clipboard. The menu option is Edit|Copy and the keyboard shortcut is Ctrl+C.
- Print invokes the Print dialog. The menu option is File|Print and the keyboard shortcut is Ctrl+P.
- Find in Text invokes the Find Text dialog. The menu option is Edit|Find in Text and the keyboard shortcut is Ctrl+F.
- Zoom in increases the font size. The menu option is View|Zoom in and the keyboard shortcut is Ctrl++.
- Zoom out decreases the font size. The menu option is View|Zoom out and the keyboard shortcut is Ctrl+-.

The address toolbar will be the fast way to enter a specific url for a documentation file.

### The Menus

#### The File Menu

- File|Print invokes the Print dialog.
- File|Exit terminates Qt Assistant.

#### The Edit Menu

- Edit|Copy copies any selected text to the clipboard.
- Edit|Find in Text invokes the Find Text dialog.
- Edit|Preferences invokes the Preferences dialog.

#### The View Menu

- View|Zoom in increases the font size.
- View|Zoom out decreases the font size.
- View|Index toggles the display of the Index toolwindow.
- View|Contents toggles the display of the Contents toolwindow.
- View|Bookmarks toggles the display of the Bookmarks toolwindow.
- View|Search toggles the display of the Search in the Documentation window.

#### The Go Menu

- Go|Home goes to the home page.
- Go|Back displays the previous page.
- Go|Forward displays the next page.
- Go|Sync with Table of Contents syncs the Contents toolwindow to the currently shown page.
- Go|Next Page selects the next page in the Documentation window.
- Go|Previous Page selects the previous page in the Documentation window.

#### The Bookmarks Menu

- Bookmarks|Add adds the current page to the list of bookmarks.

### The Dialogs

#### The Print Dialog

This dialog is platform-specific. It gives access to various printer options and can be used to print the current page.

#### The Preferences Dialog

The Filters page offers a feature for setting documentation filters for each compressed help file that is installed. Click the Add button to add new filter and specify the attributes on what help file the filter should work. You can delete a filter by clicking the Remove button.

The Documentation page will provide you a way to install and remove compressed help files. Click the Install button and choose the path on your hard drive from from where you would like to install your compressed help file (.qch). To delete a help file select a documentation in the list and click Remove.

#### The Find Text Control

This Control is used to find text in the current page. Enter the text you want to find in the Find line edit. If you check the 'Whole words only' checkbox, the search will only consider whole words, i.e. if you search for 'spin' with this checkbox checked it will not match 'spinbox', but will match 'spin'. If you check the 'Case sensitive' check box then, for example, 'spin' will match 'spin' but not 'Spin'. You can search Forward or Backward from your current position in the page by clicking one of the Direction radio buttons. Click the Find button to search (or search again), and click the Close button to finish.

## Full Text Searching

Qt Assistant provides a powerful full text search engine. To search for certain words or text, click the 'Search' tab in the Documentation window. Then enter the text you want to look for and press Enter or click Search. The search is not case sensitive, so Foo, fOo and FOO are all treated as the same. The following are examples of common search patterns:

- `deep` -- lists all the documents that contain the word 'deep'
- `deep*` -- lists all the documents that contain a word beginning with 'deep'
- `deep copy` -- lists all documents that contain both 'deep' and 'copy'
- `"deep copy"` -- list all documents that contain the phrase 'deep copy'

It is also possible to use the Advanced search to get more flexibility. You can specify some words so that hits containing these are excluded from the result or search for an exact phrase of words. Search for similar words will look like this:

- `QStin` -- lists all the documents that that are similar like 'QString'
- `QSting` -- lists all the documents that that are similar like 'QString'
- `QStrin` -- lists all the documents that that are similar like 'QString'

All options can be combined to enhance your search options.

The list of documents found is ordered according to the number of occurrences of the search text they contain, therefore those with the highest number of occurrences appearing first. Simply click any document in the list to display it in the document window.

If the documentation has changed, i.e. if documents have been added or removed, Qt Assistant will reindex.

## Using Qt Assistant as custom help browser

Using Qt Assistant as custom help browser requires more than just being able to display any kind of 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 browser 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 Customizing Qt Assistant section.

The third requirement needed to use Qt Assistant as a custom help browser 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 browser 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 browser. The section about using Qt Assistant remotely explains how this can be done.

### Customizing Qt Assistant

Qt Assistant can be customized by using different command line options passed on startup. In addition, Qt Assistant introduces also some special help collection tags, which enables its properties to change, for example the default startup page, the about dialog text or the general look.

Note that all Qt Assistant settings are stored in the used help collection file and Qt Assistant operates entirely on this collection. That means while changing or removing the current help collection, Qt Assistant will behave totally different according to the used collection file and it's stored settings.

#### Modifying the Qt Assistant with command line options

Different help collections can be shown by simply passing the help collection path to Qt Assistant. For example:

         1: > assistant -collectionFile file

Other available options the can be passed on the command line.

Command Line Option | Brief Description
--- | ---
-collectionFile <file.qhc> | Uses the specified collection file instead of the default one.
-showUrl URL | Shows the document referenced by URL.
-enableRemoteControl | Enables Qt Assistant to be remotly controlled.
-show <widget> | Shows the specified dockwidget which can be "contents", "index", "bookmarks" or "search".
-hide <widget> | Hides the specified dockwidget which can be "contents", "index", "bookmarks" or "search.
-activate <widget> | Activates the specified dockwidget which can be "contents", "index", "bookmarks" or "search.
-register <doc.qch> | Registers the specified compressed help file in the given help collection.
-unregister <doc.qch> | Unregisters the specified compressed help file from the given collection file.
-quiet | Doesn't show any error, warning or success messages.

#### Documentation Help collection tags

Help collection tags enable Qt Assistant to act as a specialized help tool for displaying documentation for any application. With help of these tags, the documentation writer can change properties such as Qt Assistant's title, application icons, 'about' dialog text and others. Qt Assistant can be customized by specifying 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.

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</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.qhp</input>
                         <output>myapplication.qch</output>
                     </file>
                 </generate>
                 <register>
                     <file>myapplication.qch</file>
                 </register>
             </docFiles>
         </QHelpCollectionProject>

#### Using Qt Assistant remotely

Even though the help browser 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 browser is started. Another advantage with this approach is that the application can communicate with the help browser 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 browser 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.