QScroller#

The QScroller class enables kinetic scrolling for any scrolling widget or graphics item. More…

Synopsis#

Properties#

scrollerProperties - Scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior
state - The state of the scroller

Functions#

def finalPosition ()
def handleInput (input, position[, timestamp=0])
def pixelPerMeter ()
def scrollerProperties ()
def setSnapPositionsX (positions)
def setSnapPositionsX (first, interval)
def setSnapPositionsY (positions)
def setSnapPositionsY (first, interval)
def state ()
def stop ()
def target ()
def velocity ()

Slots#

def ensureVisible (rect, xmargin, ymargin)
def ensureVisible (rect, xmargin, ymargin, scrollTime)
def resendPrepareEvent ()
def scrollTo (pos)
def scrollTo (pos, scrollTime)
def setScrollerProperties (prop)

Signals#

def scrollerPropertiesChanged (arg__1)
def stateChanged (newstate)

Static functions#

def activeScrollers ()
def grabGesture (target[, gestureType=QScroller.ScrollerGestureType.TouchGesture])
def grabbedGesture (target)
def hasScroller (target)
def scroller (target)
def scroller (target)
def ungrabGesture (target)

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

With kinetic scrolling, the user can push the widget in a given direction and it will continue to scroll in this direction until it is stopped either by the user or by friction. Aspects of inertia, friction and other physical concepts can be changed in order to fine-tune an intuitive user experience.

The QScroller object is the object that stores the current position and scrolling speed and takes care of updates. QScroller can be triggered by a flick gesture

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

or directly like this:

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

The scrolled QObjects receive a QScrollPrepareEvent whenever the scroller needs to update its geometry information and a QScrollEvent whenever the content of the object should actually be scrolled.

The scroller uses the global QAbstractAnimation timer to generate its QScrollEvents. This can be changed with FrameRate on a per- QScroller basis.

The Dir View Example shows one way to use a QScroller with a QTreeView . An example in the scroller examples directory also demonstrates QScroller .

Even though this kinetic scroller has a large number of settings available via QScrollerProperties , we recommend that you leave them all at their default, platform optimized values. Before changing them you can experiment with the plot example in the scroller examples directory.

See also

QScrollEvent QScrollPrepareEvent QScrollerProperties

class PySide6.QtWidgets.QScroller#

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property PᅟySide6.QtWidgets.QScroller.scrollerProperties: PySide6.QtWidgets.QScrollerProperties#

This property holds The scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior..

Access functions:

scrollerProperties ()
setScrollerProperties (prop)
Signal scrollerPropertiesChanged (arg__1)

property PᅟySide6.QtWidgets.QScroller.state: State#

This property holds the state of the scroller.

See also

State

Access functions:

state ()
Signal stateChanged (newstate)

PySide6.QtWidgets.QScroller.State#

This enum contains the different QScroller states.

Constant

Description

QScroller.Inactive

The scroller is not scrolling and nothing is pressed.

QScroller.Pressed

A touch event was received or the mouse button was pressed but the scroll area is currently not dragged.

QScroller.Dragging

The scroll area is currently following the touch point or mouse.

QScroller.Scrolling

The scroll area is moving on it’s own.

Constant	Description
QScroller.Inactive	The scroller is not scrolling and nothing is pressed.
QScroller.Pressed	A touch event was received or the mouse button was pressed but the scroll area is currently not dragged.
QScroller.Dragging	The scroll area is currently following the touch point or mouse.
QScroller.Scrolling	The scroll area is moving on it’s own.

PySide6.QtWidgets.QScroller.ScrollerGestureType#

This enum contains the different gesture types that are supported by the QScroller gesture recognizer.

Constant

Description

QScroller.TouchGesture

The gesture recognizer will only trigger on touch events. Specifically it will react on single touch points when using a touch screen and dual touch points when using a touchpad.

QScroller.LeftMouseButtonGesture

The gesture recognizer will only trigger on left mouse button events.

