QScroller

Inheritance diagram of PySide2.QtWidgets.QScroller

Synopsis

Functions

Slots

Signals

Static functions

Detailed Description

The PySide2.QtWidgets.QScroller class enables kinetic scrolling for any scrolling widget or graphics item.

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 PySide2.QtWidgets.QScroller object is the object that stores the current position and scrolling speed and takes care of updates. PySide2.QtWidgets.QScroller can be triggered by a flick gesture

QWidget *w = ...;
QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture);

or directly like this:

QWidget *w = ...;
QScroller *scroller = QScroller::scroller(w);
scroller->scrollTo(QPointF(100, 100));

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

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

Several examples in the scroller examples directory show how PySide2.QtWidgets.QScroller , PySide2.QtGui.QScrollEvent and the scroller gesture can be used.

Even though this kinetic scroller has a large number of settings available via PySide2.QtWidgets.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.

PySide2.QtWidgets.QScroller.State

This enum contains the different PySide2.QtWidgets.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.
PySide2.QtWidgets.QScroller.ScrollerGestureType

This enum contains the different gesture types that are supported by the PySide2.QtWidgets.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.
PySide2.QtWidgets.QScroller.Input

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

Constant Description
QScroller.InputPress The user pressed the input device (e.g. QEvent.MouseButtonPress , QEvent.GraphicsSceneMousePress , QEvent.TouchBegin )
QScroller.InputMove The user moved the input device (e.g. QEvent.MouseMove , QEvent.GraphicsSceneMouseMove , QEvent.TouchUpdate )
QScroller.InputRelease The user released the input device (e.g. QEvent.MouseButtonRelease , QEvent.GraphicsSceneMouseRelease , QEvent.TouchEnd )
static PySide2.QtWidgets.QScroller.activeScrollers()
Return type:

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

PySide2.QtWidgets.QScroller.ensureVisible(rect, xmargin, ymargin, scrollTime)
Parameters:
  • rectPySide2.QtCore.QRectF
  • xmarginPySide2.QtCore.qreal
  • ymarginPySide2.QtCore.qreal
  • scrollTimePySide2.QtCore.int

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

PySide2.QtWidgets.QScroller.ensureVisible(rect, xmargin, ymargin)
Parameters:

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 PySide2.QtWidgets.QScroller.scrollTo() .

PySide2.QtWidgets.QScroller.finalPosition()
Return type:PySide2.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.

static PySide2.QtWidgets.QScroller.grabGesture(target[, gestureType=TouchGesture])
Parameters:
Return type:

PySide2.QtCore.Qt.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.

static PySide2.QtWidgets.QScroller.grabbedGesture(target)
Parameters:targetPySide2.QtCore.QObject
Return type:PySide2.QtCore.Qt.GestureType

Returns the gesture type currently grabbed for the target or 0 if no gesture is grabbed.

PySide2.QtWidgets.QScroller.handleInput(input, position[, timestamp=0])
Parameters:
Return type:

PySide2.QtCore.bool

This function is used by gesture recognizers to inform the scroller about a new input event. The scroller changes its internal PySide2.QtWidgets.QScroller.state() according to the input event and its attached scroller properties. The scroller doesn’t distinguish between the kind of input device the event came from. Therefore the event needs to be split into the input type, a position and a milli-second timestamp . The position needs to be in the target’s coordinate system.

The return value is true if the event should be consumed by the calling filter or false if the event should be forwarded to the control.

Note

Using PySide2.QtWidgets.QScroller.grabGesture() should be sufficient for most use cases.

static PySide2.QtWidgets.QScroller.hasScroller(target)
Parameters:targetPySide2.QtCore.QObject
Return type:PySide2.QtCore.bool

Returns true if a PySide2.QtWidgets.QScroller object was already created for target ; false otherwise.

PySide2.QtWidgets.QScroller.pixelPerMeter()
Return type:PySide2.QtCore.QPointF

Returns the pixel per meter metric for the scrolled widget.

The value is reported for both the x and y axis separately by using a PySide2.QtCore.QPointF .

Note

