容器组件

由于QWidget类自身支持相互嵌套来建立对象树，因此原则上从 QWidget派生的组件类都可以成为容器。Qt有专门的布局系统（从QLayout派生的类，如QGridLayout)，作为容器的组件可以使用布局类型来管理子级组件的位置和大小。

下面的代码创建了5个组件。

com1 为 QWidget 类，成为顶层容器，最终会呈现为普通窗口；com2 和 com3 是 QPushButton 组件，嵌套于 com1 内，成为子级组件；com4 是 QLabel 组件，嵌套在 com2 组件内；com5 也是 QLabel 组件，嵌套在 com3 组件内。呈现效果如图 9-1 所示。

5个组件之间的包含关系如图9-2所示。

本示例将从QWidget类派生出一个自定义面板。添加到该面板的组件将沿水平方向排列。在处理子级组件的排列时可以使用QHBoxLayout类。

具体的实现步骤如下。

1. 定义 DemoPanel 类，从 QWidget 类派生。

2. 在 __init__ 方法中实例化 QHBoxLayout 对象，用于控制子级组件的布局。

3. 定义 spacing 和 setSpacing 方法，用于获取或设置子级组件之间的间隙。

4. 定义 addWidget 方法，用来添加子级组件。方法内部调用 QHBoxLayout 对象的 addWidget 方法。

5. 重写 sizeHint 方法，计算当前组件所需要的空间。方法内部调用 QHBoxLayout 对象的 sizeHint 方法。

6. 实例化 QMainWindow 组件，它是 QtWidgets 模块提供的组件，表示应用程序的主窗口。

7. 实例化 DemoPanel 组件。

8. 创建 4 个 QLabel 组件实例，随后添加到 panel 对象中。QLabel 的背景使用随机生成的颜色填充。

9. 将 4 个 QLabel 对象添加到 panel 中。

10. 调用 QMainWindow 对象的 setCentralWidget 方法，让 panel 对象填充主窗口的内容区域。

11. 显示主窗口。

示例的运行结果如图9-3所示。

QFrame组件构建一个带有边框的空白区域，其中可以放置其他可视化组件。QFrame组件的边框可以是平面效果，也可以是三维效果，这取决于 Shape和 Shadow两个枚举的取值。

带三维效果的QFrame组件可以制作简单的容器，如面板。主要是在视觉上对组件进行分组，让其区域看起来与周围的组件不同。而平面效果的QFrame组件可以用于呈现文本、图像等内容。例如，功能比较简单的标签组件 QLabel 就是从 QFrame类派生的。结构复杂一些的如 QTextEdit、QScrollArea(提供滚动条，可移动可视区域）等组件也派生自QFrame类。

9.3.1 边框形状

边框形状由QFrame.Shape枚举的值来指定，其成员如下。

1. NoFrame：无边框显示。
2. Box：绘制外框，即常规矩形边框。
3. Panel：面板，在三维效果下会产生模拟光照投射而形成的阴影。
4. StyledPanel：面板，但外观会受样式参数的影响。
5. HLine：只绘制单一的水平线，适用于制作分隔线。
6. VLine：只绘制单一的垂直线，同样适用于制作分隔线。
7. WinPanel：此值只用于兼容，一般推荐使用 StyledPanel。使用该值会产生类似 Windows 2000 风格的面板。

以上枚举值在平面效果（Shadow枚举的值为Plain）中外观差异不明显（绘制一个平面矩形），但在三维效果（Shadow枚举的值为 Raised或Sunken）中外观差异较大。Box形状的4个边框颜色相同，而Panel形状的4个边会分成两组外观—左、上边的风格相同，右、下边的风格相同。

9.3.2 阴影效果

阴影效果能控制QFrame组件的边框呈现为平面或三维效果。阴影效果由QFrame.Shadow枚举来指定，其成员如下。

1. Plain：平面效果，采用窗口的前景色（QPalette.WindowText 所指定的颜色，也是窗口文本的默认颜色）来绘制边框线条。无三维效果。
2. Raised：三维效果。使用深浅不一的颜色绘制边框阴影，使其呈现出“凸起”的外形。
3. Sunken：三维效果。使用深色和浅色画笔绘制出“凹陷”的外形。

9.3.3 示例：Box 与 Panel 形状的区别

本示例主要演示QFrame组件在使用三维效果后，Box与Panel形状在视觉上的区别。

下面的代码在窗口中创建网格布局（QGridLayout)，第一行放置 QFrame 组件，第二行包含两个QRadioButton 组件。

