2.6 Qt帮助文档

之前讲过一些 Qt 的简单知识，比如 qSleep 函数是 Qt 单元测试的函数，并且在名字空间 QTest 里，不仅需要包含头文件，还需要在 pro 文件里加一个 Qt 模块 testlib。那这些知识从来学来的呢？这就是 Qt 帮助文档的用途了。Qt 帮助文档非常细致而全面，应有尽有，是非常不错的自学教材。因为 Qt 帮助文档太多，所以难以都翻译成中文，即使翻译了一部分，翻译花的时间太多，翻译更新的时效性也难以保证，所以还是得看英文帮助为主。本节介绍 Qt 助手和 Qt 帮助文档的使用，学会基本的文档运用方式。

2.6.1 Qt 助手

点击开始菜单-->Qt 5.4.0-->5.4-->MinGW 4.9 (32-bit)-->Assistant，或者从 Qt 命令行里执行 assistant 命令，都可以打开独立的 Qt 助手程序，这就是帮助文档的浏览查阅软件，并且可以添加新的 Qt 相关文档。首先介绍一下 Qt 助手的界面：
assistant1
Qt 助手是典型的 Qt 主窗口程序，上方是菜单栏和工具栏（默认显示的叫导航工具栏），最下面的是状态栏。Qt 助手界面与常见的网页浏览器功能非常类似，概略介绍一下几个菜单：
默认显示的工具栏是导航工具栏，在菜单查看-->工具栏里可以找到其他三个工具栏，或者右击工具栏或菜单栏空白处，邮件菜单也可以设置显示哪些工具栏。导航 工具栏里按钮功能在菜单栏里都有对应菜单项，“同步目录”按钮就是菜单“前往”-->“同步目录”菜单项一样的功能。“Find in Text”按钮就是“编辑”菜单里的对应项，快捷键 Ctrl+F，注意查找当前页文本的查找栏不是弹窗的，而是位居底部状态栏上面。 在本页检索到的关键词会用黄色背景高亮显示出来，查找栏可以通过点击左边红叉按钮关闭，可以按快捷键 Ctrl+F 再次显示。导航工具栏的其他按钮意义都很简单直白，如前进、后退、主页、复制、打印、放大、缩小、正常大小等，就不多作说明了。

介绍完边边角角，我们来看看左边的导航窗口，左边导航窗口分两部分，上方的是四个选项卡式的子窗口：内容、索引、书签和搜索。下方的是当前打开的文档页面。导航窗 口下方的打开文档列表窗口一目了然，对于上面四个子窗口需要解释一下：
在本小节第一张图可以看到帮助页内部的结构，主要有帮助页的标题、目录树路径、前一篇和后一篇链接、帮助页内部目录、页面分节小标题、正文内容等，图上标注的 比较清楚，就不再赘述了。下面看看 Qt 助手的完全体界面显示：
assistant2
Qt 助手的过滤器工具栏，是指筛选文档目录树的根，就是只看某一个 qch 文件里的内容，上图 Unfiltered 是默认的不做任何过滤。地址工具栏显示 Qt 帮助页的内部链接地址，这个链接地址只在 Qt 帮助系统（Qt 助手和 QtCreator 帮助插件）里面有效。书签工具栏是用户保存的书签页，书签页 的默认保存名字是“帮助页的标题 | 所在文档根名字”。
上图左侧显示的搜索子窗口，里面可以选择高级搜索模式，支持多种不同的关键词匹配方式。
上图最下方状态栏之上的是当前页面文本查找栏，找到的关键词会高亮显示。
对于独立的 Qt 助手程序界面暂时先介绍这些，下面看看 QtCreator 集成的助手插件。

2.6.2 QtCreator 集成的帮助系统

QtCreator 作为集成开发环境，打开这一个工具等于打开所有的工具，QtCreator 除了自带设计师插件，还带有助手插件，可以随时查看帮助文档。QtCreator 的助手插件有两种工作方式，第一种是以 QtCreator 的帮助模式出现，打 开 QtCreator，点击左边“帮助”，如下图所示：
assistant3
界面与独立的 Qt 助手程序差不多，主要是工具栏的区别。QtCreator 左边是分栏窗口，上面分栏子窗口的默认是 Contents 视图，对应助手独立程序左侧的“内容”窗口，在该子窗口标题栏位置（其实是工具栏）可以选择当前视图，总共有四个：
分栏窗口的工具栏还有两个分别是“添加分栏”和“关闭分栏”按钮，可以添加分栏显示上面枚举的多个视图。如果要关闭全部边栏，可以点击 QtCreator 菜单“控件”-->“Hide SideBar”隐藏边栏；如果边栏被全部关闭了，那么可以点击 QtCreator 菜单“控件”-->“Show SideBar”重新显示边栏。
左侧分栏下方的子窗口是打开页面列表（Open Pages），也可以切换显示的视图，与左边上面子窗口的功能差不多，只是默认显示的视图不一样。
右边区域都是当前打开的帮助页面，页面上方的区域是其工具栏，有一排按钮，功能分别是：
QtCreator 的帮助文档内容和 Qt 助手独立程序的帮助文档内容是一样的，这两个程序都可以查阅帮助文档，页面内容也是一样的。二者的帮助文档目录树有一丁点不一样的，最后的 2.6.4 小节会提到。

