内容

• 公共类型
• 特性
• 公共函数
• 公共槽
• 信号
• 静态公共成员
• 详细描述

QScroller 类

QScroller 类使任何卷动 Widget 或图形项能够动感卷动。 更多...

头：	#include <QScroller>
CMake:	find_package(Qt6 COMPONENTS Widgets REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
Since:	Qt 5.0
继承：	QObject

• 所有成员列表，包括继承成员

公共类型

enum	Input { InputPress, InputMove, InputRelease }
enum	ScrollerGestureType { TouchGesture, LeftMouseButtonGesture, MiddleMouseButtonGesture, RightMouseButtonGesture }
enum	State { Inactive, Pressed, Dragging, Scrolling }

特性

• scrollerProperties : QScrollerProperties
• state : const State

公共函数

QPointF	finalPosition () const
bool	handleInput (QScroller::Input input , const QPointF & position , qint64 timestamp = 0)
QPointF	pixelPerMeter () const
QScrollerProperties	scrollerProperties () const
void	setSnapPositionsX (const QList<qreal> & positions )
void	setSnapPositionsX (qreal first , qreal interval )
void	setSnapPositionsY (const QList<qreal> & positions )
void	setSnapPositionsY (qreal first , qreal interval )
QScroller::State	state () const
void	stop ()
QObject *	target () const
QPointF	velocity () const

公共槽

void	ensureVisible (const QRectF & rect , qreal xmargin , qreal ymargin , int scrollTime )
void	ensureVisible (const QRectF & rect , qreal xmargin , qreal ymargin )
void	resendPrepareEvent ()
void	scrollTo (const QPointF & pos , int scrollTime )
void	scrollTo (const QPointF & pos )
void	setScrollerProperties (const QScrollerProperties & prop )

信号

void	scrollerPropertiesChanged (const QScrollerProperties & newProperties )
void	stateChanged (QScroller::State newState )

静态公共成员

QList<QScroller *>	activeScrollers ()
Qt::GestureType	grabGesture (QObject * target , QScroller::ScrollerGestureType scrollGestureType = TouchGesture)
Qt::GestureType	grabbedGesture (QObject * target )
bool	hasScroller (QObject * target )
QScroller *	scroller (QObject * target )
const QScroller *	scroller (const QObject * target )
void	ungrabGesture (QObject * target )

详细描述

采用动感滚动，用户可以沿给定方向推动 Widget，且将继续沿此方向卷动直到被用户 (或摩擦) 停止。可以改变惯性、摩擦和其它物理概念的各个方面，为微调直观用户体验。

QScroller 对象是存储当前位置、卷动速度及负责更新的对象。通过轻弹手势可以触发 QScroller

    QWidget *w = ...;
    QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture);
					

或直接像这样：

    QWidget *w = ...;
    QScroller *scroller = QScroller::scroller(w);
    scroller->scrollTo(QPointF(100, 100));
					

卷动的 QObject 接收 QScrollPrepareEvent 每当卷动器需要更新其几何体信息时和 QScrollEvent 每当对象内容实际上应滚动时。

卷动器使用全局 QAbstractAnimation 计时器来生成其 QScrollEvent。这可以改变采用 QScrollerProperties::FrameRate 在每 QScroller 基础之上。

目录视图范例 展示一种使用 QScroller 的方式采用 QTreeView 。范例在 scroller 范例目录还演示 QScroller。

尽管此动感卷动器拥有大量可用设置凭借 QScrollerProperties ，推荐将它们全部保持在其默认、平台优化值。在更改它们之前，可以实验性采用 plot 范例在 scroller 范例目录。

另请参阅 QScrollEvent , QScrollPrepareEvent ，和 QScrollerProperties .

成员类型文档编制

enum QScroller:: Input

此枚举包含输入设备不可知视图对于输入事件相关 QScroller .

常量	值	描述
QScroller::InputPress	1	用户按下输入设备 (如 QEvent::MouseButtonPress , QEvent::GraphicsSceneMousePress , QEvent::TouchBegin )
QScroller::InputMove	2	用户移动输入设备 (如 QEvent::MouseMove , QEvent::GraphicsSceneMouseMove , QEvent::TouchUpdate )
QScroller::InputRelease	3	用户释放输入设备 (如 QEvent::MouseButtonRelease , QEvent::GraphicsSceneMouseRelease , QEvent::TouchEnd )

enum QScroller:: ScrollerGestureType