为了便于观察 QFrame 组件的边框，将其边框宽度设置为 15。本示例中 QFrame 组件的阴影使用“凸起”效果（Raised）。

处理两个 QRadioButton 组件的 toggled 信号，当单选按钮的状态切换时修改 QFrame 组件的边框形状（使用setFrameShape方法）。代码如下：

运行示例程序，然后单击Box选项，设置QFrame组件的边框形状为Box，如图9-4所示。

单击选中 Panel选项，设置 QFrame组件的边框形状为 Panel，如图9-5所示。

通过对比可知，当QFrame组件使用Box形状的边框时，只有边框自身呈现出“凸起”效果；而使用Panel形状时，在边框内的整个矩形区域都呈现出“凸起”效果。

9.3.4 示例：“凸起”和“凹陷”阴影的区别

本示例主要演示 QFrame 组件中“凸起”和“凹陷”两种阴影的区别。设置阴影风格需要调用 setFrameShadow 方法，例如：

本示例将通过快捷键来切换 QFrame 组件的阴影风格。具体代码如下：

启用快捷键的流程如下。

1. 实例化 QShortcut对象，并将其附加到对象树中，父级为QFrame组件。
2. 调用 setKey 方法设置按键。它需要一个 QKeySequence 对象来描述快捷键，快捷键可以用字符串来定义，如ctrl+F，表示在按住【Ctrl】键的同时按下【F】键，即可触发。定义的字符串不区分大小写，ctrl+s 和 Ctrl+S 均有效。

1. 调用setEnabled方法使快捷键变为可用状态。此步可以省略，因为快捷键默认处于可用状态。
2. 调用 setContext方法可以设置快捷键的运用范围。WindowShortcut表示把快捷键注册为窗口级别，在整个窗口内均可用。也可以使用ApplicationShortcut值，使快捷键作用于整个应用程序。

连接activated信号。当快捷键被触发时，QShortcut对象会发出该信号，在本示例中，将调用setFrameShadow方法修改 QFrame组件的阴影风格。

运行示例程序，QFrame组件默认使用平面效果的阴影，此时按下快捷键【Ctrl+R】，应用“凸起”效果，如图9-6所示。

按下快捷键【Ctrl+S】，QFrame组件的边框阴影将变为“凹陷”效果，如图9-7所示。

通过本示例的对比可知，Raised阴影使边框看起来高于矩形平面，而Sunken阴影则低于矩形平面。

9.3.5 中线（mid-line）

此处中线是指位于外边框与内边框中间的一条线段，如图9-8所示。

如果去掉中线（线宽为0)，那么外框线与内框线会粘连在一起，如图9-9所示。

要修改中线的宽度，可以调用 setMidLineWidth方法，例如：

9.3.6 setFrameStyle 方法

setFrameStyle 方法是 setFrameShape 和 setFrameShadow 方法的合并版本，可以同时设置边框形状（Shape）和阴影（Shadow）。传递参数时，将两个枚举类型的值用“或”运算符连接。例如，下面的代码指定 QFrame 组件使用 Panel 形状以及“凹陷”阴影效果。

再如，要使用Box形状和平面效果，setFrameStyle方法的调用如下：

QTabWidget组件以“页面”的方式管理子级组件。QTabWidget组件提供一排标签栏，当用户选择一个标签后，“页面”区域会显示与该标签关联的内容组件，同时发出 currentChanged信号。QTabWidget组件的标签栏默认位于页面上方（顶部)，可以通过setTabPosition方法改变标签栏的位置。

QTabWidget 组件分为两部分，标签栏由 QTabBar 组件负责呈现，而页面部分则由 QStackedWidget组件呈现，如图9-10所示。

9.4.1 示例：动态添加页面

本示例演示在运行阶段向 QTabWidget 组件动态添加页面。程序代码需要调用 addTab 方法添加标签页，其声明如下：

widget 参数指定要作为页面内容的可视化组件；label 参数设置要在标签上显示的标题文本；icon参数设置在标签上显示的图标。返回值是新页面的索引。

