Qt学习(10)

Qt学习（10）—Qt帮助文档

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

1、Qt助手

        点击开始菜单-->Qt 5.5.0-->5.5-->MinGW 4.9 (32-bit)-->Assistant，或者从 Qt 命令行里执行 assistant 命令，都可以打开独立的 Qt 助手程序，这就是帮助文档的浏览查阅软件，并且可以添加新的 Qt 相关文档。首先介绍一下 Qt 助手的界面：

        Qt 助手是典型的 Qt 主窗口程序，上方是菜单栏和工具栏（默认显示的叫导航工具栏），最下面的是状态栏。Qt 助手界面与常见的网页浏览器功能非常类似，概略介绍一下几个菜单：

• 文件：可以新建多个标签页，同时打开多个文档页面，还可设置文档页面属性，打印帮助页面。
• 编辑：在当前打开页面复制文本或查找文本，以及 Qt 助手自身的首选项编辑。
• 查看：文档页面显示的放大缩小，显示各个功能窗口（内容、索引、书签、搜索、打开页列表）或工具栏（过滤器工具栏、地址工具栏、书签工具栏）。
• 前往：类似网页浏览器的前进、后退、主页，有区别的是同步目录菜单项，如果通过索引或搜索查找打开的帮助页，不知道该页面位于哪个目录树里和目录路径，可以点击同步目录，定位该帮助页在目录树里的路径。
• 书签：添加打开的页面到书签菜单栏或书签工具栏，管理书签等。
• 帮助：关于 Qt 助手版本信息。

        默认显示的工具栏是导航工具栏，在菜单查看-->工具栏里可以找到其他三个工具栏，或者右击工具栏或菜单栏空白处，邮件菜单也可以设置显示哪些工具栏。导航    工具栏里按钮功能在菜单栏里都有对应菜单项，“同步目录”按钮就是菜单“前往”-->“同步目录”菜单项一样的功能。“Find in Text”按钮就是“编辑”菜单里的对应项，快捷键 Ctrl+F，注意查找当前页文本的查找栏不是弹窗的，而是位居底部状态栏上面。在本页检索到的关键词会用黄色背景高亮显示出来，查找栏可以通过点击左边红叉按钮关闭，可以按快捷键 Ctrl+F 再次显示。导航工具栏的其他按钮意义都很简单直白，如前进、后退、主页、复制、打印、放大、缩小、正常大小等，就不多作说明了。
        介绍完边边角角，我们来看看左边的导航窗口，左边导航窗口分两部分，上方的是四个选项卡式的子窗口：内容、索引、书签和搜索。下方的是当前打开的文档页面。导航窗口下方的打开文档列表窗口一目了然，对于上面四个子窗口需要解释一下：

• 内容：显示 Qt 帮助文档的目录树，每一个文档树的根对应一个 qch 文件（Qt Compressed Help file），对于本教程安装的 Qt 开发环境，这些 qch 文件位于 Qt安装目录/Qt5.5.0/Docs/Qt-5.5/文件夹里，这个文件夹不仅有一堆 *.qch 文件，还有一堆子文件夹，子文件夹名字与 qch 文件名字是对应的，子文件夹保存 qch文件的快速索引数据。
• 索引：qch 文件里每篇帮助页都有快速索引，索引的内容一般有帮助页标题、Qt 模块名、类名/名字空间、成员变量/属性、成员函数、枚举类型、宏定义等等，通过输入索引关键词，就可以快速找到相关的文档页面。这些快速索引数据保存位置就是刚才讲的 Qt安装目录/Qt5.5.0/Docs/Qt-5.5/ 的子文件里。
• 书签：可以按快捷键 Ctrl+D，保存当前页为书签，书签保存位置分两类，一类是在书签菜单栏的菜单项显示，另一类是在书签工具栏里显示。可以右击菜单栏或工具栏空白处，在右键菜单选择显示书签工具栏。
• 搜索：这个是对所有 Qt 文档页面进行全文搜索，对于快速索引找不到的关键词，可以在全文检索子窗口里查找。

        在本小节第一张图可以看到帮助页内部的结构，主要有帮助页的标题、目录树路径、前一篇和后一篇链接、帮助页内部目录、页面分节小标题、正文内容等，图上标注的比较清楚，就不再赘述了。下面看看 Qt 助手的完全体界面显示：

       Qt 助手的过滤器工具栏，是指筛选文档目录树的根，就是只看某一个 qch 文件里的内容，上图 Unfiltered 是默认的不做任何过滤。地址工具栏显示 Qt 帮助页的内部链接地址，这个链接地址只在 Qt 帮助系统（Qt 助手和 Qt Creator 帮助插件）里面有效。书签工具栏是用户保存的书签页，书签页的默认保存名字是“帮助页的标题 | 所在文档根名字”。
        上图左侧显示的搜索子窗口，里面可以选择高级搜索模式，支持多种不同的关键词匹配方式。
        上图最下方状态栏之上的是当前页面文本查找栏，找到的关键词会高亮显示。
        对于独立的 Qt 助手程序界面暂时先介绍这些，下面看看 QtCreator 集成的助手插件。

