|  | Home · Overviews · Examples

# Qt Assistant in More Detail

- Command Line Options
- Toolwindows
- Documentation Window
- Toolbars
- Menus
- Dialogs
- Find Text Control
- Filtering Help Contents
- Full Text Searching

## 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 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.

## Toolwindows

The toolwindows provide four ways of navigating documentation:

- 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.
- 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 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 Alt+C, Alt+I or Alt+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.

## 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.

## Toolbars

The toolbar provides fast access to the most common actions.

- Previous takes you to the previous page in history. The menu option is Go|Previous and the keyboard shortcut is Alt+Left Arrow.
- Next takes you to the next page in history. The menu option is Go|Next and the keyboard shortcut is Alt+Right Arrow.
- Home takes you to the home page (usually the first page when launching Qt Assistant). 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+-.
- Normal Size resets the font size to its normal size. The menu option is View|Normal Size and the keyboard shortcut is Ctrl+0.

The address toolbar provides a fast way to enter a specific url for a documentation file. By default, the address toolbar is not shown, so it has to be activated via View|Toolbars|Address Toolbar.
The filter toolbar allows you to apply a filter to the currently installed documentation. As the address toolbar, the filter toolbar is by default not visible and has to be activated via View|Toolbars|Filter Toolbar.

## Menus

### The File Menu

- File|Page Setup... invokes a dialog allowing you to define the page layout like margins and the orientation, but also the paper size.
- File|Print Preview... provides a preview of the printed pages.
- File|Print... invokes the Print dialog.
- File|New Tab opens a new empty tab page in the Documentation window.
- File|Close Tab closes the current tab page of the Documentation window.
- 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 control at the lower end of the Documentation window.
- Edit|Find Next looks for the next occurance of the specified text in the Find Text control.
- Edit|Find Previous looks for the previous occurance of the specified text in the Find Text control.
- Edit|Preferences invokes the Preferences dialog.

### The View Menu

- View|Zoom in increases the font size.
- View|Zoom out decreases the font size.
- View|Normal Size resets the font size.
- View|Contents toggles the display of the Contents toolwindow.
- View|Index toggles the display of the Index 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 in history.
- Go|Forward displays the next page in history.
- Go|Sync with Table of Contents syncs the Contents toolwindow to the currently shown page.
- Go|Next Page selects the next tab page in the Documentation window.
- Go|Previous Page selects the previous tab page in the Documentation window.

### The Bookmarks Menu

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

## 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 Fonts page allows you to change the font family and font sizes of the browser window displaying the documentation or the application itself.
The Filters page lets you create and remove documentation filters. To add a new filter, clikc the Add button, specify a filter name in the appearing dialog and click OK. The select the filter attributes in the list box at the right hand side. 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 of the compressed help file (*.qch) you would like to install. To delete a help file select a documentation in the list and click Remove.

## 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. The search is incremental, meaning whenever you type one character in the find line edit the search process will be started.

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 checkbox 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. To hide the find control, either click the Close button or hit the Esc key.

## Filtering Help Contents

Qt Assistant allows you to install any kind of documentation as long as the documentation is organized in Qt compressed help files (*.qch). For example, it is possible to install the Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. That is in some way very convenient since only one version of Qt Assistant is needed. But at the same time it becomes more complicated when e.g. searching in the index because nearly every keyword is defined in Qt 4.4.0 as well as Qt 4.4.1. This means that Qt Assistant will always ask the user which one should be displayed.

To solve this issue, documentation filters were introduced. A filter is identified by its name and contains a list of filter attributes. An attribute is just a string and can be freely choosen. Attributes are defined by the documentation itself, this means that every documentation has usually one or more attributes. So, the Qt Assistant documentation defines e.g. the attributes `assistant`, `tools` and `4.4.0`, Qt Designer defines `designer`, `tools` and `4.4.0`. The filter to display all tools would then define only the attribute `tools` since this attribute is part of both documentation. 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, i.e. it's equal to unfiltered.

## 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.