- class 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 behaviorstateᅟ
- The state of the scroller
Methods#
def
finalPosition()
def
handleInput()
def
pixelPerMeter()
def
state()
def
stop()
def
target()
def
velocity()
Slots#
def
ensureVisible()
def
scrollTo()
Signals#
Static functions#
def
grabGesture()
def
grabbedGesture()
def
hasScroller()
def
scroller()
def
ungrabGesture()
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 gesturew = ... 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.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 theplot
example in thescroller
examples directory.See also
- class 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.
- class 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.
- class 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. 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)
Note
Properties can be used directly when
from __feature__ import true_property
is used or via accessor functions otherwise.- property scrollerPropertiesᅟ: QScrollerProperties#
This property holds The scroller properties of this scroller. The properties are used by the
QScroller
to determine its scrolling behavior..- Access functions:
- property stateᅟ: QScroller.State#
This property holds the state of the scroller.
See also
- Access functions:
Signal
stateChanged()
Returns an application wide list of currently active
QScroller
objects. ActiveQScroller
objects are in astate()
that is notInactive
. This function is useful when writing your own gesture recognizer.Starts scrolling so that the rectangle
rect
is visible inside the viewport with additional margins specified in pixels byxmargin
andymargin
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
- ensureVisible(rect, xmargin, ymargin, scrollTime)
- Parameters:
rect –
QRectF
xmargin – float
ymargin – float
scrollTime – int
This is an overloaded function.
This version will reach its destination position in
scrollTime
milliseconds.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
- static grabGesture(target[, gestureType=QScroller.ScrollerGestureType.TouchGesture])#
- Parameters:
target –
QObject
gestureType –
ScrollerGestureType
- Return type:
Registers a custom scroll gesture recognizer, grabs it for the
target
and returns the resulting gesture type. IfscrollGestureType
is set toTouchGesture
the gesture triggers on touch events. If it is set to one ofLeftMouseButtonGesture
,RightMouseButtonGesture
orMiddleMouseButtonGesture
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.See also
Returns the gesture type currently grabbed for the
target
or 0 if no gesture is grabbed.See also
- handleInput(input, position[, timestamp=0])#
This function is used by gesture recognizers to inform the scroller about a new input event. The scroller changes its internal
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 theinput
type, aposition
and a milli-secondtimestamp
. Theposition
needs to be in the target’s coordinate system.The return value is
true
if the event should be consumed by the calling filter orfalse
if the event should be forwarded to the control.Note
Using
grabGesture()
should be sufficient for most use cases.Returns
true
if aQScroller
object was already created fortarget
;false
otherwise.See also
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 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.
- resendPrepareEvent()#
This function resends the QScrollPrepareEvent. Calling resendPrepareEvent triggers a 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.
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.See also
- scrollTo(pos, scrollTime)
- Parameters:
pos –
QPointF
scrollTime – int
This is an overloaded function.
This version will reach its destination position in
scrollTime
milliseconds.This is an overloaded function.
This is the const version of
scroller()
.Returns the scroller for the given
target
. As long as the object exists this function will always return the sameQScroller
instance. If noQScroller
exists for thetarget
, one will implicitly be created. At no point more than oneQScroller
will be active on an object.See also
- scrollerProperties()#
- Return type:
See also
Getter of property
scrollerPropertiesᅟ
.- scrollerPropertiesChanged(arg__1)#
- Parameters:
arg__1 –
QScrollerProperties
QScroller
emits this signal whenever its scroller properties change.newProperties
are the new scroller properties.See also
Notification signal of property
scrollerPropertiesᅟ
.- setScrollerProperties(prop)#
- Parameters:
prop –
QScrollerProperties
See also
Setter of property
scrollerPropertiesᅟ
.- setSnapPositionsX(positions)#
- Parameters:
positions – .list of qreal
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.- setSnapPositionsX(first, interval)
- Parameters:
first – float
interval – float
Set the snap positions for the horizontal axis to regular spaced intervals. The first snap position is at
first
. The next atfirst
+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- setSnapPositionsY(positions)#
- Parameters:
positions – .list of qreal
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.- setSnapPositionsY(first, interval)
- Parameters:
first – float
interval – float
Set the snap positions for the vertical axis to regular spaced intervals. The first snap position is at
first
. The next atfirst
+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.0Getter of property
stateᅟ
.QScroller
emits this signal whenever the state changes.newState
is the new State.See also
Notification signal of property
stateᅟ
.- stop()#
Stops the scroller and resets its state back to Inactive.
Returns the target object of this scroller.
See also
Ungrabs the gesture for the
target
. Does nothing if no gesture is grabbed.See also
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 QPointF.
See also