首页 > 编程笔记 > Qt笔记 阅读:1,584

Qt Assistant(Qt助手)查阅帮助文档(非常详细)

之前讲过一些简单的 Qt 知识,比如 qSleep 函数是 Qt 单元测试的函数,并且在名字空间 QTest 里,不仅需要包含头文件,还需要在 pro 文件里加一个 Qt 模块 testlib。那这些知识从来学来的呢?这就是 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 Assistant(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 Creator 集成的帮助系统

界面与独立的 Qt 助手程序差不多,主要是工具栏的区别。Qt Creator 左边是分栏窗口,上面分栏子窗口的默认是“目录”视图,对应助手独立程序左侧的“内容”窗口,在该子窗口标题栏位置(其实是工具栏)可以选择当前视图,总共有四个:
分栏窗口的工具栏还有两个分别是“添加分栏”和“关闭分栏”按钮,可以添加分栏显示上面列举的多个视图。如果要关闭全部边栏,可以点击 QtCreator 菜单“控件”-->“Hide SideBar”隐藏边栏;如果边栏被全部关闭了,那么可以点击 QtCreator 菜单“控件”-->“Show SideBar”重新显示边栏。

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

右边区域都是当前打开的帮助页面,页面上方的区域是其工具栏,有一排按钮,功能分别是:
Qt Creator 的帮助文档内容和 Qt 助手独立程序的帮助文档内容是一样的,这两个程序都可以查阅帮助文档,页面内容也是一样的。

选中代码进入帮助页面

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

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

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

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

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

帮助文档运用

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

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

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

打断一下思路,我们先来讲讲 Qt 一般的命名规则:
对于上图里的函数名、常量名可以对比上面规则,基本是一致的,msleep、sleep、usleep 都是成员函数,它们的名称很短,只能算一个单词,所以都是小写字母。

对于右侧void QTest::​qSleep(int ms)一行,怎么知道 QTest 是类名还是函数名呢?

可以直接滚动页面到顶端,或者点击示例代码里的绿色 QTest 字样(注意示例代码明确用了QTest::前缀),打开链接,看到类似下面的帮助内容:

查看 QTest 帮助页面开头的描述和该页面的标题,可以知道它是一个名字空间,根据上边的页内目录,可以看到它里面定义了一堆类、类型、函数、宏,另外还有 QTest 名字空间的详细描述,可以点击上边的“Detailed Description”或者帮助页第一段的“More ...”查看详细描述。

在 QTest 帮助页顶头的简要描述之后,紧接着的就是该名字空间的头文件以及使用时需要的 Qt 模块,到这里就可以弄清楚我们使用 qSleep 函数时需要的一切依赖和步骤:
其他 Qt 名字空间或类里面的函数用法都是类似的,一般都是上面示范的三个步骤,熟悉之后用起来就很方便。

对于上图里的 Qt::Key_Sleep,这是个键盘按键定义,有些多媒体键盘带有休眠按键,该按键对应这个常量定义。 QStyle::SH_ToolTip_FallAsleepDelay 这个定义不管它,是工具提示风格里的。

剩下三个函数的声明如下图所示:

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

所有教程

优秀文章