对话框

对话框用于完成与用户的短暂会话，例如打开文件、选择颜色、输入比较简单的信息等。对话框也属于桌面环境中的顶层窗口，因此它具备标题栏、边框等外观。

QDialog作为对话框的公共基类，实现了一部分通用功能，包括以下方法成员。

1. exec：该方法将以模态窗口的方式打开对话框。exec方法调用后不会立即返回，除非对话框关闭，因此对话框在打开期间会阻断用户与其他窗口的交互。如果对话框是应用程序级别的，那么同一个应用程序中的其他窗口将无法使用，直到对话框关闭；如果对话框与某个窗口关联（该窗口成为对话框的父级)，那么只有当前窗口的交互行为被阻止，不会影响其他窗口的运行。
2. open：该方法是异步的，调用后立即返回。要获取对话框的操作结果，可以连接finished，或者 accepted、rejected 信号。
3. accept：对话框接受用户输入并隐藏。调用该方法会发出accepted信号。
4. reject：拒绝当前输入结果并隐藏对话框。调用该方法会发出rejected信号。
5. done：隐藏对话框并设置对话框的操作结果。调用该方法会使 QDialog对象发出 finished信号。

如果表示操作结果的整数值与QDialog.DialogCode枚举的某个成员相等，那么调用done方法后也会发出 accepted 或 rejected 信号。

13.1.1 示例：实现自定义对话框

由于 QDialog类已实现对话框的基础功能，而且 QDialog也是 QWidget的子类，因此要实现自定义的对话框，只需从QDialog类派生即可，其界面的布局方法与QWidget类相同。

本示例将实现一个使用QSpinBox组件输入整数值的对话框。具体步骤如下。

定义 CustDialog类，以 QDialog为基类。

getInput方法公开给外部代码调用，用于获取QSpinBox组件中输入的整数值。“确定”“取消”按钮的主要功能是设置对话框结果，因此将它们的 clicked 信号分别与 accept 和 reject 方法连接即可，当按钮被单击时会自动调用这些方法。

创建应用程序窗口（通过QWidget类），界面上添加一个按钮组件（QPushButton）和标签组件（QLabel）。

实例化 CustDialog 对话框类。

“输入整数值”按钮的 clicked 信号与 onClicked 函数连接。在 onClicked 函数中打开自定义对话框，并获取输入的整数值。

显示程序窗口。

运行示例程序后，单击窗口上的“输入整数值”按钮，将弹出如图13-1所示的对话框。

输入整数后，单击“确定”按钮隐藏对话框，返回到应用程序窗口，标签组件就会显示输入的值，如图13-2所示。

图 13-1、图 13-2

图 13-1 自定义对话框
图 13-2 已输入的整数值

13.1.2 示例：异步对话框

open方法在打开对话框后会立即返回，应用程序可以通过连接相应的信号来获取用户的操作结果。

例如，当对话框接受输入（如单击“确定”按钮）后会发出accepted信号。应用程序可以连接该信号，并做出响应。如果需要对操作结果进行复杂处理，可以连接finished信号。该信号带有一个int类型的参数，以表示操作结果。该值可以是 DialogCode枚举所定义的 Accepted 和 Rejected，也可以是开发者自定义的数值。

当QDialog类默认的信号（finished、accepted、rejected）不能满足开发需求时，可以从QDialog类派生出自定义类型，然后添加自定义处理，使应用程序能够从对话框中获取更多数据，例如用户选择的字体。

本示例将演示一个自定义对话框。对话框内允许用户输入姓名和年龄，当用户单击“确定”按钮后，对话框除发出默认的finished等事件外，还会发出自定义的dataReady信号。dataReady信号将传递用户输入的姓名和年龄。

CustDialog类的实现代码如下：

dataReady是自定义的信号，它带有两个参数——字符串类型和整数类型。为了实现在对话框确认时发出dataReady信号，上述代码重写了done方法。如果对话框的操作结果是Accepted，就发出dataReady信号，同时传递 QLineEdit 和 QSpinBox 组件的值。

下面的代码初始化应用程序窗口和自定义对话框。

应用程序窗口包含一个按钮和一个标签组件。按钮被单击后显示 CustDialog对话框，当对话框隐藏后，在标签组件中显示输入的数据。

运行示例程序，单击窗口上的“输入信息”按钮，打开如图13-3所示的对话框。

输入姓名与年龄后，单击“确定”按钮隐藏对话框，回到应用程序窗口。标签组件将显示已输入的内容，如图13-4所示。

图 13-3、图 13-4

图 13-3 自定义对话框
图 13-4 输入的内容

QInputDialog类提供一个可输入单个值的简易的对话框，支持的类型有浮点数、整数、字符串。

QInputDialog类通过InputMode枚举来确定输入模式，该枚举定义了以下成员。

1. TextInput：输入的内容是字符串类型。
2. IntInput： 输入整数值。
3. DoubleInput：输入的值是浮点数值。

QInputDialog类的公共成员可以依据InputMode枚举的值进行分组，详见表13-1。

另外，以下三个方法可以自定义对话框上显示的文本信息。

1. setLabelText：设置对话框内的输入提示文本，如“请输入用户名”。
2. setOkButtonText：为 OK按钮设置自定义文本，如“确定”。该按钮使对话框返回 Accepted操作结果。
3. setCancelButtonText：设置Cancel按钮所显示的文本，如“关闭”。该按钮会使对话框返回Rejected 操作结果。

13.2.1 示例：QInputDialog 的基本用法

本示例会在窗口中创建三个按钮，对应QInputDialog对话框的三种输入模式。当用户输入结束并单击“确定”按钮后，对话框将隐藏，并在窗口上显示所输入的内容。具体的实现步骤如下。

初始化程序窗口（使用QWidget类）。

程序窗口使用网格布局，第一列的三个行放置按钮组件。

第二列的三个行放置三个标签组件。

初始化 QInputDialog 对话框。

