This document introduces Qt Assistant , a tool for presenting on-line documentation. It also introduces the Qt Reference Documentation which is accessible using Qt Assistant , or with a web browser. The document is divided into the following sections:
Table of contents:
Once you have installed Qt, Qt Assistant should be ready to run:
assistant
and press
Enter
.
When you start up Qt Assistant , you will be presented with a standard main window application, with a menu bar and toolbar. Below these, on the left hand side are navigation windows called 内容 , 索引 and Bookmarks . On the right, taking up most of the space, is the 文档编制 window. By default, Qt Assistant loads the Qt reference documentation along with the manuals of other Qt tools, like Qt Designer or Qt Linguist .
Qt Assistant works in a similar way to a Web browser. If you click hyperlinks (cross-references), the 文档编制 window will present the relevant page. You can bookmark pages of particular interest and you can click the 上一 and 下一 toolbar buttons to navigate within the pages you have visited.
尽管 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 do not provide. Qt Assistant uses an advanced full text search engine to index all the pages in each compressed help file so that you can search for particular words and phrases.
To perform an index search, click the 索引 tab on the Sidebar (or press Alt+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 文档编制 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. To activate the full text search, either press (Alt+S) or click on the Search tab in the 文档编制 window. Then enter the term you're looking for and hit the Search button. All documents containing the specified term will then be listed in the list box below.
The documentation for the Qt library is written in-line in the
.cpp
files by the developers themselves. The documentation team revises the documentation to ensure that it is accurate and usable, and to provide quality control. The documentation team also writes the larger texts, such as the class descriptions that introduce a class along with the concepts the class uses, as well as introducing the functions and properties that the class provides.
The documentation focuses on the API rather than the internals, since we make great efforts to keep our API consistent and compatible with each new version, but we may change the internals considerably to improve performance and enhance functionality.
The Qt Reference Documentation consists of almost 1,500 HTML pages (over 2,500 printed pages). The overwhelming majority of pages document Qt classes. Since developers differ in the way they think and work we provide a variety of approaches to navigating the documentation set:
No matter where you find yourself in the Qt documentation, you will find extensive cross-referencing. Even snippets of example code contain clickable links, so that for example, if you come across a class declaration in a code example, the class name will be a clickable link to the class's documentation.
In addition to the class documentation some of Qt's modules have extensive descriptions, and there are many overview documents which describe various aspects of the Qt library; all these are linked from the reference documentation home page. There are also two tutorials and numerous example programs in the examples subdirectory of the Qt distribution.
Qt Assistant 处理下列命令行选项：
| 命令行选项 | 简要描述 |
|---|---|
| -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. |
The tool windows provide four ways to navigate the documentation:
If you want the 文档编制 window to use as much space as possible, you can easily group, move or hide the tool windows. To group the windows, drag one on top of the other and release the mouse. If one or all tool windows are not shown, press Alt+C , Alt+I or Alt+O to show the required window.
The tool windows can be docked into the main window, so you can drag them to the top, left, right or bottom of Qt Assistant's window, or you can drag them outside Qt Assistant to float them as independent windows.
The 文档编制 window lets you create a tab 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 文档编制 窗口。
The main toolbar provides fast access to the most common actions.
| 动作 | 描述 | Menu Item | Shortcut |
|---|---|---|---|
| 上一 | Takes you to the previous page in the history. | Go|Previous | Alt+Left Arrow |
| 下一 | Takes you to the next page in the history. | Go|Next | Alt+Right Arrow |
| 首页 | Takes you to the home page as specified in the Preferences Dialog. | Go|Home | Ctrl+Home . |
| Sync with Table of Contents | Synchronizes the 内容 tool window with the page currently shown in the 文档编制 窗口。 | Go|Sync with Table of Contents | |
| Copy | 把任何选中文本拷贝到剪贴板。 | Edit|Copy | Ctrl+C |
| 打印 | Opens the 打印 对话框。 | File|Print | Ctrl+P |
| Find in Text | Opens the Find Text 对话框。 | Edit|Find in Text | Ctrl+F |
| Zoom in | Increases the font size used to display text in the current tab. | View|Zoom in | Ctrl++ |
| Zoom out | Decreases the font size used to display text in the current tab. | View|Zoom out | Ctrl+- |
| Normal Size | Resets the font size to its normal size in the current tab. | View|Normal Size | 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 with the address toolbar, the filter toolbar is not visible by default and has to be activated via View|Toolbars|Filter Toolbar .
This dialog is platform-specific. It gives access to various printer options and can be used to print the document shown in the current tab.
The 字体 page allows you to change the font family and font sizes of the browser window displaying the documentation or the application itself.
The 过滤器 page lets you create and remove documentation filters. To add a new filter, click the 添加 button, specify a filter name in the pop-up dialog and click OK , then select the filter attributes in the list box on the right hand side. You can delete a filter by selecting it and clicking the 移除 button.
The 文档编制 page lets you install and remove compressed help files. Click the 安装 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 移除 .
The 选项 page lets you specify the homepage Qt Assistant will display when you click the 首页 button in Qt Assistant 's main user interface. You can specify the hompage by typing it here or clicking on one of the buttons below the textbox. Current Page sets the currently displayed page as your home page while Restore to default will reset your home page to the default home page.
This control is used to find text in the current page. Enter the text you want to find in the line edit. The search is incremental, meaning that the most relevant result is shown as you enter characters into the line edit.
If you check the Whole words only checkbox, the search will only consider whole words; for example, 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 forwards or backwards from your current position in the page by clicking the 上一 or 下一 buttons. To hide the find control, either click the Close button or hit the Esc key.
Qt Assistant allows you to install any kind of documentation as long as it 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. 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 nearly every keyword is defined in Qt 4.4.0 as well as in Qt 4.4.1. 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, this means that every documentation set usually has one or more attributes.
For example, the Qt 4.4.0
Qt Assistant
documentation defines the attributes
assistant
,
tools
and
4.4.0
,
Qt Designer
定义
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 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; i.e., it is equivalent to requesting unfiltered documentation.
Qt Assistant provides a powerful full text search engine. To search for certain words or text, click the Search tab in the 文档编制 window. Then enter the text you want to look for and press Enter or click the Search button. The search is not case sensitive, so, 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'
深拷贝
-- 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 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 文档编制 窗口。
If the documentation has changed — for example, if documents have been added or removed — Qt Assistant will index them again.