另外，如果需要在特定的索引处插入新页面，还可以使用insertTab方法：

index参数指定要插入新页面的位置，index之后且已经存在的页面索引会递增。例如，QTabWidget组件中已有三个页面（索引为0、1、2)，往索引为1的位置插入新页面。位于索引0处的页面位置不变，但原索引为1、2的页面，其索引递增后变为2、3。

本示例需要定义窗口类，派生自 QTabWidget 类。初始化时默认添加一个页面，并且页面上有一个按钮，单击按钮后，会添加一个新的页面。自定义窗口类的代码如下：

为“添加新页面”按钮处理clicked信号，连接onAddPage方法。该方法的实现代码如下：

新页面的内容是QLabel组件，其中显示的文本为当前时间。

运行示例程序，初始化后如图9-11所示。

单击“添加新页面”按钮，添加新的标签页，如图9-12所示。

9.4.2 示例：设置标签栏的位置

QTabWidget 组件允许通过 setTabPosition 方法修改标签栏的位置。位置参数由 TabPosition 枚举类型定义（使用地理方位），成员如下。

1. North：北面，即位于内容页的上方。
2. South：南面，即位于内容页的下方。
3. West：西面，即位于内容页的左方。
4. East：东面，即位于内容页的右方。

下面的代码实例化QTabWidget类，并在第一页中放置4个按钮，分别对应上述4个枚举值。

依次处理 4 个按钮的 clicked 信号，调用 setTabPosition 方法改变标签栏的位置。

继续添加 4 个页面，内容为空白的 QWidget 对象。

运行示例程序，单击“初始页”上面的按钮改变标签栏的位置，如图9-13和图9-14所示。

9.4.3 示例：带图标的标签

调用addTab方法时可以为新标签指定一个图标。本示例将在QTabWidget组件中新建4个页面，同时它们的标签上都带有图标。

关键代码如下：

图标用QIcon类表示，直接从PNG格式的图像文件加载数据，然后传递给addTab方法。图标将显示在标签文本的左边，如图9-15所示。

9.4.4 使用快捷键

当QTabWidget组件的标签文本中出现“&”字符时，紧跟在“&”之后的字母（不区分大小写）会被视为快捷键。用户只要按下【Alt+<字母>】就能激活文本所在的标签页。

例如，有以下4个标签页：

第一个标签的文本是Pic&true，“&”之后是字符“t”，因此激活Picture标签的快捷键就是【Alt+T】；第二个标签的文本是Sh&ell，字符“&”之后是字符“e”，因此激活Shell标签的快捷键便是【Alt+E】。剩下的Markers和Folders标签也是同样的规律，它们的快捷键依次是【Alt+M】和【Alt+F】。

当用户按下【Alt】键后，作为快捷键的字母下方会出现短横线（下画线），如图9-16所示。

下画线的作用是提示用户该按哪个键。假如按下了快捷键【Alt+F】，Folders标签就会选中，如图9-17所示。

QGroupBox组件包含标题文本、边框以及面板。添加的子级组件将呈现在面板区域内。QGroupBox组件不会自动排列子级组件，因此建议在QGroupBox中使用布局类（如QGridLayout），再往布局对象中添加组件。

可以直接在调用 QGroupBox类的构造函数时指定标题文本，也可以在实例化 QGroupBox后再通过setTitle方法设置标题，还可以调用setAlignment方法设置标题文本的对齐方式，如居中对齐，默认左对齐。

9.5.1 示例：QGroupBox 的基础用法

本示例将演示QGroupBox组件的简单用法。下面代码直接创建QGroupBox组件的实例作为主窗口，并在 QGroupBox 内部放置 4 个 QCheckBox 组件。

QGroupBox内部可以放置任意QWidget组件以及它的子类组件。为了减少排版工作量，最好使用布局类，如本示例中使用了QVBoxLayout布局。

最终效果如图9-18所示。

9.5.2 示例：设置标题的对齐方式

QGroupBox组件的标题默认设置为左对齐，若要改变其对齐方式，需要调用setAlignment方法。参数值使用的是 Qt.AlignmentFlag 枚举。

本示例在QGroupBox组件中放置 3个按钮组件（QPushButton)，分别控制 QGroupBox标题文本的对齐方式。具体代码如下：