在初始化时，可以为整数、浮点数和字符串类型的输入值设置对应的参数（如setIntRange方法设置整数值的有效范围，setDoubleRange 方法设置浮点数值的范围)。整数值的输入使用的是 QSpinBox组件，浮点数值的输入使用的是QDoubleSpinBox组件，文本内容则用 QLineEdit组件输入。

分别连接三个按钮的 clicked 信号，通过 setInputMode 方法切换 QInputDialog 对话框的输入模式，然后显示对话框等待用户输入，最后显示输入的内容。

需要注意的是，切换输入模式，即调用 setInputMode方法一定要在 exec方法调用之前完成。

显示程序窗口。

运行示例程序，如图13-5所示。

单击“输入int数值”按钮，QInputDialog对话框打开，如图13-6所示。

输入整数值，然后单击“确定”按钮，回到主窗口。输入的内容会显示在按钮右边的标签组件上，如图13-7所示。

图 13-5、图 13-6、图 13-7

图 13-5 QInputDialog 示例程序的主窗口
图 13-6 输入对话框
图 13-7 显示输入的内容

13.2.2 QInputDialog 的信号

除了从QDialog类继承的信号（如 accepted、rejected)，QInputDialog类也定义了3 组信号。

1. doubleValueChanged与 doubleValueSelected:当输入模式为浮点数值时使用。
2. intValueChanged与intValueSelected:当输入模式为整数值时使用。
3. textValueChanged与 textValueSelected:当输入模式为文本时使用。

*ValueChanged信号表示对话框处于活动状态时，输入的内容改变时发出；而*ValueSelected信号表示对话框已经提交，用户最终输入的内容。

例如，以整数输入模式打开QInputDialog对话框。当用户输入3时，intValueChanged信号发出，参数值为3；接着用户输入0，即 QSpinBox组件内的现有值是 30，此时intValueChanged信号参数值为 30;用户继续输入0，此时intValueChanged信号的参数值为300。若此时用户输入完成，单击“确定”按钮，intValueSelected 信号发出，参数值为 300。

13.2.3 示例：实时显示输入内容

本示例通过连接 textValueChanged和textValueSelected信号，在程序主窗口上实时显示对话框中正在输入的内容。具体步骤如下。

初始化程序窗口。在窗口中添加一个按钮组件和一个标签组件。

初始化输入对话框，输入模式为文本。

连接按钮的 clicked信号，调用 open 方法显示对话框。

连接 QInputDialog 组件的 textValueChanged信号，更新标签组件上的文本，实时显示输入的内容。

连接textValueSelected信号，输入完毕后获取最终的文本。

连接rejected信号，当输入取消后清空标签组件的文本。

运行示例程序后，单击“请输入文本”按钮，打开输入对话框。在文本框中先输入“天”，此时会看到主窗口上显示“正在输入：天”，如图13-8所示。

接着输入“南”，主窗口上显示“正在输入：天南”，如图13-9所示。

随后输入“海北”，单击OK按钮完成输入，主窗口显示“输入完毕文本内容：天南海北”，如图 13-10 所示。

图 13-8、图 13-9、图 13-10

图 13-8 输入第一个字符
图 13-9 输入第二个字符
图 13-10 输入结束

13.2.4 示例：使用下拉列表框完成文本输入

在文本输入模式下，除了用键盘敲入内容，也可以从下拉列表中选择一项作为输入的文本。若希望用下拉列表框代替文本框，需要调用setComboBoxItems方法设置一个字符串列表，作为下拉列表框的数据来源。

本示例将实现：单击窗口上的按钮，打开输入对话框，然后从下拉列表框中选择一项作为输入的文本，最后输入文本显示在主窗口上。实现步骤如下。

初始化程序窗口。

在布局对象中添加一个按钮组件和一个标签组件。

初始化输入对话框。

调用 setComboBoxItems 方法设置下拉列表。

连接按钮组件的clicked信号。显示输入对话框，待完成输入后显示已输入文本。

运行示例程序，单击“请选择房间面积”按钮，打开输入对话框。从下拉列表框中选择一个选项，如图13-11所示。

单击“确定”按钮，回到程序窗口，显示输入的文本如图13-12所示。

图 13-11、图 13-12

图 13-11 从下拉列表中选择
图 13-12 显示输入文本

13.2.5 便捷方法

QInputDialog类提供了一组静态方法成员，可以直接调用，不需要创建QInputDialog类的实例。不同输入模式对应着不同的方法成员。

对于整数输入模式，应调用getInt方法，它的声明如下：

parent参数指定对话框的父级窗口。title参数指定对话框的标题栏文本。label参数设置对话框上的说明文本。value参数设置初始值（默认为0)。minValue参数指定最小值，maxValue参数指定最大值。

step参数指定内部 QSpinBox 组件的步长值，默认值为1。flags参数设置窗口标志（Qt.WindowType)。

value、minValue、maxValue、step、flags参数可以省略。

getInt方法返回两个值：第一个值是输入的内容；第二个是bool类型的值，表示对话框是否确认输入，如单击“确定”按钮则返回True。

对于浮点数输入模式，应调用getDouble方法，其声明如下：

parent、title、label等参数的含义与getInt方法相同，decimals参数指定浮点数值的精度（保留小数位)，默认是2。

对于文本输入模式，应调用getText方法，它的声明如下：

echo参数指定文本的呈现方式，默认为Normal。text参数设置初始文本，默认为空字符串。

inputMethodHints设置输入法的附加选项，默认为ImhNone，表示无须设置。例如，要禁止输入法自动切换英文大小写，可以指定ImhNoAutoUppercase。

另外，在文本输入模式下如果希望使用下拉列表框完成输入，还可以使用getItem方法：

items参数指定一个字符串列表，作为下拉列表框的数据来源。current参数指定下拉列表框中默认选择的项（索引)。editable参数指定下拉列表框是否允许编辑，如果允许，则用户可以手动输入内容；若禁止编辑，用户只能从列表中选择一项。其他参数的含义与getText方法相同。