2、Qt Creator 集成的帮助系统

      Qt Creator 作为集成开发环境，打开这一个工具等于打开所有的工具，Qt Creator 除了自带设计师插件，还带有助手插件，可以随时查看帮助文档。Qt Creator 的助手插件有两种工作方式，第一种是以 Qt Creator 的帮助模式出现，打开 Qt Creator，点击左边“帮助”，如下图所示：

界面与独立的 Qt 助手程序差不多，主要是工具栏的区别。Qt Creator 左边是分栏窗口，上面分栏子窗口的默认是 Contents 视图，对应助手独立程序左侧的“内容”窗口，在该子窗口标题栏位置（其实是工具栏）可以选择当前视图，总共有四个：

• Bookmarks（书签）：对应 Qt 助手独立程序的“书签”，保存的文档书签页面。
• Contents（目录）：对应 Qt 助手独立程序的“内容”，即帮助文档目录树。
• Index（索引）：对应 Qt 助手独立程序的“索引”，对帮助文档进行快速索引。
• Search（查找）：对应 Qt 助手独立程序的“搜索”，对帮助文档进行全文搜索。

       分栏窗口的工具栏还有两个分别是“添加分栏”和“关闭分栏”按钮，可以添加分栏显示上面枚举的多个视图。如果要关闭全部边栏，可以点击 Qt Creator 菜单“控件”-->“Hide SideBar”隐藏边栏；如果边栏被全部关闭了，那么可以点击 Qt Creator 菜单“控件”-->“Show  SideBar”重新显示边栏。左侧分栏下方的子窗口是打开页面列表（Open Pages），也可以切换显示的视图，与左边上面子窗口的功能差不多，只是默认显示的视图不一样。右边区域都是当前打开的帮助页面，页面上方的区域是其工具栏，有一排按钮，功能分别是：

• 主页：回到帮助文档主页，这里默认是 QtCreator 文档主页。
• 后退：回到上一个显示的页面。
• 前进：与后退相反，进入下一个页面。
• 添加书签：保存当前显示的帮助页面到书签视图（Bookmarks）里。
• 打开页面列表：与左侧打开的页面列表（Open Pages）是对应的关系，可以选择显示已打开的页面。
• 过滤文档根：在帮助文档目录树里，筛选一个文档根，查看其内容，默认“未过滤”是显示所有文档根。

          Qt  Creator 的帮助文档内容和 Qt 助手独立程序的帮助文档内容是一样的，这两个程序都可以查阅帮助文档，页面内容也是一样的。二者的帮助文档目录树有一丁点不一样的，最后的 第 4 小节会提到。

        现在来看看 Qt Creator 助手插件的第二种工作方式，先进入“欢迎”模式，打开上一节的 testbug 项目，然后自动进入“编辑”模式。在“编辑”模式，边栏上半部分项目视图里打开 widget.cpp ，在构造函数里选中 qSleep 函数名，然后按快捷键 F1，看到在“编辑”模式里集成的智能感知帮助页面：

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

3、帮助文档运用

        对于帮助文档查阅运用，首先是要知道自己想达到什么目的、实现什么功能，然后先可以用谷歌百度搜索关键词，得到可能的模块名、类名、函数名，再用 Qt 助手的索引或搜索功能找到具体的文档和示例代码。就拿上一节的睡眠函数举例，通常猜都猜得到跟 sleep 单词有关系，然后去 Qt 助手索引里查找：

 

如上图所示，在索引栏输入 sleep 之后出来好几个函数以及常量。先讲讲 Qt 一般的命名规则：

• 类名、枚举类型/常量、名字空间等名称都是首字母大写，名字里单词首字母都大写，比如 Qt::Key_Sleep ，这里的 Qt是名字空间，Key_Sleep 是 Qt 名字空间里的常量。
• 类的属性/成员变量、成员函数、静态函数等名称一般以小写字母单词打头，名称里第二个单词开始用大写首字母，如 setText 函数。
• 全局函数以及名字空间里的全局函数通常以 q 打头，后面接首字母大写的英文单词，比如 qSleep 函数，qAbs 函数（求绝对值），另外在 <QtGlobal> 头文件包含了一堆全局的类型、函数、宏等。
• 全局的宏定义是单词字母全部大写，单词之间用下划线分隔，如 QT_VERSION（版本号 0xMMNNPP，MM = major，NN = minor，PP = patch，比如 0x050400）、Q_OS_WIN32（仅在 Windows 操作系统里定义）。

         对于上图里的函数名、常量名可以对比上面规则，基本是一致的，msleep、sleep、usleep 几个成员函数名称很短，只能算一个单词，所以都是小写字母。对于 void QTest::​qSleep(int ms) 一行，怎么知道 QTest 是类名还是函数名呢？可以直接拖动页面到顶上面，或者点击示例代码里的绿色 QTest 字样（注意示例代码明确用了 QTest:: 前缀！），打开链接，看到类似下面的帮助内容：

        查看 QTest 帮助页面开头的描述和该页面的标题，可以知道它是一个名字空间，根据右边的页内目录，可以看到它里面定义了一堆类、类型、函数、宏，另外还有     QTest 名字空间的详细描述，可以点击右边的“Detailed Description”或者帮助页第一段的“More ...”查看详细描述。在 QTest 帮助页顶头的简要描述之后，紧接着的就是该名字空间的头文件以及使用时需要的 Qt 模块，到这里就可以弄清楚我们使用 qSleep 函数时需要的一切依赖和步骤：

