class QScroller

类 QScroller 允许任何滚动小部件或图形项启用动态滚动。更多信息…

概要

属性

• scrollerProperties - 此滚动条的滚动条属性。这些属性由 QScroller 用于确定其滚动行为

• state - 滚动条的状态

方法

• def finalPosition()

• def handleInput()

• def pixelPerMeter()

• def scrollerProperties()

• def setSnapPositionsX()

• def setSnapPositionsY()

• def state()

• def stop()

• 定义 target()

• 定义 velocity()

插槽

• 定义 ensureVisible()

• 定义 resendPrepareEvent()

• 定义 scrollTo()

• 定义 setScrollerProperties()

信号

• 定义 scrollerPropertiesChanged()

• 定义 stateChanged()

静态函数

• 定义 activeScrollers()

• 定义 grabGesture()

• 定义 grabbedGesture()

• 定义 hasScroller()

• 定义 scroller()

• 定义 ungrabGesture()

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对此片段翻译的贡献。如果您发现翻译有问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们

详细描述

警告

本节包含自动从C++翻译到Python的代码片段，可能存在错误。

在动量滚动中，用户可以按给定方向推动小部件，它会继续向此方向滚动，直到用户停止或由于摩擦力而停止。可以更改惯性和摩擦力等物理概念，以便微调直观的用户体验。

QScroller对象是存储当前位置和滚动速度并处理更新的对象。QScroller可以通过滑动手势触发

w = ...
QScroller.grabGesture(w, QScroller.LeftMouseButtonGesture)

或直接这样

w = ...
scroller = QScroller.scroller(w)
scroller.scrollTo(QPointF(100, 100))

当滚动器需要更新其几何信息时，滚动中的QObjects会接收到一个QScrollPrepareEvent，而在实际需要滚动对象内容时，则会接收到一个QScrollEvent。

滚动器使用全局的QAbstractAnimation计时器来生成其QScrollEvents。这可以通过在单个QScroller上修改FrameRate属性来改变。

尽管这个动量滚动器通过QScrollerProperties提供了大量的设置，但我们建议将其全部保留在默认、平台优化的值。在更改之前，您可以在scroller示例目录中的plot示例中进行实验。

参阅亦

QScrollerProperties

class State

此枚举包含不同的QScroller状态。

常量	描述
QScroller.Inactive	滚动器没有滚动并且没有任何按键被按下。
QScroller.Pressed	接收到一个触摸事件或鼠标按钮被按下，但当前没有拖动滚动区域。
QScroller.Dragging	滚动区域当前在跟随触摸点或鼠标。
QScroller.Scrolling	滚动区域正在自行移动。

class ScrollerGestureType手势识别器支持的不同的手势类型。

常量	描述
QScroller.TouchGesture	手势识别器只会对触摸事件做出响应。具体来说，当使用触摸屏时，它会响应单个触摸点，当使用触摸板时，它会响应双触摸点。
QScroller.LeftMouseButtonGesture	手势识别器只会对左鼠标按钮事件做出响应。
QScroller MiddleMouseButtonGesture	手势识别器只会对中鼠标按钮事件做出响应。
QScroller.RightMouseButtonGesture	手势识别器只会对右鼠标按钮事件做出响应。

class Input

此枚举包含一个与输入设备无关的输入事件的看法，这些事件对于QScroller来说是相关的。

常量	描述
QScroller.InputPress	用户按下输入设备（例如，QEvent :: MouseButtonPress，QEvent :: GraphicsSceneMousePress，QEvent :: TouchBegin）
QScroller.InputMove	用户移动输入设备（例如，QEvent :: MouseMove，QEvent :: GraphicsSceneMouseMove，QEvent :: TouchUpdate）
QScroller.InputRelease	用户释放输入设备（例如，QEvent :: MouseButtonRelease，QEvent :: GraphicsSceneMouseRelease，QEvent :: TouchEnd）

注意

可以在使用`from __feature__ import true_property`时直接使用属性，否则可以通过访问函数使用。

属性 scrollerProperties： QScrollerProperties

这个属性保存了这个滚动器的滚动属性。这些属性被用于 QScroller 以确定其滚动行为。

访问函数

• scrollerProperties()

• setScrollerProperties()

• 信号 scrollerPropertiesChanged()

属性 state： QScroller.State

这个属性保存了滚动器的状态。

参阅亦

状态

访问函数

• state()

• 信号 stateChanged()

静态 activeScrollers()

返回类型：