13.2.6 示例：使用便捷方法打开输入对话框

本示例将演示getInt和getText方法的使用。窗口上有两个按钮组件，单击后分别调用getInt和getText方法打开输入对话框。输入结束后，通过标签组件显示输入内容。核心代码如下：

getInt方法返回的第一个值是用户输入的内容，第二个值表示输入是否被确认。因此，在显示输入结果时，需要判断第二个返回值是否为True。

运行示例程序，单击“输入整数”按钮，打开输入对话框。输入一个整数值后并确认，返回程序窗口，显示的输入结果如图13-13所示。

“输入文本”按钮的测试方法类似，此处不再赘述。

图 13-13

图13-13 显示已输入的整数值

QColorDialog提供用于选择颜色的对话框，返回QColor类型的对象。该对话框包含两个与用户当前选择的颜色相关的成员。

1. currentColor：返回当前被选中的颜色，调用 setCurrentColor 方法能以编程方式修改当前选定的颜色。
2. selectedColor：用户最终选择的颜色，前提是当用户已单击“确定”等按钮确认。

currentColor方法与 selectedColor方法所返回的颜色值可能相同，但含义不同。用户在确认对话框之前可能会选择红色，但在提交前发现选错了，于是又选择了蓝色。因此，在整个会话中，currentColor所返回的值由红色变成蓝色，而selectedColor方法返回的是用户最终选择的颜色。

currentColor 的值改变后，QColorDialog 对象会发出 currentColorChanged。当用户提交选择后，会发出 colorSelected 信号。

13.3.1 示例：设置文本颜色

本示例将使用QColorDialog对话框为 QLabel组件设置文本颜色。代码如下：

窗口中创建了一个按钮组件和一个标签组件。单击按钮后打开颜色对话框，确认选择后通过调色板修改标签组件的文本颜色。先调用 palette 方法获取原来的调色板数据，然后调用 setColor 修改颜色(QLabel 组件默认的颜色角色是 WindowText)。修改后调用 setPalette方法重新设置调色板。

运行示例程序，单击“选择颜色”按钮，打开选择颜色对话框，如图13-14所示。

选择好颜色后，单击OK按钮确认，QLabel组件的文本颜色就会发生改变，如图13-15所示。

图 13-14、图 13-15

图13-14 选择颜色对话框
图13-15 标签文本的颜色已更新

13.3.2 自定义颜色区域

颜色对话框在标准颜色之外提供了一个自定义颜色区域，如图 13-16 所示。用户可以将从取色器中选定的颜色添加到这个区域。自定义颜色区域的设置在多个 QColorDialog 实例之间共享，用户可以通过这个自定义区域快速选择自己所需要的颜色。开发人员也可以通过 QColorDialog 类公开的方法以编程方式操作自定义颜色区域。

图 13-16

图13-16 自定义颜色的区域

由于自定义颜色在QColorDialog实例之间共享，所以与自定义颜色区域相关的成员都是静态的。

要往自定义区域添加颜色，请调用setCustomColor方法，其声明如下：

index参数指的是自定义区域中颜色位置索引，第一个位置为0，第二个为1，等等。color参数设置颜色。如果要往自定义区域中所有位置设定颜色，最好先知道系统允许的颜色数量，避免index参数的值超出有效范围。customCount方法能获取到系统允许的自定义颜色数量，例如：

代码执行的结果为：

支持的自定义颜色数量：16表明当前系统允许设置16个自定义颜色。

下面的代码将设置4个自定义颜色：

当打开 QColorDialog对话框时，会看到如图13-17所示的界面。

图 13-17

图 13-17 4 个自定义颜色

13.3.3 示例：使用便捷方法

QColorDialog 类也公开了静态的 getColor 方法，不需要实例化 QColorDialog 类即可打开颜色对话框。getColor方法的声明如下：

initial参数设置打开对话框时的初始颜色，默认为白色。title参数指定对话框的标题，parent参数指定父级对象（一般是程序主窗口）。options参数指定对话框选项，一般可以忽略。返回值为QColor对象，如果用户放弃选择，那么 QColor 对象的 isValid 方法就会返回 False。

本示例的核心代码如下：

QPushButton组件被单击后，通过getColor方法打开颜色对话框，最后用选择的颜色填充QFrame组件的背景。

注意，QFrame组件要调用setAutoFillBackground方法并将参数设置为True，否则无法呈现背景色。

运行示例程序，然后单击“选择颜色”按钮，打开颜色对话框。确认选择后，QFrame组件的背景色会改变，如图13-18所示。

图 13-18

图 13-18 修改 QFrame 组件的背景色

QFileDialog类提供可以选择文件或目录的对话框。该对话框的工作模式可以通过setFileMode方法设置，参数的值由FileMode枚举定义。

1. AnyFile：不管文件是否已经存在都可以选择，此模式常用于保存文件对话框。
2. ExistingFile：选择单个文件，此文件必须是存在的。
3. Directory：可以选择目录和文件。在Windows系统中，选择目录的对话框中不支持文件选择。
4. ExistingFiles：选择多个已存在的文件。

当用户选择文件并确认对话框后，QFileDialog对象会发出 fileSelected（单个文件）和filesSelected（多个文件）信号。

13.4.1 示例：切换文件选择模式

本示例将实现单文件、多文件选择模式的切换。具体实现步骤如下。

初始化程序窗口，窗口使用网格布局。

添加 QPushButton、QLabel、QCheckBox 组件。QLabel 组件用于显示已选择的文件。

初始化 QFileDialog 对话框。

setNameFilter方法用于设置文件类型过滤器。过滤器可以筛选出哪些文件会显示在选项列表中。多个文件扩展名用空格分隔，多个过滤器之间用两个英文的分号分隔。过滤器前面的文本用于描述文件类型，如上述代码中的“MusicFiles”，括号中指定要显示在列表中的文件扩展名，如*.wav、*.mp3。

