PySide6.QtWidgets.QScroller¶

class QScroller¶

QScroller 类为任何滚动小部件或图形项启用了动能滚动。更多…

概要¶

属性¶

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

注意

本文档可能包含从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

滚动区域正在自行移动。

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

class ScrollerGestureType¶

此枚举包含由QScroller手势识别器支持的不同手势类型。

常量

描述

QScroller.TouchGesture

手势识别器将仅在触摸事件上触发。具体来说，当使用触摸屏时，它将响应单点触摸；当使用触摸板时，它将响应双点触摸。

QScroller.LeftMouseButtonGesture

手势识别器将仅在左键鼠标事件上触发。

QScroller.MiddleMouseButtonGesture

手势识别器将仅在鼠标中键事件上触发。

QScroller.RightMouseButtonGesture

手势识别器将仅在右键鼠标按钮事件上触发。

常量	描述
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）

常量	描述
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时，属性可以直接使用，否则通过访问器函数使用。

property scrollerPropertiesᅟ: QScrollerProperties¶

此属性保存此滚动条的滚动属性。这些属性由QScroller用于确定其滚动行为。

Access functions:

scrollerProperties()
setScrollerProperties()
信号 scrollerPropertiesChanged()

property stateᅟ: QScroller.State¶

此属性保存滚动条的状态。

另请参阅

State

Access functions:

state()
信号 stateChanged()

static activeScrollers()¶

Return type:: QScroller的列表

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

ensureVisible(rect, xmargin, ymargin)¶

Parameters:

rect – QRectF
xmargin – 浮点数
ymargin – 浮点数

开始滚动，以便矩形 rect 在视口中可见，并在矩形周围由 xmargin 和 ymargin 指定的额外边距（以像素为单位）。

在无法将矩形加上边距放入视口的情况下，内容会被滚动，以便尽可能多地显示来自 rect 的内容。

滚动速度的计算是为了在平台定义的时间跨度后达到给定位置。

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

另请参阅

scrollTo()

ensureVisible(rect, xmargin, ymargin, scrollTime)

Parameters:

rect – QRectF
xmargin – 浮点数
ymargin – 浮点数
scrollTime – int

这是一个重载函数。

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

finalPosition()¶

Return type:: QPointF

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

目标位置以像素为单位。

另请参阅

pixelPerMeter() scrollTo()

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

Parameters:

target – QObject
gestureType – ScrollerGestureType

Return type:

GestureType

注册一个自定义的滚动手势识别器，将其应用于target并返回结果的手势类型。如果scrollGestureType设置为TouchGesture，则手势在触摸事件上触发。如果设置为LeftMouseButtonGesture、RightMouseButtonGesture或MiddleMouseButtonGesture之一，则手势在相应按钮的鼠标事件上触发。

在同一时间，单个对象上只能有一个滚动手势处于活动状态。如果你在同一个对象上两次调用此函数，它将在抓取新的手势之前取消现有的手势。

注意

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

另请参阅

ungrabGesture() grabbedGesture()

static grabbedGesture(target)¶

Parameters:: 目标 – QObject
Return type:: GestureType

返回当前为target抓取的手势类型，如果没有抓取手势则返回0。

另请参阅

grabGesture() ungrabGesture()

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

Parameters:

输入 – Input
position – QPointF
timestamp – int

Return type:

布尔

此函数由手势识别器使用，用于向滚动器通知新的输入事件。滚动器根据输入事件及其附加的滚动器属性更改其内部state()。滚动器不区分事件来自的输入设备类型。因此，事件需要分为input类型、position和毫秒timestamp。position需要在目标的坐标系中。

如果事件应该被调用过滤器消耗，则返回值为true；如果事件应该转发到控件，则返回值为false。

注意

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

static hasScroller(target)¶

Parameters:: 目标 – QObject
Return type:: 布尔

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

另请参阅

scroller()

pixelPerMeter()¶

Return type:: QPointF

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

使用QPointF分别报告x轴和y轴的值。

注意

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

resendPrepareEvent()¶

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

scrollTo(pos)¶

Parameters:: pos – QPointF

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

在有效滚动区域外滚动时的行为是未定义的。在这种情况下，滚动器可能会也可能不会超出范围。

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

pos 是在视口坐标中给出的。

另请参阅

ensureVisible()

scrollTo(pos, scrollTime)

Parameters:

pos – QPointF
scrollTime – int

这是一个重载函数。

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

static scroller(target)¶

Parameters:: 目标 – QObject
Return type:: QScroller

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

另请参阅

hasScroller() target()

static scroller(target)

Parameters:: 目标 – QObject
Return type:: QScroller

这是一个重载函数。

这是 scroller() 的常量版本。

scrollerProperties()¶

Return type:: QScrollerProperties

另请参阅

setScrollerProperties()

属性 scrollerPropertiesᅟ 的获取器。

scrollerPropertiesChanged(newProperties)¶

Parameters:: newProperties – QScrollerProperties

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

另请参阅

scrollerProperties

属性 scrollerPropertiesᅟ 的通知信号。

setScrollerProperties(prop)¶

Parameters:: prop – QScrollerProperties

另请参阅

scrollerProperties()

属性 scrollerPropertiesᅟ 的设置器。

setSnapPositionsX(positions)¶

Parameters:: positions – qreal 的列表

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

setSnapPositionsX(first, interval)

Parameters:

first – 浮点数
interval – 浮点数

设置水平轴的捕捉位置为等距间隔。第一个捕捉位置在first。下一个在first + interval。这可以用于实现列表头。这将覆盖所有先前设置的捕捉位置以及先前设置的捕捉间隔。通过将间隔设置为0.0可以停用捕捉。

setSnapPositionsY(positions)¶

Parameters:: positions – .qreal的列表

将垂直轴的捕捉位置设置为positions列表。这将覆盖所有先前设置的捕捉位置以及先前设置的捕捉间隔。通过设置一个空的位置列表可以停用捕捉功能。

setSnapPositionsY(first, interval)

Parameters:

first – 浮点数
interval – 浮点数

为垂直轴设置对齐位置为规则的间隔。第一个对齐位置在first。下一个在first + interval。这将覆盖所有先前设置的对齐位置以及先前设置的对齐间隔。通过将间隔设置为0.0可以停用对齐功能。

state()¶

Return type:: State

属性 stateᅟ 的获取器。

stateChanged(newstate)¶

Parameters:: newstate – State

QScroller 每当状态改变时发出此信号。newState 是新的状态。

另请参阅

state

属性 stateᅟ 的通知信号。

stop()¶

停止滚动器并将其状态重置为未激活状态。

target()¶

Return type:: QObject

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

另请参阅

hasScroller() scroller()

static ungrabGesture(target)¶

Parameters:: 目标 – QObject

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

另请参阅

grabGesture() grabbedGesture()

velocity()¶

Return type:: QPointF

当状态为滚动或拖动时，返回当前滚动速度，单位为米每秒。否则返回零速度。

速度分别通过使用QPointF报告x轴和y轴。

另请参阅

pixelPerMeter()

PySide6.QtWidgets.QScroller¶

概要¶

属性¶

方法¶

插槽¶

信号¶

静态函数¶

详细描述¶