`.list of QScroller

返回一个应用范围内的当前活动 QScroller 对象列表。活动的 QScroller 对象处于非 Inactive 的 state() 状态。此函数在编写您自己的手势识别器时非常有用。

ensureVisible(rect, xmargin, ymargin)

参数：

• rect – QRectF

• xmargin – float

• ymargin – float

开始滚动，以便矩形 rect 可以在视口中可见（包括通过 xmargin 和 ymargin 指定像素的额外边距）。

在无法在视口中适应矩形以及边距的情况下，内容会被滚动，以便尽可能从 rect 中显示尽可能多的内容。

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

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

参阅亦

scrollTo()

ensureVisible(rect, xmargin, ymargin, scrollTime)

参数：

• rect – QRectF

• xmargin – float

• ymargin – float

• scrollTime – int

这是一个重载函数。

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

finalPosition()

返回类型：

QPointF

返回当前滚动运动的估计最终位置。如果滚动器状态不是滚动状态，则返回当前位置。当滚动器状态为非活动状态时，结果未定义。

目标位置以像素为单位。

参阅亦

pixelPerMeter() scrollTo()

static grabGesture(target[, gestureType=QScroller.ScrollerGestureType.TouchGesture])

参数：

• target – QObject

• gestureType – ScrollerGestureType

返回类型：

GestureType

注册自定义滚动手势识别器，获取 target 并返回结果手势类型。如果 scrollGestureType 设置为 TouchGesture，则手势监听触摸事件。如果设置为 LeftMouseButtonGesture 、 RightMouseButtonGesture 或 MiddleMouseButtonGesture，则在该按钮的鼠标事件上触发。

一个对象在同一时间只能有一个滚动手势处于活动状态。如果在同一对象上两次调用此函数，将解除现有手势的拖放，然后再捕获新手势。

注意

为了避免不期望的副作用，在手势触发时消费鼠标事件。由于初始鼠标按下事件没有被消费，手势会发送一个全局位置的假鼠标释放事件(INT_MIN, INT_MIN)。这确保接收了原始鼠标按下事件的部件的内部状态是一致的。

参阅亦

ungrabGesture() grabbedGesture()

static grabbedGesture(target)

参数：

target – QObject

返回类型：

GestureType

返回当前对target捕获的手势类型或没有捕获手势时返回0。

参阅亦

grabGesture() ungrabGesture()

handleInput(input, position[, timestamp=0])

参数：

• input – Input

• position – QPointF

• timestamp – int

返回类型：

bool

此函数由手势识别器用于通知滚动器有关一个新的输入事件。根据输入事件及其附加的滚动器属性，滚动器会更改其内部state()。滚动器不会区分事件来自哪种输入设备，因此需要将事件拆分为input类型、一个position和一个毫秒级的timestamp。position需要以目标坐标系统为准。

返回值是true，表示事件应由调用过滤器消费；或false，表示事件应转发到控件。

注意

对于大多数用例，使用grabGesture()应该是足够的。

static hasScroller(target)

参数：

target – QObject

返回类型：

bool

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

参阅亦

scroller()

pixelPerMeter()

返回类型：

QPointF

返回滚动小部件的像素每米度量值。

该值通过使用一个-mfスタイルのQPointF分别单独报告x和y轴。

注意

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

resendPrepareEvent()

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

scrollTo(pos)

参数：

pos – QPointF

开始滚动小部件，使点 pos 位于视口的顶部左侧位置。

当滚动超出有效滚动区域时，行为是未定义的。在这种情况下，滚动条可能会或可能不会超出。

将计算滚动速度，以便在平台定义的时间间隔后达到指定位置。

pos 以视口坐标给出。

参阅亦

ensureVisible()

scrollTo(pos, scrollTime)

参数：

• pos – QPointF

• scrollTime – int

这是一个重载函数。

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

static scroller(target)

参数：

target – QObject

返回类型：

QScroller

这是一个重载函数。

这是 scroller() 的 const 版本。

static scroller(target)

参数：

target – QObject

返回类型：

QScroller

返回给定 target 的滚动器。只要对象存在，此函数将始终返回相同的 QScroller 实例。如果不存在 QScroller，则将隐式创建一个。一个对象上不会同时有多个 QScroller 激活。

参阅亦

hasScroller() target()

scrollerProperties()

返回类型：

QScrollerProperties

参阅亦

setScrollerProperties()

属性 scrollerProperties 的获取器。

scrollerPropertiesChanged(arg__1)

参数：

arg__1 – QScrollerProperties

QScroller 在其滚动属性更改时发出此信号。 newProperties 是新的滚动属性。

参阅亦

scrollerProperties

属性 scrollerProperties 的通知信号。

setScrollerProperties(prop)

参数：

prop – QScrollerProperties

参阅亦

scrollerProperties()

scrollerProperties 属性的设置器。

setSnapPositionsX(positions)

参数：

positions – .real 列表

将水平轴的自动吸附位置设置为 positions 列表。这将覆盖之前设置的自动吸附位置和之前设置的吸附间隔。可以通过设置一个空的自动吸附位置列表来禁用吸附。

setSnapPositionsX(first, interval)

参数：

• first – float

• interval – float

将水平轴的自动吸附位置设置为间隔均匀的位置。第一个自动吸附位置在 first。下一个在 first + interval。这可以用来实现列表的表头。这将覆盖之前设置的自动吸附位置和之前设置的吸附间隔。可以通过将间隔设置为 0.0 来禁用吸附。

setSnapPositionsY(positions)

参数：

positions – .real 列表

将垂直轴的 snap 位置设置为 positions 列表。这将覆盖之前设置的所有 snap 位置以及之前设置的 snap 间隔。可以通过设置一个空的位置列表来禁用 snap。

setSnapPositionsY(first, interval)

参数：

• first – float

• interval – float

将垂直轴的 snap 位置设置为常规间隔。第一个 snap 位置在 first，下一个在 first + interval。这将覆盖之前设置的所有 snap 位置以及之前设置的 snap 间隔。可以通过设置间隔为 0.0 来禁用 snap。

state()

返回类型：

状态

属性 state 的获取器。

stateChanged(newstate)

参数：

newstate – State

QScroller 在状态更改时发出此信号。 newState 是新的状态。

参阅亦

state

属性 state 的通知信号。

stop()

停止滚动器并将其状态重置为 Inactive。

target()

返回类型：

QObject

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

参阅亦

hasScroller() scroller()

static ungrabGesture(target)

参数：

target – QObject

取消抓取 target 的手势。如果没有手势被抓取，则不执行任何操作。

参阅亦

grabGesture() grabbedGesture()

velocity()

返回类型：

QPointF

当状态为 Scotting 或 Dragging 时，返回当前每秒滚动速度（单位：米/秒）。其他情况返回零速度。

使用 QPointF 分开报告 x 和 y 轴的速度。

参阅亦

pixelPerMeter()