也可以使用setNameFilter方法，以列表方式添加过滤器。代码如下：

连接QPushButton 组件的 clicked信号，显示文件对话框。

连接 QCheckBox 组件的 toggled 信号。调用 QFileDialog 对象的 setFileMode 方法，根据QCheckBox的选择状态修改文件选择模式。

连接QFileDialog组件的 fileSelected信号。只有在单文件选择模式下才会发出。

连接QFileDialog组件的 filesSelected信号。当选择模式为多文件时发出。

多文件选择模式下，参数list是一个字符串列表，包含被选择文件的路径。

运行示例程序，当“选择多个文件”复选框处于未选中状态时，单击“打开”按钮，此时文件对话框只能选择一个文件：当“选择多个文件”复选框处于选中状态时，文件对话框可以同时选择多个文件。

13.4.2 示例：选择目录

本示例实现目录选择功能。调用 setFileMode方法并向参数赋值FileMode.Directory后，QFileDialog对话框允许选择目录对象（在Windows下，目录模式不显示文件)。

DemoWindow类的实现代码如下：

调用 setFileMode方法设置为目录模式后，可以使用 setDirectory方法设置一个默认目录——本示例默认选择用户文档目录。通过 QStandardPaths.StandardLocation.DocumentsLocation 可以得到文档目录的列表。列表中一般只包含一个路径（如果设置多个文档路径，会包含多个路径)。

运行示例程序后，单击“浏览目录”按钮，打开文件对话框，如图13-19所示，此时已自动选择“文档”目录。

选择一个目录，然后单击“选择文件夹”按钮，回到程序窗口，窗口上就会显示被选目录的路径，如图13-20所示。

13.4.3 便捷方法

QFileDialog与QColorDialog等类型一样，提供了一个静态方法，可直接调用。QFileDialog类的便捷方法如下。

选择文件。主要有两个方法：getOpenFileName与getOpenFileNames。

图 13-19、图 13-20

图 13-19目录列表
图13-20 显示被选择的目录

getOpenFileName方法用于选择单个文件，其声明如下：

caption参数设置对话框的标题，dir参数设置初始目录，filter参数设置过滤器，selectedFilter参数设置默认选择的过滤器，options参数设置对话框选项。该方法的返回值是包含两个元素的元组，第一个元素代表被选文件的路径，第二个元素代表选择文件时所使用的过滤器。

getOpenFileName方法的使用示例如下：

另一个方法是 getOpenFileNames，其声明如下：

各参数的含义与getOpenFileName方法相同，但getOpenFileNames方法可以选择多个文件，其返回值也是包含两个元素的元组。第一个元素是字符串列表，表示被选文件；第二个元素是当前使用的过滤器。

getOpenFileNames方法的示例代码如下：

选择目录。比较常用的是 getExistingDirectory 方法，声明如下：

各参数的含义与getOpenFileName相似，该方法返回目录的路径。使用示例如下：

保存文件。主要是getSaveFileName方法，其声明如下：

参数和返回值与 getOpenFileName 方法相同，但 getSaveFileName 方法获取的是保存文件的路径，该路径通常是不存在的新文件。因此，getSaveFileName方法允许选择不存在的文件路径。

getSaveFileName方法的使用示例如下：

上述代码中定义了三个过滤器（文本文件、HTML页面文件和XML文件)，默认选择XML文件，即选择的文件名默认追加.xml扩展名。

QFontDialog类提供一个允许用户选择字体的对话框。在初始化时，可以通过以下重载的构造函数设置默认字体（通过initial参数）。

currentFont方法返回的是用户当前选择（并不表示最终选择）的字体。调用setCurrentFont方法可以以编程方式设置当前字体，同时 QFontDialog 对象会发出 currentFontChanged 信号。

当用户确认选择后，可以访问 selectedFont方法获取最终被选择的字体，同时会发出 fontSelected信号。对于调用open方法打开对话框的方案，可以连接fontSelected信号来获取被选择的字体。

13.5.1 示例：使用新增的 open 方法

QFontDialog类除了从QDialog类继承的open方法，还新增了一个重载版本，其声明如下：

receiver参数表示接收消息的对象，一般可以指定程序窗口。member参数指定与fontSelected信号连接的方法。方法调用后会自动建立 fontSelected信号与member之间的连接；当QFontDialog 对话框确认后会自动解除与fontSelected信号的连接。

member参数以字符串的形式指定方法成员的名称(包括参数的类型)，同时需要SLOT函数进行转化，例如：

本示例将定义名为 TestWindow的窗口类。窗口上添加QLabel和QPushButton组件。当单击按钮时，初始化 QFontDialog 对象，用户确认后改变QLabel组件的字体。

TestWindow类的实现代码如下：

onFontSelected 方法与 QFontDialog 对象的 fontSelected信号建立连接。作为槽（Slot）方法，需要在声明方法时加上@Slot装饰器。

示例程序运行后，单击“选择字体”按钮，打开字体对话框，如图13-21所示。

单击OK按钮关闭对话框，QLabel组件的文本将应用被选择的字体，如图13-22所示。

图 13-21、图 13-22

图 13-21 字体对话框
图 13-22 应用被选择的字体

13.5.2 示例：使用便捷方法

QFontDialog类也公开了静态的便捷方法 getFont，直接调用可打开字体对话框并等待用户选择。

getFont方法的声明如下：

initial参数指定默认的字体。parent参数指定父级对象，通常是程序窗口。title参数设置对话框标题。options参数设置对话框选项。

getFont方法的返回值包含两个元素。第一个元素为 bool类型，若为True表示用户已确认选择，否则用户已放弃选择。第二个元素是所选择的字体对象，类型为QFont。

DemoWindow是本示例自定义的窗口类，其完整代码如下：

getFont方法的initial参数既可以使用QFont实例，也可以直接用字体名称，如本示例中的“宋体”。

