QScroller 类

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

头: #include <QScroller>
qmake: QT += widgets
Since: Qt 5.0
继承: QObject

该类在 Qt 5.0 引入。

公共类型

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

特性

公共函数

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 基础之上。

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

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

另请参阅 QScrollEvent , QScrollPrepareEvent ,和 QScrollerProperties .

成员类型文档编制

enum QScroller:: 输入

此枚举包含输入设备不可知视图对于输入事件相关 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

此特性保持滚轴的状态

访问函数:

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