现在来看看 QtCreator 助手插件的第二种工作方式，先进入“欢迎”模式，打开上一节的 testbug 项目，然后自动进入“编辑”模式。
在“编辑”模式，边栏上半部分项目视图里打开 widget.cpp ，在构造函数里选中 qSleep 函数名，然后按快捷键 F1，看到在“编辑”模式里集成的智能感知帮助页面：
assistant4
如上图所示，QtCreator 的“编辑”模式里，可以根据选中的函数名、变量名、类名等名称，按 F1 之后自动打开智能感知帮助页面，会自动根据编辑器里的名称查询帮助文档，如果找到对应的文档，会自动高亮显示出来。这是非常好用的功能，如果不知道类或对象有什么函数，选 择名称，按 F1 会直接进入该类的帮助文档，查找文档特别方便。
智能感知页面上方是它的工具栏。工具栏第一个按钮“Go to Help Mode”是进入 QtCreator 的帮助模式。工具栏剩下的按钮分别是主页、后退、前进、添加书签，最右边的叉号是关闭。
关于 QtCreator 和 Qt 助手独立程序的界面就介绍这么多，这些工具用多了就熟悉了。下面介绍怎么查询和运用帮助文档，因为帮助文档都是英文的，所以 学好英文还是有必要的。

2.6.3 帮助文档运用

对于帮助文档查阅运用，首先是要知道自己想达到什么目的、实现什么功能，然后先可以用谷歌百度搜索关键词，得到可能的模块名、类名、函数名，再用 Qt 助手的索引或搜索功能找到具体的文档和示例代码。就拿上一节的睡眠函数举例，通常猜都猜得到跟 sleep 单词有关系，然后去 Qt 助手索引里查找：
sleep1
如上图所示，在索引栏输入 sleep 之后出来好几个函数以及常量。先讲讲 Qt 一般的命名规则：
对于上图里的函数名、常量名可以对比上面规则，基本是一致的，msleep、sleep、usleep 几个成员函数名称很短，只能算一个单词，所以都是小写字母。对于 void QTest::​qSleep(int ms) 一行，怎么知道 QTest 是类名还是函数名呢？
可以直接拖动页面到顶上面，或者点击示例代码里的绿色 QTest 字样（注意示例代码明确用了 QTest:: 前缀！），打开链接，看到类似下面的帮助内容：
sleep2
查看 QTest 帮助页面开头的描述和该页面的标题，可以知道它是一个名字空间，根据右边的页内目录，可以看到它里面定义了一堆类、类型、函数、宏，另外还有 QTest 名字空间的详细描述，可以点击右边的“Detailed Description”或者帮助页第一段的“More ...”查看详细描述。在 QTest 帮助页顶头的简要描述之后，紧接着的就是该名字空间的头文件以及使用时需要的 Qt 模块，到这里就可以弄清楚我们使用 qSleep 函数时需要的一切依赖和步骤：
其他 Qt 名字空间或类里面的函数用法都是类似的，一般都是上面示范的三个步骤，熟悉之后用起来就很方便。

对于上图里的 Qt::Key_Sleep，这是个键盘按键定义，有些多媒体键盘带有休眠按键，该按键对应这个常量定义。 QStyle::SH_ToolTip_FallAsleepDelay 这个定义不管它，是工具提示风格里的。剩下三个函数的声明如下图所示：
sleep3
这三个是静态成员函数，说明与具体对象无关，可以直接在代码里使用，如 QThread::sleep(1) 。QThread 类位于核心模块 core 里面，所以不需要额外添加 Qt 模块，包含它的头文件 <QThread> 就行了。使用 QThread 类里的睡眠函数要比 QTest 名字空间里的函数方便一些，而且功能也丰富一些。在本节练习里，可以试试 QThread 类里的三个睡眠函数。

2.6.4 常见的帮助文档

上面大致介绍了 Qt 助手和 QtCreator 里的助手插件，以及帮助文档的查询和运用。接下来稍微宏观一点看看帮助文档的概貌。Qt 帮助文档大致可以分为两类：一类是 Qt 类库本身的文档，一般以模块名字为文档目录根，如 Qt Core、Qt GUI、Qt Widgets 等等。第二类是 Qt 开发工具的使用手册（Manual），如 QMake Manual、Qt Assistant Manual、Qt Designer Manual 等。本章里的内容主要是借助一些简单例子，教大家熟悉一些 Qt 的开发工具，关于这些开发工具的详细使用说明，都可以在对应的文档目录根里找到，如果希望进一步了解 Qt 开发工具，可以直接查看对应的帮助手册。