运行示例程序后，在编辑框中输入测试内容，然后选中部分字符。单击“字体”按钮打开字体对话框。选择好字体后确认，编辑器中选定的字符就会应用新的字体了，如图13-23所示。

图 13-23

图 13-23 设置选定文本的字体

QDialogButtonBox组件提供一个承载按钮列表的容器，将它布局在自定义对话框中，可以更方便地创建按钮组。

QDialogButtonBox组件内部有两种排列按钮的方式——水平或垂直。可通过向构造函数传递Qt.Orientation枚举的值来指定按钮排列方向。如果 QDialogButtonBox 对象已经实例化，也可以调用setOrientation 方法修改。

13.6.1 按钮角色

实例化 QDialogButtonBox类后，可以调用 addButton 方法添加按钮。按钮角色由 ButtonRole 枚举定义，用来描述按钮在对话框中的功能。该枚举的成员如下。

1. InvalidRole：表示按钮不可用。使用该值会导致按钮被隐藏。
2. AcceptRole：表示接受对话框中的内容。
3. RejectRole：表示拒绝对话框中的内容。
4. DestructiveRole：舍弃状态，如“放弃”按钮，表示用户放弃当前在编辑的内容。
5. ActionRole：表示执行某项操作，这些操作可能会修改对话框中某些组件的值。
6. HelpRole：表示帮助按钮。
7. YesRole：代表“是”、Yes、Ok等按钮，表示用户接受对话框的内容，与Accept角色相似。
8. NoRole：代表“否”、No等按钮，表示用户拒绝对话框的内容，与Reject角色相似。
9. ResetRole：表示重置对话框中的组件状态，通常是清空文本框内的文本。
10. ApplyRole：代表“应用”、Apply等按钮。

ButtonRole枚举仅定义了按钮的角色，并未做任何处理。开发者需要根据实际情况响应其行为。

QDialogButtonBox 组件中任何按钮被单击后都会发出 clicked信号。该信号带有一个 QAbstractButton类型的参数，表示被单击的按钮引用。程序代码可以与clicked信号连接，然后根据按钮的角色来完成各自的功能。不过，QDialogButtonBox类在发出clicked信号后，会分析按钮的角色，做出特殊处理—发送额外的信号，具体如下。

1. 如果遇到 AcceptRole、YesRole角色的按钮，会发出 accepted信号。
2. 如果遇到 RejectRole、NoRole 角色的按钮，会发出 rejected信号。
3. 如果遇到 HelpRole角色的按钮，会发出 helpRequested 信号。

13.6.2 示例：使用按钮角色

本示例将演示按钮角色在QDialogButtonBox中的运用。

自定义对话框中的 QDialogButtonBox 对象包含 Yes 和 No 按钮，对应的是 accepted 和 rejected 信号。具体代码如下：

Yes按钮使用的角色是 YesRole，No按钮使用的角色是 NoRole。Yes按钮被单击后会使QDialogButtonBox 对象发出 accepted 信号，将该信号与对话框的 accept 方法连接后才能发挥作用。同理，No按钮会发出rejected信号，该信号也要与对话框的reject方法连接。

下面的代码实现程序窗口。

运行示例程序，单击“显示对话框”按钮，打开自定义的对话框，如图13-24所示。

单击任一按钮，关闭对话框。程序窗口将显示操作结果，如图13-25所示。

图 13-24、图 13-25

图 13-24 对话框中的 Yes 和 No 按钮
图 13-25 显示对话框结果

13.6.3 标准按钮

标准按钮将自动套用系统默认定义的文本和角色，由StandardButton枚举定义，它的成员如下。

1. NoButton：表示“否”（No）按钮，对应的按钮角色是NoRole。
2. Yes：表示“是”（Yes）按钮，对应的按钮角色是YesRole。
3. Ok：表示“确定”按钮，对应 AcceptRole。
4. Open：表示“打开”（Open）按钮，对应AcceptRole。
5. Save：表示“保存”（Save）按钮，对应的角色是 AcceptRole。
6. Cancel:表示“取消”（Cancel）按钮，对应RejectRole。
7. Close：表示“关闭”（Close）按钮，对应的角色是RejectRole。
8. Discard:表示“放弃”（Discard）按钮，对应的角色是DestructiveRole。
9. Apply：表示“应用”（Apply）按钮，对应的角色是 ApplyRole。
10. Reset：表示“重置”（Reset）按钮，对应 ResetRole。
11. RestoreDefaults：表示“恢复默认”（Restore Defaults）按钮，对应 ResetRole。
12. Help：表示“帮助”（Help）按钮，对应的角色是HelpRole。
13. SaveAll：表示“全部保存”（Save All）按钮，对应的角色是 AcceptRole。
14. YesToAll：表示“全部都是”（Yes to All）按钮，对应的角色是 YesRole。
15. NoToAll：表示“全部都否”（No to All）按钮，对应 NoRole 角色。
16. Abort：表示“退出”（Abort）按钮，对应的角色是 RejectRole。
17. Retry：表示“重试”（Retry）按钮，对应 AcceptRole 角色。
18. Ignore:表示“忽略”（Ignore）按钮，对应 AcceptRole角色。
19. NoButton：表示无效按钮，将被隐藏。

在初始化 QDialogButtonBox类时，可以用以下重载的__init__方法设置标准按钮：

创建 QDialogButtonBox 实例后，还可以调用 setStandardButtons 方法来设置标准按钮。

13.6.4 示例：展示所有标准按钮

本示例主要是让读者直观地看到各标准按钮的呈现效果。具体代码如下：

由于NoButton会使按钮隐藏（不可见），因此上述代码未包含NoButton的值。

运行示例后，就能看到所有的标准按钮了，如图13-26所示。

图 13-26

图 13-26 标准按钮列表

13.6.5 示例：标准按钮与clicked 信号

当 QDialogButtonBox组件中的某个按钮被单击后，QDialogButtonBox 组件会发出 clicked 信号，同时传递被单击按钮的引用。

