5.2 使用 Qt Assistant 获取在线文档与帮助

5.2.1 简介

对于大多数复杂的程序来说，在线文档和帮助是必不可少的。 Qt 通过 Qt 助手－一个 帮助文件和文档的在线阅读器，来满足这一需求。 简单的说，Qt Assistant 就是浏览 Qt 参考文档的工具，它具有强大的查询和索引功能，使用时能够比 Web 浏览器更加快速和容 易。而且它可定制，并且可随用户自己的应用程序一起发布，从而形成用户自己的帮助系 统。

开发人员可以将 Qt Assistant 部署为自有应用程序和文档集的帮助浏览器。使用 QAssistantClient 类，可以集成 Qt Assistant。Qt Assistant 使用 QTextEdit 来显示 Qt 的 HTML 参考文档；如有必要，开发人员也可以使用此类来直接实现自己的帮助浏览 器。QTextEdit 支持 HTML 4.0 的子集，它与 Qt 提供的富文本（RichText）类一起使用 时，也可以用来显示其他格式的文档。

5.2.2 Qt 的参考文档

Qt 的参考文档包括大约 3,100 页 HTML 文档，描述 了 Qt 的所有类和工具，并概述 了 Qt 编程的各个方面，所以对于任何一名 Qt 开发人员来说，它都是一个基本工具。 通常 任何一本 Qt 书籍都不能完全覆盖到 Qt 中所有的类和函数，同时也无法提供全部的细节。 所以如果想尽可能的从 Qt 获益，那么就应当尽可能的达到对 Qt 参考文档了如指掌的程 度。

在 Qt 的 doc/html 目录下可以找到 HTML 格式的参考文档，并且可以使用任何一种 Web 浏览器来阅读它。也可以使用 Qt 的帮助浏览器 Qt Assistant，它具有强大的查询和索引功 能，使用时能够比 Web 浏览器更加快速和容易。

另外，可以从 http://doc.trolltech.com 中获取 Qt 的当前版和一些早期版本的在线参考文档。这个网站也选摘了 Qt 季刊（Qt Quarterly）中的一些文章。Qt 季刊是 Qt 程序 员的时事通讯，会发给所有获得 Qt 商业许可协议的人员。

5.2.3 使用 Qt Assistant 1.运行 Qt Assistant

要运行 Qt Assistant，在 Windows 下，如果是采用 Qt SDK 方式安装的 Qt 库，那么你 在程序组里面是找不到 Qt Assistant 的快捷方式的，它被整合到了 Qt Creator 里面，你 可以在运行 Qt Creator 时，按下 F1 键，即可调出 Qt Assistant，或者可以去 Qt 的安装目 录下面找到 Qt Assistant 的执行文件，双击运行或者干脆为它在桌面上设置一个快捷方 式；如果使用框架方式安装 Qt 库的话，可以在程序组里面找到它的快捷方式，点击后即可 运行；在 X11 下，可在命令行终端中输入 assistant 命令；在 Mac OS X Finder 中，只需 双击 assistant 即可。

注意，上述指的是一般的情况，比如各个 Linux 发行版对 Qt Assistant 的命名也有所 不同，甚至有时路径也不完全一样。下面是个具体例子：

如果你是自己编译源代码安装的 Qt，而且没有配置快捷方式的话，可以启动命令行， 进入你的 Qt 安装目录，以笔者的 Red Flag 6.0 为例，依次键入下列命令。

$ cd /usr/bin
$ ./assistant-qt4

一般的，Qt Assistant 运行起来的效果如图 5-18 所示

图 5-18 Qt4 Assistant

2.使用方法

其实读者朋友如果用过 Windows 上微软出品的 MSDN 的话，就会发现 Qt4 Assistant 的 界面布局与 MSDN 十分相似，操作方法也是大同小异，很容易上手。

(1) 界面布局

图示出了 Qt Assistant 的界面布局结构，它通常分为 3 个部分，最上面是主窗口，左 侧下面是内容索引窗口，右侧下面是主浏览区。

主浏览区

图 5-19 Qt4 Assistant 界面功能分布

(2) 菜单和工具栏

表 5-7 示出了 Qt Assistant 主要菜单项的功用。

表 5-7 Qt Assistant 菜单项

表 5-8 示出了导航工具栏的功用。

表 5-8 Qt Assistant 导航工具栏

名称和图标	功能
	后退
	前进
	登录 Qt 主页
	同步目录

表 5-9 示出了文件和编辑工具栏的功用。

表 5-9 Qt Assistant 文件和编辑工具栏

名称和图标	功能
	复制选中的文本
	打印
	在文本中查找

表 5-10 示出了查看工具栏的功用。

表 5-10 Qt Assistant 查看工具栏

名称和图标	功能
	放大
	缩小
	正常大小

