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 菜单项

菜单	说明
文件	提供文档设置、打印等相关操作操作命令
编辑	提供首选项设置、复制文本、查找等操作命令
查看	提供工具栏、各个标签页的显隐设置，显示比例设置等操作命令
前往	提供登录 Qt 主页以及在 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，双击它，就可以在右面的主浏览区内查看了。