在处理 QDialogButtonBox 组件所发出的 clicked 信号时，可以通过 standardButton 方法获得与按钮对应的 StandardButton 值，接着分析 StandardButton值就能确定被单击的是哪个标准按钮了。

本示例将演示如何在clicked信号的处理代码中判断被触发的标准按钮。自定义对话框类CustDialog的实现代码如下：

在初始化应用程序时，可以将CustDialog对话框作为程序的主窗口。

运行示例程序，如图13-27所示。

单击Apply按钮，QLabel组件会显示相关信息，如图13-28所示。

图 13-27、图 13-28

图 13-27 自定义对话框
图 13-28 Apply 按钮被单击后

13.6.6 示例：用户注册对话框

本示例将实现一个用户注册对话框（UserRegDialog)，对话框底部的按钮由QDialogButtonBox组件来完成。在该对话框中，需要输入用户名、密码和E-mail。单击“注册”按钮后回到程序主窗口，并显示新用户信息。对话框输入的用户信息将保存到字典类型（dict）的对象中。

UserRegDialog类的完整代码如下：

密码字段使用了两个QLineEdit组件，即需要两次输入的密码一致才能通过验证。如果用户单击了“注册”按钮，先对各字段输入的值进行验证。如果验证成功，将数据存入data字段。最后调用对话框基类的accept方法接受输入；如果单击的是“取消”按钮，则调用对话框基类的reject方法拒绝输入。

下面的代码创建程序窗口，并由“新增用户”按钮的clicked信号处理代码负责显示对话框。当用户信息完成输入后，在标签组件中显示用户信息。代码如下：

示例程序运行后，单击“新增用户”按钮，打开输入用户信息的对话框，如图13-29所示。

单击“注册”按钮，回到主窗口，显示新用户信息，如图13-30所示。

图 13-29、图 13-30

图 13-29 注册用户对话框
图 13-30 显示用户信息

程序界面不应该直接显示用户密码，此处仅用于演示。

QWizard类派生自QDialog，它是一种特殊的对话框。QWizard组件呈现为向导对话框，用户可以通过“返回”（Back)、“下一步”（Next）、“完成”（Finish）等按钮在页面之间导航。

单个向导页由 QWizardPage类表示。它是 QWidget的子类，因此可以像普通 QWidget一样使用，如添加布局和子级组件。不过，QWizardPage类增加了额外的界面元素：title（标题）、subTitle（副标题）、pixmap（显示在页面上的各样图标)。初始化 QWizard组件后，需要调用 addPage方法添加页面。调用exec 或 open 方法显示向导对话框。

13.7.1 示例：创建简单的向导对话框

本示例主要演示 QWizard类与 QWizardPage类的使用。示例将为向导创建两个页面，以下两个函数分别初始化并返回向导页面。

实例化QWizard组件，添加上述两个方法所返回的向导页。

调用 open方法以异步方式显示向导对话框。

运行示例程序，如图13-31所示。

单击Next按钮，将跳转到第二页，如图13-32所示。

图 13-31、图 13-32

图 13-31向导对话框的第一个页面
图 13-32 向导对话框的第二个页面

此时，单击Finish按钮可关闭对话框；单击Back按钮可以回到第一页。

13.7.2 WizardButton 枚举

该枚举定义了QWizard组件中的按钮。

1. BackButton：“返回”按钮。
2. NextButton：“下一步”“继续”按钮。
3. CommitButton：“确认”按钮。
4. FinishButton：“完成”按钮。
5. CancelButton：“取消”按钮。
6. HelpButton：“帮助”按钮。
7. CustomButton1：第一个自定义按钮。
8. CustomButton2：第二个自定义按钮。
9. CustomButton3：第三个自定义按钮。
10. Stretch：不表示按钮，而是向布局插入空格。此空格会占用剩余的布局空间。

其中包含三个自定义按钮，可以由开发人员自行实现。

13.7.3 示例：设置按钮的文本

本示例将演示如何修改向导对话框中的按钮文本，调用的是setButtonText方法，它的声明如下：

参数 which的类型是WizardButton枚举，指定要修改显示文本的按钮，text参数指定新的文本。

CustPage从 QWizardPage类派生，通过构造函数可以直接设置新页面的标题、副标题以及页面内容。具体代码如下：

页面的内容文本用 QTextEdit组件显示。由于此处 QTextEdit 组件的功能是显示文本，因此可以用setReadOnly 方法设置为只读。

实例化 QWizard组件，用CustPage类创建 3 个页面。

调用 setButtonText方法，修改 Back、Next、Finish、Cancel 按钮的文本。

由于QWizard类继承了QDialog类的成员，所以可以连接QWizard对象的accepted、rejected信号，以便在向导对话框关闭后进行相关处理。本示例仅调用print函数向控制台输出文本内容。

运行示例程序，按钮文本如图13-33所示。

图 13-33

图13-33 修改后的按钮文本

13.7.4 示例：重写 nextId 方法

不管是 QWizard类还是 QWizardPage类，都有nextId方法，该方法会返回下一个页面的编号。默认实现是返回比当前页面更大的编号。addPage方法添加页面后会返回页面编号，此编号默认是按添加的顺序递增的。例如，第一个页面的编号是0，第二个页面的编号是1……

如果调用setPage方法来添加页面，则可以自定义页面编号。然后重写nextId方法，返回下一个页面的编号。QWizard 和QWizardPage类都可以重写 nextId 方法。本示例将重写 QWizardPage类的 nextId方法，实现在单击“Next”按钮后跳过“输入注册码”页面。

示例的实现步骤如下。

定义3个变量，代表3个页面的编号。

定义Page1类，实现“欢迎”页面。

该页面包含两个 QRadioButton 组件，将在重写nextId方法时使用。如果第一个QRadioButton 被选择，就返回编号为PAGE_2的页面；如果第二个QRadioButton被选中，就返回编号为PAGE_3的页面(跳过了 PAGE_2)。

定义Page2类，这是第二个页面，用于输入注册码。