• ①包含头文件：#include <QTest>
• ②pro文件里添加需要的模块：QT += testlib
• ③代码里调用函数：QTest::qSleep(250);

        其他 Qt 名字空间或类里面的函数用法都是类似的，一般都是上面示范的三个步骤，熟悉之后用起来就很方便。
        对于上图里的 Qt::Key_Sleep，这是个键盘按键定义，有些多媒体键盘带有休眠按键，该按键对应这个常量定义。QStyle::SH_ToolTip_FallAsleepDelay 这个定义不管它，是工具提示风格里的。剩下三个函数的声明如下图所示：

 

 

• msleep：毫秒级睡眠，是 QThread 类的公开静态成员函数。
• sleep：秒级睡眠，也是 QThread 类的公开静态成员函数。
• usleep：微秒级睡眠，也是 QThread 类的公开静态成员函数。

      这三个是静态成员函数，说明与具体对象无关，可以直接在代码里使用，如 QThread::sleep(1) 。QThread 类位于核心模块 core 里面，所以不需要额外添加 Qt 模块，包含它的头文件 <QThread> 就行了。使用 QThread 类里的睡眠函数要比 QTest 名字空间里的函数方便一些，而且功能也丰富一些。在本节练习里，可以试试 QThread 类里的三个睡眠函数。

4、常见帮助文档

       上面大致介绍了 Qt 助手和 Qt Creator 里的助手插件，以及帮助文档的查询和运用。接下来稍微宏观一点看看帮助文档的概貌。Qt帮助文档大致可以分为两类：一类是 Qt 类库本身的文档，一般以模块名字为文档目录根，如 Qt Core、Qt GUI、Qt Widgets 等等。第二类是 Qt 开发工具的使用手册（Manual），如 QMake Manual、Qt Assistant Manual、Qt Designer  Manual 等。本章里的内容主要是借助一些简单例子，教大家熟悉一些 Qt 的开发工具，关于这些开发工具的详细使用说明，都可以在对应的文档目录根里找到，如果希望进一步了解 Qt 开发工具，可以直接查看对应的帮助手册。
        我们先处理 第2 小节挖的坑，如果有读者比较细心，可以发现 Qt 助手独立程序的文档根，比 Qt Creator 帮助模式里的文档根少了一个，就是 Qt Creator 自己的帮助手册 Qt Creator Manual 。因为 Qt 开发框架和 Qt Creator 是分别编译打包的，二者的文档位置不一样，Qt 助手独立程序默认情况下没有去找寻 QtCreator 的使用手册。我们可以手动添加一下，打开 Qt 助手独立程序，菜单“编辑”-->“首选项”，进入首选项编辑对话框，选择“文档”：

点击“添加”按钮，进入 Qt安装目录/Tools/QtCreator/share/doc/qtcreator 文件夹里，看到两个帮助文件：

一般添加第一个 qtcreator.qch 就够了，这个是 Qt Creator 的使用手册。第二个 qtcreator-dev.qch 是 Qt Creator 自身的开发文档，如果要为 Qt Creator 开发插件，就可以参考这个文档。我们先添加第一个，等待添加好，点击“OK”，可以在“内容”窗口里最下面找到新的“Qt Creator Manual  3.4.2”：

现在就可以在 Qt 助手独立程序里直接查找 Qt Creator 的文档了。如果以后有类似的 qch 帮助文档，可以如法炮制，添加到 Qt 助手的文档目录 里面。

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

QMake Manual	核心工具 qmake 帮助手册，含有其使用方式及 pro 文件格式等。
Qt Assistant Manual	Qt 助手帮助手册，Qt学习(10)节内容就源于此。
Qt Designer Manual	Qt 设计师帮助手册，Qt学习（7）节内容源于这个手册。
Qt Linguist Manual	Qt 语言家帮助手册，程序的多国语言支持可以查阅这个手册。
Qt Creator Manual	集成开发环境 QtCreator 的帮助手册，Qt学习（8） 节和 Qt学习（9） 节内容分别对应这个手册的 User Interface 和 Debugging 帮助页。
Qt 5.5.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.5.0 Reference Documentation 是总纲性质的文档，之后的 15 个 Qt 基本模块都在它的范围之内。从 Qt Core 到 Qt WebKit 等，本教程会都涉及到，最后的 Qt  QML 和 Qt  Quick 的模块，本教程不打算讲，因为本教程是针对传统桌面操作系统的，而 Qt QML/Quick 是针对手机等移动设备操作系统定制的，暂时不在本教程范围之内。Qt 除了 15 个基本模块，还有大量扩展模块，有些是针对手机应用的，有些是针对特定操作系统 或特定硬件的，本教程暂时也不考虑这些附加的模块。关于帮助文档的介绍先到这，以后还会经常用到的。