64 Star 180 Fork 34

qtguide / qtguide

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
ch02-06.htm 24.32 KB
一键复制 编辑 原始数据 按行查看 历史
qtguide 提交于 2015-04-29 22:22 . ch3.0
<!DOCTYPE html>
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type">
<title>ch02-06</title>
<link href="css/style.css" rel="stylesheet" type="text/css">
<link rel="stylesheet" href="thumbnailviewer.css" type="text/css">
<script src="thumbnailviewer.js" type="text/javascript">
/***********************************************
* Image Thumbnail Viewer Script- © Dynamic Drive (www.dynamicdrive.com)
* This notice must stay intact for legal use.
* Visit http://www.dynamicdrive.com/ for full source code
***********************************************/
</script> </head>
<body>
<div class="os1">2.6 Qt帮助文档</div>
<br>
之前讲过一些 Qt 的简单知识,比如 qSleep 函数是 Qt 单元测试的函数,并且在名字空间 QTest 里,不仅需要包含头文件,还需要在 pro
文件里加一个 Qt 模块 testlib。那这些知识从来学来的呢?这就是 Qt 帮助文档的用途了。Qt
帮助文档非常细致而全面,应有尽有,是非常不错的自学教材。因为 Qt
帮助文档太多,所以难以都翻译成中文,即使翻译了一部分,翻译花的时间太多,翻译更新的时效性也难以保证,所以还是得看英文帮助为主。本节介绍 Qt 助手和
Qt 帮助文档的使用,学会基本的文档运用方式。<br>
<br>
<div class="os2">2.6.1 Qt 助手</div>
<br>
点击开始菜单--&gt;Qt 5.4.0--&gt;5.4--&gt;MinGW 4.9 (32-bit)--&gt;Assistant,或者从 Qt
命令行里执行 assistant 命令,都可以打开独立的 Qt 助手程序,这就是帮助文档的浏览查阅软件,并且可以添加新的 Qt 相关文档。首先介绍一下
Qt 助手的界面:<br>
<center><img src="images/ch02/ch02-06-01.png" alt="assistant1" width="800"></center>
Qt 助手是典型的 Qt 主窗口程序,上方是菜单栏和工具栏(默认显示的叫导航工具栏),最下面的是状态栏。Qt
助手界面与常见的网页浏览器功能非常类似,概略介绍一下几个菜单:<br>
<ul>
<li>文件:可以新建多个标签页,同时打开多个文档页面,还可设置文档页面属性,打印帮助页面。</li>
<li>编辑:在当前打开页面复制文本或查找文本,以及 Qt 助手自身的首选项编辑。</li>
<li>查看:文档页面显示的放大缩小,显示各个功能窗口(内容、索引、书签、搜索、打开页列表)或工具栏(过滤器工具栏、地址工具栏、书签工具栏)。</li>
<li>前往:类似网页浏览器的前进、后退、主页,有区别的是同步目录菜单项,如果通过索引或搜索查找打开的帮助页,不知道该页面位于哪个目录树里和目录路
径,可以点击同步目录,定位该帮助页在目录树里的路径。</li>
<li>书签:添加打开的页面到书签菜单栏或书签工具栏,管理书签等。</li>
<li>帮助:关于 Qt 助手版本信息。</li>
</ul>
默认显示的工具栏是导航工具栏,在菜单查看--&gt;工具栏里可以找到其他三个工具栏,或者右击工具栏或菜单栏空白处,邮件菜单也可以设置显示哪些工具栏。导航
工具栏里按钮功能在菜单栏里都有对应菜单项,“同步目录”按钮就是菜单“前往”--&gt;“同步目录”菜单项一样的功能。“Find in
Text”按钮就是“编辑”菜单里的对应项,快捷键 Ctrl+F,注意查找当前页文本的查找栏不是弹窗的,而是位居底部状态栏上面。
在本页检索到的关键词会用黄色背景高亮显示出来,查找栏可以通过点击左边红叉按钮关闭,可以按快捷键 Ctrl+F
再次显示。导航工具栏的其他按钮意义都很简单直白,如前进、后退、主页、复制、打印、放大、缩小、正常大小等,就不多作说明了。<br>
<br>
介绍完边边角角,我们来看看左边的导航窗口,左边导航窗口分两部分,上方的是四个选项卡式的子窗口:内容、索引、书签和搜索。下方的是当前打开的文档页面。导航窗
口下方的打开文档列表窗口一目了然,对于上面四个子窗口需要解释一下:<br>
<ul>
<li>内容:显示 Qt 帮助文档的目录树,每一个文档树的根对应一个 qch 文件(Qt Compressed Help
file),对于本教程安装的 Qt 开发环境,这些 qch 文件位于 Qt安装目录/Qt5.4.0/Docs/Qt-5.4/
文件夹里,这个文件夹不仅有一堆 *.qch 文件,还有一堆子文件夹,子文件夹名字与 qch 文件名字是对应的,子文件夹保存 qch
文件的快速索引数据。</li>
<li>索引:qch 文件里每篇帮助页都有快速索引,索引的内容一般有帮助页标题、Qt
模块名、类名/名字空间、成员变量/属性、成员函数、枚举类型、宏定义等等,通过输入索引关键词,就可以快速找到相关的文档页面。这些快速索引数据保存位置就是刚才讲的
Qt安装目录/Qt5.4.0/Docs/Qt-5.4/ 的子文件里。</li>
<li>书签:可以按快捷键
Ctrl+D,保存当前页为书签,书签保存位置分两类,一类是在书签菜单栏的菜单项显示,另一类是在书签工具栏里显示。可以右击菜单栏或工具栏空白处,在右
键菜单选择显示书签工具栏。</li>
<li>搜索:这个是对所有 Qt 文档页面进行全文搜索,对于快速索引找不到的关键词,可以在全文检索子窗口里查找。</li>
</ul>
在本小节第一张图可以看到帮助页内部的结构,主要有帮助页的标题、目录树路径、前一篇和后一篇链接、帮助页内部目录、页面分节小标题、正文内容等,图上标注的
比较清楚,就不再赘述了。下面看看 Qt 助手的完全体界面显示:<br>
<center><img src="images/ch02/ch02-06-02.png" alt="assistant2" width="800"></center>
Qt 助手的过滤器工具栏,是指筛选文档目录树的根,就是只看某一个 qch 文件里的内容,上图 Unfiltered 是默认的不做任何过滤。地址工具栏显示
Qt 帮助页的内部链接地址,这个链接地址只在 Qt 帮助系统(Qt 助手和 QtCreator 帮助插件)里面有效。书签工具栏是用户保存的书签页,书签页
的默认保存名字是“帮助页的标题 | 所在文档根名字”。<br>
上图左侧显示的搜索子窗口,里面可以选择高级搜索模式,支持多种不同的关键词匹配方式。<br>
上图最下方状态栏之上的是当前页面文本查找栏,找到的关键词会高亮显示。<br>
对于独立的 Qt 助手程序界面暂时先介绍这些,下面看看 QtCreator 集成的助手插件。<br>
<br>
<div class="os2">2.6.2 QtCreator 集成的帮助系统</div>
<br>
QtCreator 作为集成开发环境,打开这一个工具等于打开所有的工具,QtCreator
除了自带设计师插件,还带有助手插件,可以随时查看帮助文档。QtCreator 的助手插件有两种工作方式,第一种是以 QtCreator
的帮助模式出现,打 开 QtCreator,点击左边“帮助”,如下图所示:<br>
<center><img src="images/ch02/ch02-06-03.png" alt="assistant3" width="800"></center>
界面与独立的 Qt 助手程序差不多,主要是工具栏的区别。QtCreator 左边是分栏窗口,上面分栏子窗口的默认是 Contents
视图,对应助手独立程序左侧的“内容”窗口,在该子窗口标题栏位置(其实是工具栏)可以选择当前视图,总共有四个:<br>
<ul>
<li>Bookmarks:对应 Qt 助手独立程序的“书签”,保存的文档书签页面。</li>
<li>Contents:对应 Qt 助手独立程序的“内容”,即帮助文档目录树。</li>
<li> Index:对应 Qt 助手独立程序的“索引”,对帮助文档进行快速索引。</li>
<li> Search:对应 Qt 助手独立程序的“搜索”,对帮助文档进行全文搜索。</li>
</ul>
分栏窗口的工具栏还有两个分别是“添加分栏”和“关闭分栏”按钮,可以添加分栏显示上面枚举的多个视图。如果要关闭全部边栏,可以点击 QtCreator
菜单“控件”--&gt;“Hide SideBar”隐藏边栏;如果边栏被全部关闭了,那么可以点击 QtCreator 菜单“控件”--&gt;“Show
SideBar”重新显示边栏。<br>
左侧分栏下方的子窗口是打开页面列表(Open Pages),也可以切换显示的视图,与左边上面子窗口的功能差不多,只是默认显示的视图不一样。<br>
右边区域都是当前打开的帮助页面,页面上方的区域是其工具栏,有一排按钮,功能分别是:<br>
<ul>
<li>主页:回到帮助文档主页,这里默认是 QtCreator 文档主页。</li>
<li>后退:回到上一个显示的页面。</li>
<li>前进:与后退相反,进入下一个页面。</li>
<li>添加书签:保存当前显示的帮助页面到书签视图(Bookmarks)里。</li>
<li>打开页面列表:与左侧打开的页面列表(Open Pages)是对应的关系,可以选择显示已打开的页面。</li>
<li>过滤文档根:在帮助文档目录树里,筛选一个文档根,查看其内容,默认“未过滤”是显示所有文档根。</li>
</ul>
QtCreator 的帮助文档内容和 Qt
助手独立程序的帮助文档内容是一样的,这两个程序都可以查阅帮助文档,页面内容也是一样的。二者的帮助文档目录树有一丁点不一样的,最后的 2.6.4
小节会提到。<br>
<br>
现在来看看 QtCreator 助手插件的第二种工作方式,先进入“欢迎”模式,打开上一节的 testbug 项目,然后自动进入“编辑”模式。<br>
在“编辑”模式,边栏上半部分项目视图里打开 widget.cpp ,在构造函数里选中 qSleep 函数名,然后按快捷键
F1,看到在“编辑”模式里集成的智能感知帮助页面:<br>
<center><img src="images/ch02/ch02-06-04.png" alt="assistant4" width="800"></center>
如上图所示,QtCreator 的“编辑”模式里,可以根据选中的函数名、变量名、类名等名称,按 F1
之后自动打开智能感知帮助页面,会自动根据编辑器里的名称查询帮助文档,如果找到对应的文档,会自动高亮显示出来。这是非常好用的功能,如果不知道类或对象有什么函数,选
择名称,按 F1 会直接进入该类的帮助文档,查找文档特别方便。<br>
智能感知页面上方是它的工具栏。工具栏第一个按钮“Go to Help Mode”是进入 QtCreator
的帮助模式。工具栏剩下的按钮分别是主页、后退、前进、添加书签,最右边的叉号是关闭。<br>
关于 QtCreator 和 Qt 助手独立程序的界面就介绍这么多,这些工具用多了就熟悉了。下面介绍怎么查询和运用帮助文档,因为帮助文档都是英文的,所以
学好英文还是有必要的。<br>
<br>
<div class="os2">2.6.3 帮助文档运用</div>
<br>
对于帮助文档查阅运用,首先是要知道自己想达到什么目的、实现什么功能,然后先可以用谷歌百度搜索关键词,得到可能的模块名、类名、函数名,再用 Qt
助手的索引或搜索功能找到具体的文档和示例代码。就拿上一节的睡眠函数举例,通常猜都猜得到跟 sleep 单词有关系,然后去 Qt 助手索引里查找:<br>
<center><img src="images/ch02/ch02-06-05.png" alt="sleep1" width="800"></center>
如上图所示,在索引栏输入 sleep 之后出来好几个函数以及常量。先讲讲 Qt 一般的命名规则:<br>
<ul>
<li>类名、枚举类型/常量、名字空间等名称都是首字母大写,名字里单词首字母都大写,比如 Qt::Key_Sleep ,这里的 Qt
是名字空间,Key_Sleep 是 Qt 名字空间里的常量。</li>
<li>类的属性/成员变量、成员函数、静态函数等名称一般以小写字母单词打头,名称里第二个单词开始用大写首字母,如 setText 函数。</li>
<li>全局函数以及名字空间里的全局函数通常以 q 打头,后面接首字母大写的英文单词,比如 qSleep 函数,qAbs 函数(求绝对值),另外在
&lt;QtGlobal&gt; 头文件包含了一堆全局的类型、函数、宏等。</li>
<li>全局的宏定义是单词字母全部大写,单词之间用下划线分隔,如 QT_VERSION(版本号 0xMMNNPP,MM = major,NN =
minor,PP = patch,比如 0x050400)、Q_OS_WIN32(仅在 Windows 操作系统里定义)。</li>
</ul>
对于上图里的函数名、常量名可以对比上面规则,基本是一致的,msleep、sleep、usleep
几个成员函数名称很短,只能算一个单词,所以都是小写字母。对于 void QTest::​qSleep(int ms) 一行,怎么知道 QTest
是类名还是函数名呢?<br>
可以直接拖动页面到顶上面,或者点击示例代码里的绿色 QTest 字样(注意示例代码明确用了 QTest:: 前缀!),打开链接,看到类似下面的帮助内容:<br>
<center><img src="images/ch02/ch02-06-06.png" alt="sleep2" width="800"></center>
查看 QTest 帮助页面开头的描述和该页面的标题,可以知道它是一个名字空间,根据右边的页内目录,可以看到它里面定义了一堆类、类型、函数、宏,另外还有
QTest 名字空间的详细描述,可以点击右边的“Detailed Description”或者帮助页第一段的“More ...”查看详细描述。在
QTest 帮助页顶头的简要描述之后,紧接着的就是该名字空间的头文件以及使用时需要的 Qt 模块,到这里就可以弄清楚我们使用 qSleep
函数时需要的一切依赖和步骤:<br>
<ul>
<li>①包含头文件:#include &lt;QTest&gt;</li>
<li> ②pro文件里添加需要的模块:QT += testlib</li>
<li>③代码里调用函数:QTest::qSleep(250);</li>
</ul>
其他 Qt 名字空间或类里面的函数用法都是类似的,一般都是上面示范的三个步骤,熟悉之后用起来就很方便。<br>
<br>
对于上图里的 Qt::Key_Sleep,这是个键盘按键定义,有些多媒体键盘带有休眠按键,该按键对应这个常量定义。
QStyle::SH_ToolTip_FallAsleepDelay 这个定义不管它,是工具提示风格里的。剩下三个函数的声明如下图所示:<br>
<center><img src="images/ch02/ch02-06-07.png" alt="sleep3" width="800"></center>
<ul>
<li>msleep:毫秒级睡眠,是 QThread 类的公开静态成员函数。</li>
<li>sleep:秒级睡眠,也是 QThread 类的公开静态成员函数。</li>
<li>usleep:微秒级睡眠,也是 QThread 类的公开静态成员函数。</li>
</ul>
这三个是静态成员函数,说明与具体对象无关,可以直接在代码里使用,如 QThread::sleep(1) 。QThread 类位于核心模块 core
里面,所以不需要额外添加 Qt 模块,包含它的头文件 &lt;QThread&gt; 就行了。使用 QThread 类里的睡眠函数要比 QTest
名字空间里的函数方便一些,而且功能也丰富一些。在本节练习里,可以试试 QThread 类里的三个睡眠函数。<br>
<br>
<div class="os2">2.6.4 常见的帮助文档</div>
<br>
上面大致介绍了 Qt 助手和 QtCreator 里的助手插件,以及帮助文档的查询和运用。接下来稍微宏观一点看看帮助文档的概貌。Qt
帮助文档大致可以分为两类:一类是 Qt 类库本身的文档,一般以模块名字为文档目录根,如 Qt Core、Qt GUI、Qt Widgets
等等。第二类是 Qt 开发工具的使用手册(Manual),如 QMake Manual、Qt Assistant Manual、Qt Designer
Manual 等。本章里的内容主要是借助一些简单例子,教大家熟悉一些 Qt
的开发工具,关于这些开发工具的详细使用说明,都可以在对应的文档目录根里找到,如果希望进一步了解 Qt 开发工具,可以直接查看对应的帮助手册。<br>
<br>
我们先处理 2.6.2 小节挖的坑,如果有读者比较细心,可以发现 Qt 助手独立程序的文档根,比 QtCreator 帮助模式里的文档根少了一个,就是
QtCreator 自己的帮助手册 Qt Creator Manual 。因为 Qt 开发框架和 QtCreator
是分别编译打包的,二者的文档位置不一样,Qt 助手独立程序默认情况下没有去找寻 QtCreator 的使用手册。我们可以手动添加一下,打开 Qt
助手独立程序,菜单“编辑”--&gt;“首选项”,进入首选项编辑对话框,选择“文档”:<br>
<center><img src="images/ch02/ch02-06-08.png" alt="docs"></center>
点击“添加”按钮,进入 Qt安装目录/Tools/QtCreator/share/doc/qtcreator 文件夹里,看到两个帮助文件:<br>
<center><img src="images/ch02/ch02-06-09.png" alt="adddoc"></center>
一般添加第一个 qtcreator.qch 就够了,这个是 QtCreator 的使用手册。第二个 qtcreator-dev.qch 是
QtCreator 自身的开发文档,如果要为 QtCreator
开发插件,就可以参考这个文档。我们先添加第一个,等待添加好,点击“OK”,可以在“内容”窗口里最下面找到新的“Qt Creator Manual
3.3.0”:<br>
<center><img src="images/ch02/ch02-06-10.png" alt="creatormanual" width="800"></center>
现在就可以在 Qt 助手独立程序里直接查找 QtCreator 的文档了。如果以后有类似的 qch 帮助文档,可以如法炮制,添加到 Qt 助手的文档目录
里面。<br>
<br>
添加好 QtCreator 文档之后,现在来枚举常见的 Qt 工具手册和 Qt 库的基本模块文档,并简要介绍一下:<br>
<br>
<table class="tabel">
<tbody>
<tr>
<td style="width: 160px;"><b>QMake Manual</b></td>
<td> 核心工具 qmake 帮助手册,含有其使用方式及 pro 文件格式等。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Assistant Manual</b></td>
<td> Qt 助手帮助手册,2.6 节内容就源于此。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Designer Manual</b></td>
<td> Qt 设计师帮助手册,2.3 节内容源于这个手册。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Linguist Manual</b></td>
<td> Qt 语言家帮助手册,程序的多国语言支持可以查阅这个手册。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Creator Manual</b></td>
<td> 集成开发环境 QtCreator 的帮助手册,2.4 节和 2.5 节内容分别对应这个手册的 User Interface 和
Debugging 帮助页。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt 5.4.0 Reference Documentation</b></td>
<td> Qt 开发文档总纲,含有 Qt 模块列表、类列表、函数列表、类型列表、名字空间列表等,还有非常多的编译生成、调试等各类文档。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Core</b></td>
<td> 核心模块文档,元对象系统、属性系统、对象模型、对象树、信号和槽、资源系统、多线程、文件处理、XML读写等方面文档。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt GUI</b></td>
<td> 底层绘图模块,图形用户界面组件的基础类,包括 OpenGL。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Widgets</b></td>
<td> 大量的窗口类、控件类,用于构建常规的窗体程序。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Multimedia</b></td>
<td> 音频处理、视频处理、收音机、摄像头等功能。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Multimedia Widgets</b></td>
<td> 用于 Qt Multimedia 模块功能显示的窗体和控件。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Network</b></td>
<td> 网络编程模块,如 TCP、UDP、组播等。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt SQL</b></td>
<td> 数据库编程模块,可以连接 SQLite、MySQL、PostgreSQL等数据库。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Test</b></td>
<td> 单元测试模块,用于测试开发好的 Qt 程序或库的运行效率。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt WebKit</b></td>
<td> 新实现的基于 WebKit2 的类,并带有 QML API。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt WebKit Widgets</b></td>
<td> WebKit1 和 从 Qt4 传承而来的基于 QWidget 的 WebKit 窗体。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt QML</b></td>
<td> 支持 QML 和 JavaScript 的基本类。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Quick</b></td>
<td> 新的基于 QML 语言的编程框架,一般用于手机等移动设备系统的用户界面开发。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Quick Controls</b></td>
<td> Qt Quick 基本控件模块。 </td>
</tr>
<tr class="d1">
<td style="width: 160px;"><b>Qt Quick Dialogs</b></td>
<td> Qt Quick 对话框模块。 </td>
</tr>
<tr>
<td style="width: 160px;"><b>Qt Quick Layouts</b></td>
<td> Qt Quick 界面布局模块。 </td>
</tr>
</tbody>
</table>
<br>
上表列出了常见的五个工具手册,Qt 5.4.0 Reference Documentation 是总纲性质的文档,之后的 15 个 Qt
基本模块都在它的范围之内。从 Qt Core 到 Qt WebKit 等,本教程会都涉及到,最后的 Qt QML 和 Qt Quick
的模块,本教程不打算讲,因为本教程是针对传统桌面操作系统的,而 Qt QML/Quick
是针对手机等移动设备操作系统定制的,暂时不在本教程范围之内。Qt 除了 15 个基本模块,还有大量扩展模块,有些是针对手机应用的,有些是针对特定操作系统
或特定硬件的,本教程暂时也不考虑这些附加的模块。关于帮助文档的介绍先到这,以后还会经常用到的。<br>
<br>
<div class="practice">
<table>
<tbody>
<tr>
<td><img src="images/pics/practice.png" alt="tip"></td>
<td> <b>练习</b> </td>
</tr>
</tbody>
</table>
① 在 QtCreator 里打开上一节的 testbug 项目,替换 Widget 类构造函数里的 QTest::qSleep 为 QThread
类里的睡眠函数,可以把 QThread 里的三个睡眠函数都尝试一下,注意睡眠时间的单位(s,ms,us)。<br>
② 在 Qt 助手里搜索关键词 windeployqt ,找到该工具的帮助页面,尝试使用该工具发布前面几节的 exe 程序。可以参考帖子:<br>
Qt官方开发环境生成的exe发布方式--使用windeployqt<br>
<a href="http://tieba.baidu.com/p/3730103947" target="new">http://tieba.baidu.com/p/3730103947</a>
</div>
<br>
<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td style="width: 40%;">
<div style="text-align: center;"> <a href="ch02-05.htm"><img class="pic"
style="width: 32px; height: 32px;" alt="prev" src="images/pics/prev.png"></a></div>
</td>
<td style="width: 20%;">
<div style="text-align: center;"><a href="contents.htm"><img class="pic"
style="width: 32px; height: 32px;" alt="contents" src="images/pics/contents.png"></a></div>
</td>
<td style="width: 40%;">
<div style="text-align: center;"> <a href="ch03-00.htm"><img class="pic"
style="width: 32px; height: 32px;" alt="next" src="images/pics/next.png"></a></div>
</td>
</tr>
</tbody>
</table>
</body>
</html>
HTML
1
https://gitee.com/qtguide/qtguide.git
git@gitee.com:qtguide/qtguide.git
qtguide
qtguide
qtguide
master

搜索帮助