重写nextId方法，直接返回第三个页面的编号PAGE3。

定义Page3类，这是第三个页面。

重写nextId方法，返回-1，表示没有下一个页面了。

初始化 QWizard 对象。

由于本示例中3个页面都未使用副标题，因此可以设置 WizardOption.IgnoreSubTitles选项以忽略副标题。

将3个页面添加到QWizard对象中。由于本示例事先定义了3个页面的编号，所以添加页面时应调用 setPage方法，而不是 addPage方法。

显示向导对话框可以用 exec、open方法，也可以调用从 QWidget类继承的 show方法。

运行示例后，“欢迎”页面有两个选项。若选择“前往下一页填写注册码”，单击Next按钮后，会跳转到“填写注册码”页面，如图13-34所示。

图 13-34

图13-34 跳转到“填写注册码”页面

若选择的是“跳过填写注册码”，单击Next按钮后，会跳转到“完成”页面，如图13-35所示。

图 13-35

图13-35 直接跳转到“完成”页面

13.7.5 示例：共享页面数据

QWizard类提供 field和 setField方法。field方法用于读取数据，setField方法用于写入数据。数据可以是任何类型，需要指定唯一的字段名称。这些数据可以在各页面之间共享。例如，X页面写入的数据，可以在Y页面读取。QWizardPage类也提供了field和 setField方法，实际上其内部调用了QWizard类的 field 和 setField 方法。

本示例将在QWizard组件中添加两个页面。第一个页面需要在3个文本框中输入内容（公司名称、公司电话和公司主页)，跳转到第二页时，显示在第一页中输入的内容。

具体实现步骤如下。

定义PageA类，派生自QWizardPage，作为向导的第一个页面。

上述代码的最后调用 registerField方法注册了3个字段名，并且分别与3个 QLineEdit 组件关联。

关联之后QWizard组件会自动将QLineEdit组件中输入的文本保存为共享数据。

实现PageB类，它是向导的第二个页面。

需要注意的是，调用field方法获取共享数据的代码不能写在__init__方法中（会读不到数据），应当重写QWizardPage类的initializePage方法（页面初始化过程中会调用该方法），并在该方法内进行读取。

初始化 QWizard 组件。

添加向导页。

显示向导对话框。

运行示例程序后，在第一个页面上输入文本，如图13-36所示。

单击Next按钮跳转到第二个页面，显示上一个页面中输入的内容，如图13-37所示。

图 13-36、图 13-37

图 13-36 输入内容
图13-37 显示上一个页面中输入的内容

13.7.6 向导风格与图标

WizardStyle枚举为 QWizard 组件定义了以下4种风格。

1. ClassicStyle：Windows 传统风格。
2. ModernStyle：Windows 现代风格。
3. AeroStyle：Windows 的 Aero 风格（Windows Vista/7 以上版本)。
4. MacStyle:MacOS 风格。

同时，WizardPixmap枚举定义了QWizard组件的各部位的图标。这些图标是否呈现将受到WizardStyle的影响，不同风格的向导对话框在外观上有所差异。

WizardPixmap枚举的成员如下。

1. WatermarkPixmap：显示在页面左侧的图像，在 ClassicStyle 和 ModernStyle风格下可见。
2. BannerPixmap:显示在页面顶部的横幅。仅在 ModernStyle下可见。
3. LogoPixmap：显示在页面右上角的小图标，在 ClassicStyle 和 ModernStyle下可见。
4. BackgroundPixmap：背景图，仅在 MacStyle下可见。

QWizard组件可以调用 setWizardStyle方法设置向导风格，调用 setPixmap方法设置图标。在QWizard组件上设置的图标会应用到所有页面上，如果要为某个页面单独设置图标，可以调用QWizardPage类的 setPixmap 方法。

13.7.7 示例：为向导设置图标

本示例将演示如何为向导对话框设置图标。示例将使用ModernStyle风格，并分别为WatermarkPixmap、LogoPixmap 和 BannerPixmap 设置图标。

自定义一个页面类CustPage，通过构造函数的参数来设置页面的标题、副标题和正文内容。代码如下：

随后初始化QWizard组件，代码如下：

用CustPage类为向导组件添加两个页面。

下面的代码为向导设置图标：

QWizardPage类在呈现页面时并不会自动缩放图标，因此如果图像的尺寸比较大，最好调用scaled方法进行缩放处理。QIcon对象可以用pixmap方法返回指定大小的图像数据，上述代码中的64表示生成64×64大小的图标。

示例的运行效果如图13-38所示。

图 13-38

图 13-38自定义向导的图标

13.7.8 示例：使用自定义按钮

QWizard 组件允许添加 3个自定义按钮，由 WizardButton枚举的 3个成员定义，即 CustomButton1、CustomButton2和CustomButton3。应用程序可以为这3个按钮添加自定义的处理代码。自定义按钮被单击后，QWizard 组件会发出 customButtonClicked 信号。信号带有一个整型参数，是 WizardButton枚举的成员值，该值用来区分哪个按钮被单击。

3个自定义按钮不一定要同时启用，可以通过组合WizardOption枚举的成员来控制要启用的按钮。

例如，下面的组合表示启用第一、二个自定义按钮。

本示例将启用全部自定义按钮，具体步骤如下。

定义 createPage函数，用来创建向导页面，返回QWizardPage实例。

实例化 QWizard 组件。

设置QWizard组件的选项，启用3个自定义按钮。

先调用 options方法返回QWizard 组件现有的选项值，然后再与HaveCustomButton1、HaveCustomButton2等值进行“或”运算（合并新、旧值），最后调用setOptions方法重新设置选项值。

这样做可以确保现有的选项不会丢失。

添加页面。

连接 customButtonClicked信号，分析被单击的自定义按钮，并用print函数输出到屏幕。

为3个自定义按钮设置显示文本。

显示向导对话框。

示例的运行结果如图13-39所示。依次单击3个自定义按钮，控制台窗口会输出相关文本。