运行示例程序后，单击“居中对齐”按钮，QGroupBox的标题就会出现在容器的中间位置，如图9-19所示。

接着单击“右对齐”按钮，标题文本就会出现在容器的右上方，如图9-20所示。

9.5.3 示例：启用分组框的 Check 功能

QGroupBox 组件可以通过 setCheckable 方法开启 Check 功能。开启后，在 QGroupBox 组件的标题前面会显示复选框（类似 QCheckBox）。当复选框被选中后，QGroupBox 组件内的所有子级组件都处于可交互状态（允许用户进行操作）；当复选框取消选择后，QGroupBox 组件内的所有子级组件都被禁用（用户无法操作）。

本示例将在窗口上放置两个QGroupBox组件，它们均开启Check功能。具体步骤如下。

1. 初始化顶层窗口，并在窗口内放置两个 QGroupBox 组件。

2. 分别为两个 QGroupBox 组件设置标题文本。

3. 开启两个 QGroupBox 组件的 Check 功能。

4. 第一个 QGroupBox 组件中将创建 3 个 QRadioButton 组件。

5. 第二个 QGroupBox 组件中使用 QFormLayout 类进行布局管理，并添加 3 个字段。

6. 显示窗口。

运行示例代码，QGroupBox组件的复选框默认为选中状态，因此里面的组件都是可用的，如图9-21所示。

单击QGroupBox组件标题前面的复选框，使其变为未选中状态。此时，QGroupBox组件内的所有子级组件都不可用，如图9-22所示。

QScrollArea组件提供一个视图区域，当要呈现的内容大于视图区域时，就会出现滚动条。

要为 QScrollArea 设置内容组件，请调用 setWidget 方法。由于 QScrollArea 组件需要根据内容组件的大小来计算是否显示滚动条，以及滚动条滑块的位置，因此程序代码应该为内容组件设置合适的尺寸。

如果 QScrollArea 组件的内容是现有的 Qt 组件（如 QLabel)，那么可以调用 setMinimumSize 方法设置最小尺寸，或者调用setFixedSize方法设置固定尺寸；如果 QScrollArea的内容是自定义的组件类，那么在实现自定义组件时，可以重写sizeHint方法，并返回合适的大小。