此枚举包含的不同手势类型支持通过 QScroller 手势识别器。

常量	值	描述
QScroller::TouchGesture	0	手势识别器仅在触摸事件时才触发。具体来说，它对单触摸点作出反应当使用触摸屏时，和对双触摸点作出反应当使用触摸板时。
QScroller::LeftMouseButtonGesture	1	手势识别器仅在鼠标左键事件时才触发。
QScroller::MiddleMouseButtonGesture	3	手势识别器仅在鼠标中键事件时才触发。
QScroller::RightMouseButtonGesture	2	手势识别器仅在鼠标右键事件时才触发。

enum QScroller:: State

此枚举包含不同 QScroller 状态。

常量	值	描述
QScroller::Inactive	0	卷动器不卷动且什么都未按下。
QScroller::Pressed	1	收到触摸事件或按下鼠标按钮，但目前未拖拽卷动区域。
QScroller::Dragging	2	卷动区域目前跟随触摸点 (或鼠标)。
QScroller::Scrolling	3	卷动区域正在自行移动。

特性文档编制

scrollerProperties : QScrollerProperties

此特性保持此卷动器的卷动特性。特性用于 QScroller 以确定其卷动行为。

访问函数：

QScrollerProperties	scrollerProperties () const
void	setScrollerProperties (const QScrollerProperties & prop )

通知程序信号：

void	scrollerPropertiesChanged (const QScrollerProperties & newProperties )

[read-only] state : const State

此特性保持滚轴的状态

访问函数：

QScroller::State

state () const

通知程序信号：

void	stateChanged (QScroller::State newState )

另请参阅 QScroller::State .

成员函数文档编制

[slot] void QScroller:: ensureVisible (const QRectF & rect , qreal xmargin , qreal ymargin , int scrollTime )

这是重载函数。

此版本将到达其目标位置在 scrollTime 毫秒。

[slot] void QScroller:: ensureVisible (const QRectF & rect , qreal xmargin , qreal ymargin )

开始卷动以便矩形 rect 在视口内可见，采用额外边距以像素为单位指定通过 xmargin and ymargin 围绕矩形。

当不可能将矩形加边距拟合在视口内时，会滚动内容以便尽可能多地可见从 rect .

会计算卷动速度，以便到达给定位置在平台定义的时间跨度后。

此函数履行实际卷动通过调用 scrollTo ().

另请参阅 scrollTo ().

[slot] void QScroller:: resendPrepareEvent ()

此函数重新发送 QScrollPrepareEvent 。调用 resendPrepareEvent 触发 QScrollPrepareEvent 从卷动器。这允许接收器重新设置内容位置和内容大小当卷动时。当在 Inactive 状态下调用此函数是无用的，因为会再次发送准备事件在卷动开始之前。

[slot] void QScroller:: scrollTo (const QPointF & pos , int scrollTime )

这是重载函数。

此版本将到达其目标位置在 scrollTime 毫秒。

[slot] void QScroller:: scrollTo (const QPointF & pos )

开始卷动 Widget 以便点 pos 位于视口左上位置。

行为未定义当在有效卷动区域之外卷动时。在这种情况下，卷动器可能 (或不可能) 过冲。

将计算卷动速度，以便在平台定义的时间跨度后到达给定位置。

pos 按视口坐标给定。

另请参阅 ensureVisible ().

[signal] void QScroller:: scrollerPropertiesChanged (const QScrollerProperties & newProperties )

QScroller 发射此信号每当其卷动器特性改变时。 newProperties 是新卷动器特性。

注意： 通知程序信号对于特性 scrollerProperties .

另请参阅 scrollerProperties .

[signal] void QScroller:: stateChanged ( QScroller::State newState )

QScroller 发射此信号每当状态变化时。 newState 是新状态。

注意： 通知程序信号对于特性 state .

另请参阅 state .

[static] QList < QScroller *> QScroller:: activeScrollers ()

返回应用程序范围列表的当前活动 QScroller 对象。活动 QScroller 对象处于 state () 非 QScroller::Inactive 。此函数很有用，当编写自己的手势识别器时。

QPointF QScroller:: finalPosition () const

返回当前卷动运动的最终估计位置。返回当前位置，若卷动器状态不为 Scrolling。结果未定义，当卷动器状态为 Inactive 时。

目标位置以像素为单位。

另请参阅 pixelPerMeter () 和 scrollTo ().