Please note that this value should be physically correct. The actual DPI settings that Qt returns for the display may be reported wrongly on purpose by the underlying windowing system, for example on macOS .

PySide2.QtWidgets.QScroller.resendPrepareEvent()

This function resends the PySide2.QtGui.QScrollPrepareEvent . Calling triggers a PySide2.QtGui.QScrollPrepareEvent from the scroller. This allows the receiver to re-set content position and content size while scrolling. Calling this function while in the Inactive state is useless as the prepare event is sent again before scrolling starts.

PySide2.QtWidgets.QScroller.scrollTo(pos, scrollTime)
Parameters:

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

PySide2.QtWidgets.QScroller.scrollTo(pos)
Parameters:posPySide2.QtCore.QPointF

Starts scrolling the widget so that point pos is at the top-left position in the viewport.

The behaviour when scrolling outside the valid scroll area is undefined. In this case the scroller might or might not overshoot.

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

pos is given in viewport coordinates.

static PySide2.QtWidgets.QScroller.scroller(target)
Parameters:targetPySide2.QtCore.QObject
Return type:PySide2.QtWidgets.QScroller

This is an overloaded function.

This is the const version of PySide2.QtWidgets.QScroller.scroller() .

static PySide2.QtWidgets.QScroller.scroller(target)
Parameters:targetPySide2.QtCore.QObject
Return type:PySide2.QtWidgets.QScroller

Returns the scroller for the given target . As long as the object exists this function will always return the same PySide2.QtWidgets.QScroller instance. If no PySide2.QtWidgets.QScroller exists for the target , one will implicitly be created. At no point more than one PySide2.QtWidgets.QScroller will be active on an object.

PySide2.QtWidgets.QScroller.scrollerProperties()
Return type:PySide2.QtWidgets.QScrollerProperties
PySide2.QtWidgets.QScroller.scrollerPropertiesChanged(arg__1)
Parameters:arg__1PySide2.QtWidgets.QScrollerProperties
PySide2.QtWidgets.QScroller.setScrollerProperties(prop)
Parameters:propPySide2.QtWidgets.QScrollerProperties
PySide2.QtWidgets.QScroller.setSnapPositionsX(first, interval)
Parameters:
  • firstPySide2.QtCore.qreal
  • intervalPySide2.QtCore.qreal

Set the snap positions for the horizontal axis to regular spaced intervals. The first snap position is at first . The next at first + interval . This can be used to implement a list header. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an interval of 0.0

PySide2.QtWidgets.QScroller.setSnapPositionsX(positions)
Parameters:positions

Set the snap positions for the horizontal axis to a list of positions . This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an empty list of positions.

PySide2.QtWidgets.QScroller.setSnapPositionsY(positions)
Parameters:positions

Set the snap positions for the vertical axis to a list of positions . This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an empty list of positions.

PySide2.QtWidgets.QScroller.setSnapPositionsY(first, interval)
Parameters:
  • firstPySide2.QtCore.qreal
  • intervalPySide2.QtCore.qreal

Set the snap positions for the vertical axis to regular spaced intervals. The first snap position is at first . The next at first + interval . This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an interval of 0.0

PySide2.QtWidgets.QScroller.state()
Return type:PySide2.QtWidgets.QScroller.State
PySide2.QtWidgets.QScroller.stateChanged(newstate)
Parameters:newstatePySide2.QtWidgets.QScroller.State
PySide2.QtWidgets.QScroller.stop()

Stops the scroller and resets its state back to Inactive.

PySide2.QtWidgets.QScroller.target()
Return type:PySide2.QtCore.QObject

Returns the target object of this scroller.

static PySide2.QtWidgets.QScroller.ungrabGesture(target)
Parameters:targetPySide2.QtCore.QObject

Ungrabs the gesture for the target . Does nothing if no gesture is grabbed.

PySide2.QtWidgets.QScroller.velocity()
Return type:PySide2.QtCore.QPointF

Returns the current scrolling velocity in meter per second when the state is Scrolling or Dragging. Returns a zero velocity otherwise.

The velocity is reported for both the x and y axis separately by using a PySide2.QtCore.QPointF .