QScroller.MiddleMouseButtonGesture

The gesture recognizer will only trigger on middle mouse button events.

QScroller.RightMouseButtonGesture

The gesture recognizer will only trigger on right mouse button events.

Constant	Description
QScroller.TouchGesture	The gesture recognizer will only trigger on touch events. Specifically it will react on single touch points when using a touch screen and dual touch points when using a touchpad.
QScroller.LeftMouseButtonGesture	The gesture recognizer will only trigger on left mouse button events.
QScroller.MiddleMouseButtonGesture	The gesture recognizer will only trigger on middle mouse button events.
QScroller.RightMouseButtonGesture	The gesture recognizer will only trigger on right mouse button events.

PySide6.QtWidgets.QScroller.Input#

This enum contains an input device agnostic view of input events that are relevant for QScroller .

Constant

Description

QScroller.InputPress

The user pressed the input device (e.g. MouseButtonPress , GraphicsSceneMousePress , TouchBegin )

QScroller.InputMove

The user moved the input device (e.g. MouseMove , GraphicsSceneMouseMove , TouchUpdate )

QScroller.InputRelease

The user released the input device (e.g. MouseButtonRelease , GraphicsSceneMouseRelease , TouchEnd )

Constant	Description
QScroller.InputPress	The user pressed the input device (e.g. `MouseButtonPress` , `GraphicsSceneMousePress` , `TouchBegin` )
QScroller.InputMove	The user moved the input device (e.g. `MouseMove` , `GraphicsSceneMouseMove` , `TouchUpdate` )
QScroller.InputRelease	The user released the input device (e.g. `MouseButtonRelease` , `GraphicsSceneMouseRelease` , `TouchEnd` )

static PySide6.QtWidgets.QScroller.activeScrollers()#

Returns an application wide list of currently active QScroller objects. Active QScroller objects are in a state() that is not Inactive . This function is useful when writing your own gesture recognizer.

PySide6.QtWidgets.QScroller.ensureVisible(rect, xmargin, ymargin)#

Parameters:

rect – PySide6.QtCore.QRectF
xmargin – float
ymargin – float

Starts scrolling so that the rectangle rect is visible inside the viewport with additional margins specified in pixels by xmargin and ymargin around the rect.

In cases where it is not possible to fit the rect plus margins inside the viewport the contents are scrolled so that as much as possible is visible from rect.

The scrolling speed is calculated so that the given position is reached after a platform-defined time span.

This function performs the actual scrolling by calling scrollTo() .

See also

scrollTo()

PySide6.QtWidgets.QScroller.ensureVisible(rect, xmargin, ymargin, scrollTime)

Parameters:

rect – PySide6.QtCore.QRectF
xmargin – float
ymargin – float
scrollTime – int

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

PySide6.QtWidgets.QScroller.finalPosition()#

Return type:: PySide6.QtCore.QPointF

Returns the estimated final position for the current scroll movement. Returns the current position if the scroller state is not Scrolling. The result is undefined when the scroller state is Inactive.

The target position is in pixel.

See also

pixelPerMeter() scrollTo()

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

Parameters:

target – PySide6.QtCore.QObject
gestureType – ScrollerGestureType

Return type:

GestureType

Registers a custom scroll gesture recognizer, grabs it for the target and returns the resulting gesture type. If scrollGestureType is set to TouchGesture the gesture triggers on touch events. If it is set to one of LeftMouseButtonGesture , RightMouseButtonGesture or MiddleMouseButtonGesture it triggers on mouse events of the corresponding button.

Only one scroll gesture can be active on a single object at the same time. If you call this function twice on the same object, it will ungrab the existing gesture before grabbing the new one.

Note

To avoid unwanted side-effects, mouse events are consumed while the gesture is triggered. Since the initial mouse press event is not consumed, the gesture sends a fake mouse release event at the global position (INT_MIN, INT_MIN). This ensures that internal states of the widget that received the original mouse press are consistent.