图 13-39

图 13-39 自定义按钮

许多常用对话框组件（如 QFontDialog）都包含一个NoButtons选项，启用该选项后，对话框不会显示如Ok、Cancel等控制按钮。按钮隐藏后，用户不需要单击按钮来接受或拒绝对话框结果，关闭对话框后，所做的修改将自动生效。

控制按钮隐藏后，不再需要连接 colorSelected、fontSelected等信号来获取数据了，而是连接currentColorChanged、currentFontChanged、doubleValueChanged等信号，实时获取最新数据。

接下来以QFontDialog和QColorDialog为例进行演示：单击“字体”按钮打开字体对话框，只要在对话框中修改了相关参数，主窗口中的文本会立刻更新其字体；同理，当单击“颜色”按钮打开颜色对话框后，只要在对话框中修改颜色，主窗口上的文本颜色也会实时更新。

示例的大致步骤如下。

定义CustWindow类，从QWidget类派生，作为程序的主窗口。

实现initUi方法，负责实例化要用到的可视化组件。

两个按钮组件的功能是打开QFontDialog和QColorDialog对话框。标签组件的文本字体和文本本颜色将通过相应的对话框实时更新。

在 init 方法中调用initUi方法，然后设置对话框选项，隐藏控制按钮。

连接按钮的 clicked信号，打开相应的对话框。

连接 QFontDialog 组件的 currentFontChanged 信号，实时修改标签组件的字体。

连接 QColorDialog 组件的 currentColorChanged 信号，实时改变标签文本的颜色。

实例化并显示 CustWindow 窗口。

运行示例程序，单击“颜色”按钮，打开颜色对话框。此时，只要改变选定的颜色，标签组件的文本会自动改变颜色，如图13-40所示。

图 13-40

图 13-40 文本颜色同步更新

确定需要的颜色后，直接关闭对话框即可。

QMessageBox组件的功能是向用户展示消息框，主要作用是发出通知。与QDialogButtonBox类相似，QMessageBox类也定义了代表按钮角色的 ButtonRole枚举，以及代表标准按钮的 StandardButton枚举。

13.9.1 示例：使用标准按钮

当在 QMessageBox 类中使用标准按钮（使用 StandardButton 枚举添加的按钮）后，exec 方法返回StandardButton中的某个值，以表示被单击的按钮。

本示例将在窗口中创建一个按钮组件，单击后弹出QMessageBox对话框。对话框关闭后在标签组件中显示被单击的按钮。实现步骤如下。

以QWidget对象为主窗口，使用垂直布局。

添加按钮和标签组件。

初始化 QMessageBox 组件。

本示例的消息对话框将显示Yes（是）和No（否）按钮。

setText方法设置对话框的主要消息文本，一般采用简短明了的文字，便于用户迅速阅读；setInformativeText方法设置补充文本，用于解释主要消息文本，以帮助用户做出选择。

连接按钮的clicked信号，调用exec方法显示消息对话框。对话框关闭后显示被单击的按钮。

显示程序窗口。

运行示例程序，单击窗口上的“显示消息”按钮，打开如图13-41所示的消息框。

单击对话框中的Yes（是）按钮，回到程序窗口，标签组件显示的文本如图13-42所示。

图 13-41、图 13-42

图 13-41消息对话框
图13-42 显示消息框中被单击的按钮

13.9.2 示例：使用标准图标

QMessageBox.Icon枚举定义了几种标准的图标。

1. NoIcon：不显示图标。
2. Information：普通消息。
3. Warning:警告消息，一般用于发生错误但不严重的情况。
4. Question：询问消息，需要用户做出选择，如“是否要保存文件？”。
5. Critical：级别比较严重的错误，会导致程序无法继续运行。

QMessageBox组件调用 setIcon 方法可以设置标准图标。如果希望使用自定义的图标，可以调用setIconPixmap 方法并提供 QPixmap 对象。

本示例将创建4个按钮，对应Information、Question、Warning和Critical图标。单击按钮后，会使用对应的标准图标弹出 QMessageBox对话框。核心代码如下：

运行示例代码，然后分别单击窗口上的4个按钮，就能看到各图标的外观了，具体可参考表13-2。

13.9.3 静态成员

QMessageBox类主要用于向用户呈现消息，如果每次使用都要实例化QMessageBox类，会非常不方便。因此，QMessageBox类提供了一组静态方法，在需要弹出消息对话框时可直接调用。

information方法。显示常规的消息，该方法有两个重载。

parent参数指定对话框的父窗口。title参数指定对话框的标题，text参数指定消息内容。button0、button1参数指定对话框中的第一、第二按钮（对话框只显示两个按钮)。buttons参数可以通过或运算指定多个标准按钮。defaultButton参数指定一个标准按钮，当用户按下【Enter】键时会自动触发（如果为NoButton，则由 QMessageBox类自动选择默认按钮)。

question方法。显示询问消息框，带有问号图标。它的两个重载如下：

各参数的含义与information方法一致。

warning方法。弹出警告消息，呈现感叹号图标。该方法也有两个重载。

各参数的含义也与information方法相同。

critical。显示错误消息，该方法也有两个重载。

各参数的含义与information方法相同。

13.9.4 示例：使用静态方法

本示例将演示使用 question静态方法来打开消息对话框。程序窗口为QMainWindow类，包含菜单栏。菜单栏中添加了“应用程序”菜单，“应用程序”菜单下包含“退出”命令。具体的代码如下：

连接 exitAction的 triggered信号，在“退出”命令触发时询问用户是否退出应用程序。

消息对话框显示 Yes和 No 按钮，如果用户单击了 Yes 按钮，就调用 QApplication 类的 quit方法退出程序。quit方法是静态成员，可以直接调用。

示例代码执行后，依次执行“应用程序”→“退出”，就会弹出消息框询问是否要退出，如图13-43所示。

图 13-43

图 13-43 询问是否退出应用程序