(3) 使用内容索引窗口

默认情况下，内容索引窗口分为 3 个标签页，分别是“内容”、“索引”和“书签”，如图 5-20 所示。其中最常用的是前两个。

图 5-20 内容索引窗口

内容标签页分成了 5 个大类，分别对应到 Qt Assistant 操作、Qt Designer 操作、Qt Linguist 操作、QMake 使用、Qt 参考文档和例子这几项内容。

如果你能确定你在使用和开发中遇到的问题属于哪种类别的时候，使用 “内容”标签 页是合适和方便的，你只需点击选取某个大类，然后在展开的树形列表中选中某一个具体类 别，双击即可在右面的“主浏览区”内阅读详细的内容，如图 5-21 所示的是你想查看如何 使用 qmake 工具的情形。

图 5-21 使用内容标签页

可以看到，在主浏览区的内容也是分层次管理起来的，读者可以根据需要进行操作。

(4) 使用“索引”标签页 “索引”标签页是使用频率很高的，因为好多时候我们并不能准确定位出现的问题是属于哪一类的情况，这时候，使用 “索引”标签页，如图 5-22 所示，在“查找”编辑框内输入你的问题或是问题概述或是包含的几个字母都可以， Qt Assistant 将列出所有符合你 的需求的类别，选中你觉得合适的类别，双击它即可在右面的主浏览区内查阅相关内容。

比如我们想浏览 Qt Demo 的情况，在编辑框内输入 qtde，这时 Qt Assistant 已经智能 的显示出了相关的索引结果，然后我们选中 qtdemo，双击它，就可以在右面的主浏览区内 查看了。

图 5-22 使用索引标签页

(5) 使用“标签”标签页

“标签”标签页也是经常会用到的，当你某次查询时觉得某条资料很有用，希望下次 再来使用，就可以使用“标签”。一个书签页的情形如图 5-23 所示。

图 5-23 使用“标签”标签页

注意在窗口的左下角有一个蓝色的【添加】按钮和一个红色的【移除】按钮，它们就 是用作添加和删除书签的，你可能还注意到在右边的主浏览区内有一个 【搜索】标签页，下 面就结合这两者的使用说一下如何添加和移除标签 。

第 1 步，在右边的主浏览区内的“搜索”编辑栏内输入你想输入的字符，比如输入 qt，那么主浏览区将会把与 qt 相关的所有条目罗列出来，如图 5-24 所示

图 5-24 输入关键词进行搜索

第 2 步，你需要选中一个条目（图中蓝色的是条目），比如条目中的第 2 项，如图 5-

25 所示，系统将跳转到相应的页面

图 5-25 选中一个条目，跳转到相应界面

第 3 步，点击【添加】按钮，Qt Assistant 将弹出“添加书签”对话框，请使用者添 加书签，如图 5-26 所示。

高级配置按钮

图 5-26 添加书签对话框

如果没有特别要求，就可以在对话框上点击 【确定】按钮，添加书签，如图 5-27 所示。

图 5-27 添加书签后的情形

如果还需要进一步定制书签，那就这样做：

第 1 步，点击【添加书签】对话框上点击那个带加号形状的按钮， 对话框将伸展开来，显示进一步的配置选项，如图 5-28 所示。

图 5-28 定制书签第 1 步－点击＋号按钮

第 2 步，点击【新建文件夹】按钮，这时默认建立了一个名为“新建文件夹”的标签类别，这个过程分别如图 5-29 和图 5-30 所示。

图 5-29 定制书签第 2 步－点击【新建文件夹】按钮

图 5-30 建立好的书签文件夹

第 3 步，在你新建立的文件夹上点击鼠标右键，弹出配置菜单，你可以选择 【删除文 件夹】或是【重命名文件夹】，如图 5-31 所示

图 5-31 第 3 步－配置文件夹

第 4 步，选择【重命名文件夹】后，输入你想定义的文件夹名称，如图 5-32 所 示。

图 5-32 重命名文件夹

第 5 步，点击【确定】按钮，Qt Assistant 将为你建立一个标签，如图 5-33 所 示。

图 5-33 建立好的标签页

第 6 步，依据标签进行检索。在左侧建立好的标签页上双击， Qt Assistant 将跳转到 对应的页面，如图 5-34 所示。

图 5-34 依据标签进行检索

第 7 步，删除标签页。选中建立好的标签，然后点击 【删除】按钮，即可删除标签； 也可以选中建立好的文件夹，然后点击 【删除按钮】，系统会出现提示信息，选择【是】按 钮即可删除整个文件夹下的所有标签，如图 5-35 所示。

图 5-35 删除文件夹下的书签

至此，关于 Qt Assistant 的使用方法就讲解完了。Qt Assistant 在编程实践中经常会 用到，必须熟练掌握。