Qt帮助文档使用方法

Qt 帮助文档非常细致而全面，应有尽有，是非常不错的自学教材。因为 Qt 帮助文档太多，所以难以都翻译成中文，即使翻译了一部分，翻译花的时间太多，翻译更新的时效性也难以保证，所以还是得看英文帮助为主。本节介绍 Qt 助手和 Qt 帮助文档的使用，学会基本的文档运用方式。

Qt Assistant（Qt 助手）

在开始菜单中找到“Qt 5.9.0-->5.9-->MinGW 5.3.0 (32-bit)-->Assistant”，或者在 Qt 命令行工具中运行 assistant 命令，都可以打开独立的 Qt 助手程序，这就是帮助文档的浏览查阅软件，并且可以添加新的 Qt 相关文档。

首先介绍一下 Qt 助手的界面：

Qt 助手是典型的 Qt 主窗口（MainWindow）程序，上方是菜单栏和工具栏（默认显示的叫导航工具栏），最下面的是状态栏。

Qt 助手界面与常见的网页浏览器功能非常类似，概略介绍一下几个菜单：

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

默认显示的工具栏是导航工具栏，在菜单“查看-->工具栏”里可以找到其他三个工具栏，或者右击工具栏或菜单栏空白处，邮件菜单也可以设置显示哪些工具栏。

导航工具栏里按钮功能在菜单栏里都有对应菜单项，“同步目录”按钮就是菜单“前往-->同步目录”菜单项一样的功能。“Find in Text”按钮就是“编辑”菜单里的对应项，快捷键 Ctrl+F，注意查找当前页文本的查找栏不是弹窗的，而是位居底部状态栏上面。 在本页检索到的关键词会用黄色背景高亮显示出来，查找栏可以通过点击左边红叉按钮关闭，可以按快捷键 Ctrl+F 再次显示。导航工具栏的其他按钮意义都很简单直白，如前进、后退、主页、复制、打印、放大、缩小、正常大小等，就不多作说明了。

介绍完边边角角，我们来看看左边的导航窗口，左边导航窗口分两部分，上方的是四个选项卡式的子窗口：内容、索引、书签和搜索。下方的是当前打开的文档页面。

导航窗口下方的打开文档列表窗口一目了然，对于上面四个子窗口需要解释一下：

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

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

Qt Creator 集成的帮助系统

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

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

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

分栏窗口的工具栏还有两个分别是“添加分栏”和“关闭分栏”按钮，可以添加分栏显示上面列举的多个视图。如果要关闭全部边栏，可以点击 QtCreator 菜单“控件”-->“Hide SideBar”隐藏边栏；如果边栏被全部关闭了，那么可以点击 QtCreator 菜单“控件”-->“Show SideBar”重新显示边栏。

左侧分栏下方的子窗口是打开页面列表（Open Pages），也可以切换显示的视图，与左边上面子窗口的功能差不多，只是默认显示的视图不一样。

右边区域都是当前打开的帮助页面，页面上方的区域是其工具栏，有一排按钮，功能分别是：

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

Qt Creator 的帮助文档内容和 Qt 助手独立程序的帮助文档内容是一样的，这两个程序都可以查阅帮助文档，页面内容也是一样的。

选中代码进入帮助页面

现在来看看 QtCreator 助手插件的第二种工作方式，先进入“欢迎”模式，打开上一节的 testbug 项目，然后自动进入“编辑”模式。

在“编辑”模式，边栏上半部分项目视图里打开 widget.cpp ，在构造函数里选中 qSleep 函数名，然后按快捷键 F1，看到在“编辑”模式里集成的智能感知帮助页面：

如上图所示，在 QtCreator 的“编辑”模式里，可以根据选中的函数名、变量名、类名等，按 F1 键之后自动打开智能感知帮助页面，会自动根据编辑器里的名称查询帮助文档，如果找到对应的文档，就跳转进去。这是非常好用的功能，如果不知道类或对象有什么函数，选择名称，按 F1 键会直接进入该类的帮助文档，查找文档特别方便。

智能感知页面上方是它的工具栏：工具栏第一个按钮“Open in Help Mode”表明当前处于 QtCreator 的帮助模式，工具栏剩下的按钮分别是主页、后退、前进、添加书签、打开模式和关闭。

关于 QtCreator 和 Qt 助手独立程序的界面就介绍这么多，这些工具用多了就熟悉了。下面介绍怎么查询和运用帮助文档，因为帮助文档都是英文的，所以学好英文还是有必要的。

帮助文档运用

在使用帮助文档之前，首先是要知道自己想达到什么目的、实现什么功能，然后先可以用谷歌百度搜索一下关键词，得到可能的模块名、类名、函数名，再用 Qt 助手的索引或搜索功能找到具体的文档和示例代码。

就拿前面提到的睡眠函数举例，通常猜都猜得到跟 sleep 单词有关系，然后去 Qt 助手索引里查找：

如上图所示，在索引栏输入 sleep 之后出来好几个函数以及常量，双击鼠标即可进入相关页面。

打断一下思路，我们先来讲讲 Qt 一般的命名规则：

• 类名、枚举类型/常量、名字空间等名称都是首字母大写，名字里单词首字母都大写，比如 Qt::Key_Sleep ，这里的 Qt 是名字空间，Key_Sleep 是 Qt 名字空间里的常量。
• 类的属性/成员变量、成员函数、静态函数等名称一般以小写字母单词打头，名称里第二个单词开始用大写首字母，如 setText 函数。
• 全局函数以及名字空间里的全局函数通常以 q 打头，后面接首字母大写的英文单词，比如 qSleep 函数，qAbs 函数（求绝对值），另外在 头文件包含了一堆全局的类型、函数、宏等。
• 全局的宏定义是单词字母全部大写，单词之间用下划线分隔，如 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
• 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 类里的睡眠函数要比 QTest 名字空间里的函数方便一些，而且功能也丰富一些。