QScrollArea

定义

QScrollArea是Qt框架Qt Widgets模块中的一个控件类,其作用是在一个带框架的区域内提供对另一个部件的滚动视图,官方文档将其描述为「在另一个部件上提供滚动视图」^[1]。它本身并不直接承载内容,而是作为一个容器,把用户指定的内容部件放置在自己的视口之中^[3]。

在类层次上,QScrollArea继承自QAbstractScrollArea,而QAbstractScrollArea又继承自QFrame和QWidget,因此它具备普通部件的属性,同时获得了与滚动条相关的通用功能^[1]。该类公开的属性主要有2个,即alignment(对齐方式)与widgetResizable(视图部件是否可调整大小)^[4]。

QScrollArea的公共成员函数包括setWidget()、widget()、takeWidget()、setWidgetResizable()、setAlignment()、ensureVisible()和ensureWidgetVisible()等,其中setWidget()用于设置被滚动的子部件,widget()用于取回该部件,takeWidget()则移除子部件并把所有权交给调用者^[1]。

原理

QScrollArea的工作方式可以理解为「窗口加幕布」的结构。滚动区域自身相当于一个固定大小的观察窗口,内部还有一个作为内容载体的QWidget,被放入的按钮、标签等控件都绘制在这个内部载体上;当内部载体的尺寸大于观察窗口时,滚动条出现,拖动滚动条相当于在窗口后面移动这块内容载体^[5]。

滚动条是否出现由两个条件决定:一是子部件的尺寸是否超过视口,二是当前设置的滚动条策略。QAbstractScrollArea提供了horizontalScrollBarPolicy与verticalScrollBarPolicy两个属性,取值包括Qt::ScrollBarAsNeeded(需要时显示,默认值)、Qt::ScrollBarAlwaysOff(始终隐藏)和Qt::ScrollBarAlwaysOn(始终显示)^[6]。也可以用horizontalScrollBar()和verticalScrollBar()取得滚动条对象,再调用QScrollBar::setValue()在内容变化时主动调整滚动位置^[1]。

内部载体的尺寸对滚动行为影响很大。若子部件只是普通QWidget,通常需要调用setMinimumSize()设定最小尺寸,才能保证内容在滚动区域内正确显示;若子部件内使用了布局管理器,则布局的大小策略也会决定部件尺寸,把布局的size constraint属性设为对最小或最大尺寸有限制的取值(如QLayout::SetMinAndMaxSize),就能在布局内容变化时带动滚动区域尺寸更新^[3]。

widgetResizable属性控制滚动区域是否自动调整视图部件的尺寸。该属性默认为false,此时滚动区域尊重子部件自身的尺寸;无论该属性取何值,都可以用widget()->resize()以编程方式改变子部件尺寸,滚动区域会自动适应新尺寸。设为true时,滚动区域会自动调整子部件尺寸,以避免出现本可省略的滚动条,或利用多余空间^[4]。

发展历程

QScrollArea的alignment属性以及ensureWidgetVisible()函数在Qt 4.2中被引入,其早期文档将该类归入QtGui模块;当时的签名中父对象参数默认为0,属于Qt 4时代尚未引入nullptr的写法^[7]。

随着Qt 5的发布,QScrollArea被归入Qt Widgets模块,qmake工程中需要使用「QT += widgets」才能引用该类^[8]。文档中的函数签名也随之更新为使用nullptr作为默认参数值^[1]。

进入Qt 6之后,该类在CMake构建系统中通过「find_package(Qt6 REQUIRED COMPONENTS Widgets)」与「target_link_libraries(mytarget PRIVATE Qt6::Widgets)」引入,类名、属性与主要成员函数保持稳定,并新增了viewportSizeHint()这一受保护函数的重实现^[1]。官方文档同时提供英文与中文版本,中文版把widget一词译为「窗口部件」或「小部件」^[2]。

应用

滚动区域最常见的用途是显示尺寸大于窗口的图像。Qt官方文档给出的示例用QLabel承载QPixmap,再通过setWidget()交给QScrollArea,当图像被放大时滚动区域便提供必要的滚动条;官方还提供了把QLabel与QScrollArea组合起来的ImageViewer示例^[1]。

在界面设计工具中,QScrollArea属于容器类控件,可以直接从控件面板拖拽到窗口中,再把其他控件拖入其中^[6]。这种方式适用于内容较多、需要纵向或横向滚动才能完整展示的表单、列表和面板^[5]。

在代码方式下,典型步骤是先创建QScrollArea对象,再创建作为内容载体的QWidget,向布局中添加所需控件,最后调用setWidget()把内容载体交给滚动区域;官方特别提醒,setWidget()必须在内容载体的布局添加完成之后调用,否则部件不会显示^[4]。

除通用容器场景外,ensureVisible()与ensureWidgetVisible()两个便利函数可以在必要时滚动内容,使指定坐标点或指定子部件出现在视口之内,两个函数默认的边距都是50像素^[1]。

局限

QScrollArea只适用于把整体内容作为一个部件绘制的情形。若内容规模极大、不适合全部绘制在单个QWidget上,或者不需要逐像素的平滑滚动效果,开发者通常应当直接继承QAbstractScrollArea并自行实现滚动逻辑,而不是使用QScrollArea^[9]。

布局的添加顺序是一项使用限制。若在调用setWidget()之后才为子部件添加布局,该部件将不会显示,且此后也无法通过show()使其出现^[4]。此外,若在滚动区域已经可见时才把部件设为内容,还需要显式调用show()显示该部件^[1]。

滚动条的出现条件也容易与预期不符。只有当滚动区域自身的尺寸小于内部载体时,水平滚动条才会出现;如果含滚动区域的父窗口没有使用布局,滚动区域宽度不会随窗口缩小而缩小,只是被遮挡,此时并不会如预期般出现水平滚动条。因此在使用代码编写界面时,通常需要借助布局让滚动区域的大小随窗体变化^[5]。

对齐与空白方面也存在约束。alignment属性默认为左上对齐,可组合使用Qt::AlignLeft、Qt::AlignHCenter、Qt::AlignRight、Qt::AlignTop、Qt::AlignVCenter、Qt::AlignBottom等标志;当内部载体的最大宽高小于滚动区域实时尺寸时,滚动区域会显示空白区域,这部分空白无法放置或显示控件^[1][5]。此外,setWidget()会把子部件的autoFillBackground属性设置为true,并可能改动其外观表现^[4]。

参见

• Qt —— QScrollArea所属的跨平台C++应用程序开发框架

• QAbstractScrollArea —— QScrollArea直接继承的抽象基类,定义了滚动区域的通用功能

• QWidget —— Qt中所有用户界面对象的基类,也是QScrollArea所承载内容的载体类型

• QScrollBar —— 提供滚动条部件的类,可通过setValue()控制滚动位置

• QLabel —— 常与QScrollArea组合用于图像浏览的显示部件