我们先处理 2.6.2 小节挖的坑，如果有读者比较细心，可以发现 Qt 助手独立程序的文档根，比 QtCreator 帮助模式里的文档根少了一个，就是 QtCreator 自己的帮助手册 Qt Creator Manual 。因为 Qt 开发框架和 QtCreator 是分别编译打包的，二者的文档位置不一样，Qt 助手独立程序默认情况下没有去找寻 QtCreator 的使用手册。我们可以手动添加一下，打开 Qt 助手独立程序，菜单“编辑”-->“首选项”，进入首选项编辑对话框，选择“文档”：
docs
点击“添加”按钮，进入 Qt安装目录/Tools/QtCreator/share/doc/qtcreator 文件夹里，看到两个帮助文件：
adddoc
一般添加第一个 qtcreator.qch 就够了，这个是 QtCreator 的使用手册。第二个 qtcreator-dev.qch 是 QtCreator 自身的开发文档，如果要为 QtCreator 开发插件，就可以参考这个文档。我们先添加第一个，等待添加好，点击“OK”，可以在“内容”窗口里最下面找到新的“Qt Creator Manual 3.3.0”：
creatormanual
现在就可以在 Qt 助手独立程序里直接查找 QtCreator 的文档了。如果以后有类似的 qch 帮助文档，可以如法炮制，添加到 Qt 助手的文档目录 里面。

添加好 QtCreator 文档之后，现在来枚举常见的 Qt 工具手册和 Qt 库的基本模块文档，并简要介绍一下：

QMake Manual 核心工具 qmake 帮助手册，含有其使用方式及 pro 文件格式等。
Qt Assistant Manual Qt 助手帮助手册，2.6 节内容就源于此。
Qt Designer Manual Qt 设计师帮助手册，2.3 节内容源于这个手册。
Qt Linguist Manual Qt 语言家帮助手册，程序的多国语言支持可以查阅这个手册。
Qt Creator Manual 集成开发环境 QtCreator 的帮助手册，2.4 节和 2.5 节内容分别对应这个手册的 User Interface 和 Debugging 帮助页。
Qt 5.4.0 Reference Documentation Qt 开发文档总纲，含有 Qt 模块列表、类列表、函数列表、类型列表、名字空间列表等，还有非常多的编译生成、调试等各类文档。
Qt Core 核心模块文档，元对象系统、属性系统、对象模型、对象树、信号和槽、资源系统、多线程、文件处理、XML读写等方面文档。
Qt GUI 底层绘图模块，图形用户界面组件的基础类，包括 OpenGL。
Qt Widgets 大量的窗口类、控件类，用于构建常规的窗体程序。
Qt Multimedia 音频处理、视频处理、收音机、摄像头等功能。
Qt Multimedia Widgets 用于 Qt Multimedia 模块功能显示的窗体和控件。
Qt Network 网络编程模块，如 TCP、UDP、组播等。
Qt SQL 数据库编程模块，可以连接 SQLite、MySQL、PostgreSQL等数据库。
Qt Test 单元测试模块，用于测试开发好的 Qt 程序或库的运行效率。
Qt WebKit 新实现的基于 WebKit2 的类，并带有 QML API。
Qt WebKit Widgets WebKit1 和 从 Qt4 传承而来的基于 QWidget 的 WebKit 窗体。
Qt QML 支持 QML 和 JavaScript 的基本类。
Qt Quick 新的基于 QML 语言的编程框架，一般用于手机等移动设备系统的用户界面开发。
Qt Quick Controls Qt Quick 基本控件模块。
Qt Quick Dialogs Qt Quick 对话框模块。
Qt Quick Layouts Qt Quick 界面布局模块。

上表列出了常见的五个工具手册，Qt 5.4.0 Reference Documentation 是总纲性质的文档，之后的 15 个 Qt 基本模块都在它的范围之内。从 Qt Core 到 Qt WebKit 等，本教程会都涉及到，最后的 Qt QML 和 Qt Quick 的模块，本教程不打算讲，因为本教程是针对传统桌面操作系统的，而 Qt QML/Quick 是针对手机等移动设备操作系统定制的，暂时不在本教程范围之内。Qt 除了 15 个基本模块，还有大量扩展模块，有些是针对手机应用的，有些是针对特定操作系统 或特定硬件的，本教程暂时也不考虑这些附加的模块。关于帮助文档的介绍先到这，以后还会经常用到的。

tip 练习
① 在 QtCreator 里打开上一节的 testbug 项目，替换 Widget 类构造函数里的 QTest::qSleep 为 QThread 类里的睡眠函数，可以把 QThread 里的三个睡眠函数都尝试一下，注意睡眠时间的单位（s，ms，us）。
② 在 Qt 助手里搜索关键词 windeployqt ，找到该工具的帮助页面，尝试使用该工具发布前面几节的 exe 程序。可以参考帖子：
Qt官方开发环境生成的exe发布方式--使用windeployqt
http://tieba.baidu.com/p/3730103947

prev
contents
next