Qt 5.6 | Qt Assistant Manual | Using Qt Assistant

Qt 5.6.3 Reference Documentation

Qt Assistant Quick Guide ◦ Customizing Qt Assistant

# Using Qt Assistant

You can read documentation in the Documentation window. To open a topic in a new tab, right click it in the Contents window to open a context menu and select Open Link in New Tab. All open topics are listed in the Open Pages window. Select a topic to view it in the Documentation window.

If you want the Documentation window to use as much space as possible, you can easily group, move or hide the sidebar windows. To group the windows, drag one on top of the other and release the mouse. If one or all sidebar windows are not shown, select keyboard shortcuts to display them. You can view the keyboard shortcuts in the View menu.

The sidebar windows can be docked into the main window, so you can drag them to the top, left, right or bottom of the main window, or you can drag them outside Qt Assistant to float them as independent windows.

To change the font family and font sizes of the browser window displaying the documentation or the application itself, select Edit > Preferences > Fonts.

To temporarily increase or decrease the font size in the Documentation window, select View > Zoom in or Zoom out. To reset the font size, select View > Normal Size.

To navigate between pages, select Go > Previous or Next. This takes you to the previous or next page in the history. To return to the home page, select Go > Home. To specify the home page, select Edit > Preferences > Options.

To synchronize the Contents window with the page currently shown in the Documentation window, select Go > Sync with Table of Contents.

The address toolbar provides a fast way to enter a specific URL for a documentation file. To show the address toolbar, select View > Toolbars > Address Toolbar.

## Searching from Page Contents

To find text on the current page, select Edit > Find in Text. Enter the search term in the field. The search is incremental, meaning that the most relevant result is shown as you enter characters into the field.

If you select the Case sensitive checkbox, the search considers the case of the search term. For example, if you search for spin, it matches spin but not Spin.

To search forwards or backwards from your current position on the page, click Previous or Next.

To hide the find control, either click Close or press Esc.

## Full Text Searching

Qt Assistant provides a powerful full text search engine. You can search for certain words or text in the Search window. Enter the text you want to look for and press Enter or click Search. The search is not case sensitive. For example, 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

Use the Advanced search for more flexibility. You can specify some words so that hits containing these are excluded from the result, or you can search for an exact phrase. Searching for similar words will give results like these:

- `QStin` -- lists all the documents with titles that are similar, such as `QString`
- `QSting` -- lists all the documents with titles that are similar, such as `QString`
- `QStrin` -- lists all the documents with titles that are similar, such as `QString`

Options can be combined to improve the search results.

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

If the documentation has changed — for example, if documents have been added or removed — Qt Assistant will index them again.

## Filtering Help Contents

Qt Assistant allows you to install any kind of documentation as long as it is organized in Qt compressed help files (*.qch). For example, you can view Qt reference documentation for several Qt versions at the same time. In many respects, this is very convenient since only one version of Qt Assistant is needed. However, at the same time it becomes more complicated when performing tasks like searching the index because most keywords are defined in more than one Qt version. This means that Qt Assistant will always ask the user to choose which one should be displayed.

We use documentation filters to solve this issue. A filter is identified by its name, and contains a list of filter attributes. An attribute is just a string and can be freely chosen. Attributes are defined by the documentation itself, which means that every documentation set usually has one or more attributes.

For example, the Qt Assistant documentation defines the attributes `assistant` and `tools`, whereas Qt Designer defines `designer` and `tools`. The filter to display all tools would then define only the attribute `tools` since this attribute is part of both documentation sets. Adding the attribute `assistant` to the filter would then only show Qt Assistant documentation since the Qt Designer documentation does not contain this attribute. Having an empty list of attributes in a filter will match all documentation. That is, it is equivalent to requesting unfiltered documentation.

To create and remove documentation filters, select Edit > Preferences > Filters.

To add a new filter, click Add, specify a filter name, and click OK. Then select the filter attributes in the Attributes field.

To delete a filter, select it and click Remove.

The filter toolbar allows you to apply a filter to the currently installed documentation. To show the filter toolbar, select View > Toolbars > Filter Toolbar.

## Adding Documentation

To install and remove compressed help files, select Edit > Preferences > Documentation.

Click the Install button and choose the path of the compressed help file (*.qch) you would like to install. To delete a help file, select a documentation set in the list and click Remove.

## Specifying Home Page

To specify the homepage Qt Assistant displays when you click the Home button, select Edit > Preferences > Options.

Enter the URL of the home page or select Current Page to set the currently displayed page as your home page. To leave the home page blank, select Blank page. Select Restore to default to reset your home page to the default home page.

## Using Command Line Options

Qt Assistant handles the following command line options:

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 remotely controlled.
-show <widget> | Shows the specified sidebar window which can be "contents", "index", "bookmarks" or "search".
-hide <widget> | Hides the specified sidebar window which can be "contents", "index", "bookmarks" or "search".
-activate <widget> | Activates the specified sidebar window 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.
-remove-search-index | Purges the help search engine's index. This option is useful in case the associated index files get corrupted. Qt Assistant will re-index the documentation at the next start-up.
-rebuild-search-index | Rebuilds the help search engine's index. Note that this operation may take a while to finish.
-setCurrentFilter <filter> | Sets the given filter as the active filter.
-quiet | Does not show any error, warning or success messages.