默认情况下，QScrollArea组件将按需显示滚动条。代码可通过 setHorizontalScrollBarPolicy方法(作用于水平滚动条）或 setVerticalScrollBarPolicy 方法（作用于垂直滚动条）来调整滚动条显示策略。其可选策略由 ScrollBarPolicy 枚举定义。

1. ScrollBarAsNeeded：按需显示。这是默认值，只有当内容大于 QScrollArea 的视图区域时才会显示滚动条。
2. ScrollBarAlwaysOff：不管内容是否超出视图区域，都不会显示滚动条。
3. ScrollBarAlwaysOn：不管内容是否超出视图区域，始终显示滚动条。

9.6.1 示例：在 QScrollArea中承载自定义组件

本示例先实现自定义组件类，然后将它设置为QScrollArea的内容组件。

CustWidget类的实现代码如下：

该组件在实例化时可以提供fillColor值（默认蓝色），随后使用该颜色在组件上绘制椭圆。

CustWidget类重写了sizeHint方法，返回默认需求的大小（800×600像素）。

初始化 QScrollArea 组件，然后调用 setWidget方法将 CustWidget 对象设置为内容组件。

运行示例程序，当CustWidget组件的尺寸大于QScrollArea组件的视图区域时，会出现水平和垂直滚动条，如图9-23所示。

9.6.2 示例：设置内容组件的对齐方式

当QScrollArea有充足的空间显示内容时，滚动条自动隐藏（默认行为），此时可以用setAlignment方法来设置内容组件中QScrollArea视图区域中的对齐方式。该方法的参数类型是 Qt.AlignmentFlag枚举。枚举值可以组合使用，例如AlignLeft|AlignTop表示水平方向上左对齐，垂直方向上为顶部对齐，两个值组合后表示对象将对齐到容器的左上角。

本示例将创建9个按钮，代表9个对齐点—水平方向上的左、中、右，垂直方向上的上、中、下，两者组合起来就产生9个对齐点了。通过单击按钮可以设定QLabel组件中QScrollArea容器中的对齐方式。

具体的实现步骤如下。

1. 创建 QWidget 实例，作为顶层窗口。

2. 顶层窗口使用 QHBoxLayout 布局（水平排列）。

3. 添加子布局 QGridLayout（网格布局），嵌套在 QHBoxLayout 布局内。

4. 向网格布局添加 9 个按钮。

5. 9 个按钮的大小统一，均为 30×30 像素。

6. 初始化 QScrollArea 组件。

7. 呈现图像可以使用 QLabel 组件。

调用 setPixmap方法后，可以调用 adjustSize方法让QLabel组件根据呈现的内容自己调整其大小。

8. 连接 9 个按钮的 clicked 信号，为 QScrollArea 组件设置对齐方式。

9. 显示窗口。

运行示例后，适当调整窗口的大小，使呈现的图像有足够的空间完成对齐，然后单击窗口左边的按钮来调整图像的对齐位置。例如，单击“↘”按钮让图像对齐到右下角，如图9-24所示。

9.6.3 示例：拉伸图像

本示例搭配使用 QScrollArea和 QLabel组件实现拉伸图像的功能。

要实现拉伸图像的功能，两个组件需要满足以下条件。

1. 设置 QScrollArea 组件的 widgetResizable 属性为 True（通过 setWidgetResizable 方法），使 QScrollArea 组件能够根据视图的变化调整 QLabel 组件的大小。
2. QLabel 组件需要调用 setScaledContents 方法启用自动缩放内容的功能。
3. QLabel 组件需要调用 setSizePolicy 方法将水平、垂直方向上的缩放策略修改为 Ignored。否则，当滚动视图小于 QLabel 组件的最小尺寸时，预设的缩放策略会导致 QScrollArea 组件出现滚动条，图像无法拉伸。

示例的核心代码如下：

运行示例程序，直接调整窗口大小即可拉伸图像，如图9-25和图9-26所示。

QToolBox（工具箱组件）中可以添加多个条目（子项），每个条目都包含标题（可以带图标）和内容组件。QToolBox类似于TabWidget组件，每次只显示一个条目的内容，其他条目被折叠。

以下方法成员可以向QToolBox组件添加子项。

QToolBox 组件允许将任意 QWidget 对象（包括 QWidget 的子类）添加到子项列表中。text 参数表示工具箱条目的标题文本。icon 是可选参数，用于加载显示在标题文本前面的图标。返回值是新条目的索引。

另外，下面的方法也可以添加条目：

insertItem方法用于在指定索引处（index参数）处插入新条目。

如果工具箱条目的标题不足以描述其用途，还可以使用以下方法为其设置工具提示：

index参数表示要设置工具提示的条目索引，toolTip参数表示工具提示文本。当鼠标指针移动到条目标题上并悬浮片刻后，会显示提示文本。

访问currentIndex方法可以获得当前被激活的工具箱条目的索引。若要获得当前条目的QWidget组件引用，请使用currentWidget方法。当工具箱中被激活的条目变更后，QToolBox组件会发出currentChanged信号，并通过 index参数携带被激活条目的索引。

9.7.1 示例：带图标的工具箱条目

本示例将创建4个带图标和标题的工具箱条目。定义4个函数，用于为工具箱条目初始化QWidget（或其子类）对象，代码如下：

实例化 QToolBox 组件，然后调用 addItem 方法添加 4 个条目，代码如下：

QIcon类用于加载图标，本示例使用了4个大小为16×16像素的图像文件。“第一组”“第二组”等是标题文本。

示例运行结果如图 9-27 所示。注意，QToolBox 组件一次只显示一个条目的内容，可以单击条目标题来切换内容。

9.7.2 示例：处理 currentChanged 信号

当 QToolBox 组件中当前选中的条目改变后会发出 currentChanged 信号，并提供最新被选中的条目索引。本示例将处理 currentChanged 信号，根据索引获取当前条目的标题文本，并显示在 QLabel 组件中。

以下代码初始化顶层窗口。

窗口使用垂直排列布局。下面的代码初始化 QToolBox 组件，添加 5 个条目。

连接 currentChanged 信号，将当前条目的标题显示在名为 lbMsg 的 QLabel 组件中。

运行示例后，单击当前某个工具箱条目的标题，该条目便处于选中状态。同时，窗口底部的标签组件会显示该条目的标题，如图9-28所示。