QScroller Class

成员函数文档

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

返回一个包含当前应用程序中所有处于活动状态的QScroller 对象的列表。处于活动状态的QScroller 对象位于一个state()中，且该状态未被QScroller::Inactive 。在编写自定义手势识别器时，此函数非常有用。

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

开始滚动，使矩形rect 显示在视口内，并在该矩形周围添加由xmargin 和ymargin 指定的以像素为单位的额外边距。

如果无法将矩形及其边距全部容纳在视口内，则会滚动内容，以便尽可能多地显示rect 中的内容。

滚动速度经过计算，确保在平台定义的时间间隔后到达指定位置。

此函数通过调用scrollTo() 来执行实际的滚动操作。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::ensureVisible));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QRectF &rect, qreal xmargin, qreal ymargin) { receiver->ensureVisible(rect, xmargin, ymargin); });

另请参阅 scrollTo()。

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

该版本将在scrollTime 毫秒内到达目标位置。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::ensureVisible));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QRectF &rect, qreal xmargin, qreal ymargin, int scrollTime) { receiver->ensureVisible(rect, xmargin, ymargin, scrollTime); });

QPointF QScroller::finalPosition() const

返回当前滚动操作的预估最终位置。如果滚动条状态不是“Scrolling”，则返回当前位置。当滚动条状态为“Inactive”时，结果未定义。

目标位置以像素为单位。

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

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

注册一个自定义滚动手势识别器，将其绑定到target 上，并返回生成的手势类型。如果scrollGestureType 设置为TouchGesture ，则手势在触摸事件发生时触发；如果设置为LeftMouseButtonGesture 、RightMouseButtonGesture 或MiddleMouseButtonGesture 中的任意一个，则在相应按钮的鼠标事件发生时触发。

单个对象上同一时间只能有一个滚动手势处于活动状态。若对同一对象调用此函数两次，系统会先释放现有手势，然后捕获新手势。

另请参阅 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 。

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

如果已为target 创建了QScroller 对象，则返回true ；否则返回false 。

另请参阅 scroller()。

QPointF QScroller::pixelPerMeter() const

返回已滚动控件的“每米像素”指标。

该值通过QPointF 分别报告 x 轴和 y 轴的数值。

[slot] void QScroller::resendPrepareEvent()

该函数会重新发送QScrollPrepareEvent 。调用resendPrepareEvent会触发滚动器发出的QScrollPrepareEvent 。这允许接收方在滚动过程中重新设置内容位置和内容大小。在“非活动”状态下调用此函数是无效的，因为在滚动开始之前，准备事件会被重新发送。

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

开始滚动该控件，使点pos 位于视口左上角。

当滚动超出有效滚动区域时，其行为未定义。在此情况下，滚动条可能会或可能不会越界。

滚动速度将经过计算，以确保在平台定义的时间间隔后到达给定位置。

pos 以视口坐标形式给出。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::scrollTo));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QPointF &pos) { receiver->scrollTo(pos); });

另请参阅 ensureVisible()。

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

该版本将在scrollTime 毫秒内到达目标位置。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        scroller, qOverload(&QScroller::scrollTo));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        scroller, [receiver = scroller](const QPointF &pos, int scrollTime) { receiver->scrollTo(pos, scrollTime); });

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

返回给定 `target` 对应的滚动条。只要该对象存在，此函数将始终返回同一个 `QScroller ` 实例。如果该 `target` 不存在 `QScroller `，则会隐式创建一个。在任何时候，一个对象上都不会有超过一个 `QScroller ` 处于活动状态。

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

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

这是 scroller() 的 const 版本。

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

QScroller 每当其滚动条属性发生变化时，都会发出此信号。newProperties 是新的滚动条属性。

另请参阅 scrollerProperties 。

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

将水平轴的对齐位置设置为一个positions 列表。这将覆盖所有先前设置的对齐位置以及先前设置的对齐间隔。通过设置一个空的位置列表，可以禁用对齐功能。

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

将水平轴的对齐位置设置为等间距。第一个对齐位置为first ，下一个为first +interval 。这可用于实现列表标题。此设置将覆盖之前设置的所有对齐位置以及之前设置的对齐间隔。将间隔设置为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 。

void QScroller::stop()

停止滚动条，并将其状态重置为“非活动”状态。

QObject *QScroller::target() const

返回此滚动条的目标对象。

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

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

释放target 的手势。如果未捕获任何手势，则不执行任何操作。

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

QPointF QScroller::velocity() const

当状态为“滚动”或“拖动”时，返回当前的滚动速度（单位为米/秒）。否则，返回零速度。

通过调用 `QPointF` 方法，可分别获取 x 轴和 y 轴的速度。

另请参阅 pixelPerMeter()。