内容

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

QScroller 类

The QScroller class enables kinetic scrolling for any scrolling widget or graphics item. 更多...

头：	#include <QScroller>
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

• 1 特性继承自 QObject

公共函数

QPointF	finalPosition () const
bool	handleInput (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 )
状态	state () const
void	stop ()
QObject *	target () const
QPointF	velocity () const

• 32 公共函数继承自 QObject

公共槽

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

• 1 公共槽继承自 QObject

信号

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

• 2 信号继承自 QObject

静态公共成员

QList<QScroller *>	activeScrollers ()
Qt::GestureType	grabGesture (QObject * target , 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 )

• 11 静态公共成员继承自 QObject

额外继承成员

• 9 保护函数继承自 QObject

详细描述

The QScroller class enables kinetic scrolling for any scrolling widget or graphics item.

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

The QScroller object is the object that stores the current position and scrolling speed and takes care of updates. QScroller can be triggered by a flick gesture

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 on a per- QScroller basis.

Several examples in the scroller examples directory show how QScroller , QScrollEvent and the scroller gesture can be used.

尽管此动感卷动器拥有大量可用设置凭借 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 )

state : const State

此特性保持滚轴的状态

访问函数：

状态	state () const

通知程序信号：

void	stateChanged (QScroller::State newState )

另请参阅 QScroller::State .

成员函数文档编制

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

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

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

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

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

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

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

另请参阅 scrollTo ().

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

这是重载函数。

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

QPointF QScroller:: finalPosition () const

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

目标位置以像素为单位。

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

[static] Qt::GestureType QScroller:: grabGesture ( QObject * target , 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 ( 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。

[slot] void QScroller:: resendPrepareEvent ()

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

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

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

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

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

pos 按视口坐标给定。

另请参阅 ensureVisible ().

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

这是重载函数。

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

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

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

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

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

这是重载函数。

This is the const version of scroller ().

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

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

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

另请参阅 scrollerProperties .

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 以取消激活捕捉

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

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

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

另请参阅 state .

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 ().