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 .
此枚举包含输入设备不可知视图对于输入事件相关 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 ) |
此枚举包含的不同手势类型支持通过 QScroller 手势识别器。
常量 | 值 | 描述 |
---|---|---|
QScroller::TouchGesture
|
0
|
手势识别器仅在触摸事件时才触发。具体来说,它对单触摸点作出反应当使用触摸屏时,和对双触摸点作出反应当使用触摸板时。 |
QScroller::LeftMouseButtonGesture
|
1
|
手势识别器仅在鼠标左键事件时才触发。 |
QScroller::MiddleMouseButtonGesture
|
3
|
手势识别器仅在鼠标中键事件时才触发。 |
QScroller::RightMouseButtonGesture
|
2
|
手势识别器仅在鼠标右键事件时才触发。 |
此枚举包含不同 QScroller 状态。
常量 | 值 | 描述 |
---|---|---|
QScroller::Inactive
|
0
|
卷动器不卷动且什么都未按下。 |
QScroller::Pressed
|
1
|
收到触摸事件或按下鼠标按钮,但目前未拖拽卷动区域。 |
QScroller::Dragging
|
2
|
卷动区域目前跟随触摸点 (或鼠标)。 |
QScroller::Scrolling
|
3
|
卷动区域正在自行移动。 |
此特性保持此卷动器的卷动特性。特性用于 QScroller 以确定其卷动行为。
访问函数:
QScrollerProperties | scrollerProperties () const |
void | setScrollerProperties (const QScrollerProperties & prop ) |
通知程序信号:
void | scrollerPropertiesChanged (const QScrollerProperties & newProperties ) |
此特性保持滚轴的状态
访问函数:
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 。此函数很有用,当编写自己的手势识别器时。
返回当前卷动运动的最终估计位置。返回当前位置,若卷动器状态不为 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 ().
手势识别器使用此函数,通报卷动器有关新输入事件。卷动器改变其内部 state () 根据输入事件及其附加的卷动器特性。卷动器不区分事件来自哪种输入设备。因此,需要将事件拆分成 input 类型, position 和毫秒 timestamp 。 position 需要在目标坐标系中。
返回值为
true
若事件应该被调用过滤器消耗或
false
若事件应该被转发给控件。
注意: 使用 grabGesture () 对于大多数用例而言应该足够了。
[static]
bool
QScroller::
hasScroller
(
QObject
*
target
)
返回
true
若
QScroller
对象已创建为
target
;
false
否则。
另请参阅 scroller ().
返回卷动 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()。
将水平轴的捕捉位置设为列表 positions 。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过设置空位置列表以取消激活捕捉。
将水平轴的捕捉位置设为常规间隔间隙。首个捕捉位置在 first 。下一在 first + interval 。这可以用于实现列表 Header (头)。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过将间隙设为 0.0 以取消激活捕捉
将垂直轴的捕捉位置设为列表 positions 。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过设置空位置列表以取消激活捕捉。
将垂直轴的捕捉位置设为常规间隔间隙。首个捕捉位置在 first 。下一在 first + interval 。这会覆写所有先前设置的捕捉位置及先前设置的捕捉间隙。可以通过将间隙设为 0.0 以取消激活捕捉
停止卷动器并将其状态重置回 Inactive。
返回此卷动器的目标对象。
另请参阅 hasScroller () 和 scroller ().
[static]
void
QScroller::
ungrabGesture
(
QObject
*
target
)
取消手势抓取为 target 。什么都不做,若没有手势被抓取。
另请参阅 grabGesture () 和 grabbedGesture ().
返回当前卷动速度 (以米/秒为单位) 当状态为 Scrolling (卷动) 或 Dragging (拖拽) 时。否则,返回 0 速度。
分别报告 X 轴和 Y 轴两者的速度通过使用 QPointF .
另请参阅 pixelPerMeter ().