[static] Qt::GestureType QScroller:: grabGesture ( QObject * target , QScroller::ScrollerGestureType scrollGestureType = TouchGesture)

注册自定义卷动手势识别器，抓取它为 target 并返回结果手势类型。若 scrollGestureType 被设为 TouchGesture 手势在触摸事件时才触发。若它被设为某一 LeftMouseButtonGesture , RightMouseButtonGesture or MiddleMouseButtonGesture 它在相应按钮鼠标事件时才触发。

在一个对象中只可以同时活动一个卷动手势。若在同一对象中调用此函数 2 次，它将取消现有手势抓取在抓取新手势之前。

注意： 为避免不想要的副作用，会消耗鼠标事件当触发手势时。由于初始鼠标按下事件未被消耗，所以手势会发送伪鼠标释放事件在全局位置 (INT_MIN, INT_MIN) 。这确保收到原始鼠标按下的 Widget 的内部状态一致。

另请参阅 ungrabGesture () 和 grabbedGesture ().

[static] Qt::GestureType QScroller:: grabbedGesture ( QObject * target )

返回目前抓取的手势类型对于 target 或 0 若没有抓取手势。

另请参阅 grabGesture () 和 ungrabGesture ().

bool QScroller:: handleInput ( QScroller::Input input , const QPointF & position , qint64 timestamp = 0)

手势识别器使用此函数，通报卷动器有关新输入事件。卷动器改变其内部 state () 根据输入事件及其附加的卷动器特性。卷动器不区分事件来自哪种输入设备。因此，需要将事件拆分成 input 类型， position 和毫秒 timestamp 。 position 需要在目标坐标系中。

返回值为 true 若事件应该被调用过滤器消耗或 false 若事件应该被转发给控件。

注意： 使用 grabGesture () 对于大多数用例而言应该足够了。

[static] bool QScroller:: hasScroller ( QObject * target )

返回 true 若 QScroller 对象已创建为 target ; false 否则。

另请参阅 scroller ().

QPointF QScroller:: pixelPerMeter () const

返回卷动 Widget 的每米像素规格。

分别报告 X 轴和 Y 轴两者的值通过使用 QPointF .

注意： 请注意，此值在物理上应该是正确的。底层窗口系统可能特意误报 Qt 为显示返回的实际 DPI 设置，例如在 macOS。

[static] QScroller *QScroller:: scroller ( QObject * target )

返回卷动器为给定 target 。只要对象存在，此函数将始终返回相同 QScroller 实例。若无 QScroller 存在对于 target ，将隐式创建一个。在任何时候仅一 QScroller 将活动在对象上。

另请参阅 hasScroller () 和 target ().

[static] const QScroller *QScroller:: scroller (const QObject * target )

这是重载函数。

这是 const 版本的 scroller()。

void QScroller:: setSnapPositionsX (const QList < qreal > & positions )

将水平轴的捕捉位置设为列表 positions 。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过设置空位置列表以取消激活捕捉。

void QScroller:: setSnapPositionsX ( qreal first , qreal interval )

将水平轴的捕捉位置设为常规间隔间隙。首个捕捉位置在 first 。下一在 first + interval 。这可以用于实现列表 Header (头)。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过将间隙设为 0.0 以取消激活捕捉

void QScroller:: setSnapPositionsY (const QList < qreal > & positions )

将垂直轴的捕捉位置设为列表 positions 。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过设置空位置列表以取消激活捕捉。

void QScroller:: setSnapPositionsY ( qreal first , qreal interval )

将垂直轴的捕捉位置设为常规间隔间隙。首个捕捉位置在 first 。下一在 first + interval 。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过将间隙设为 0.0 以取消激活捕捉

void QScroller:: stop ()

停止卷动器并将其状态重置回 Inactive。

QObject *QScroller:: target () const

返回此卷动器的目标对象。

另请参阅 hasScroller () 和 scroller ().

[static] void QScroller:: ungrabGesture ( QObject * target )

取消手势抓取为 target 。什么都不做，若没有手势被抓取。

另请参阅 grabGesture () 和 grabbedGesture ().

QPointF QScroller:: velocity () const

返回当前卷动速度 (以米/秒为单位) 当状态为 Scrolling (卷动) 或 Dragging (拖拽) 时。否则，返回 0 速度。

分别报告 X 轴和 Y 轴两者的速度通过使用 QPointF .

另请参阅 pixelPerMeter ().