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

Inheritance diagram for QScroller:

Public Types
enum	Input

enum	ScrollerGestureType

enum	State

Public Signals
void	scrollerPropertiesChanged (const QScrollerProperties &newProperties)

void	stateChanged (QScroller::State newState)

Public Signals inherited from QObject
void	destroyed (QObject *obj=nullptr)

void	objectNameChanged (const QString &objectName)

Public Slots
void	ensureVisible (const QRectF &rect, qreal xmargin, qreal ymargin)

void	ensureVisible (const QRectF &rect, qreal xmargin, qreal ymargin, int scrollTime)

void	resendPrepareEvent ()

void	scrollTo (const QPointF &pos)

void	scrollTo (const QPointF &pos, int scrollTime)

void	setScrollerProperties (const QScrollerProperties &prop)

Public Slots inherited from QObject
void	deleteLater ()

Public Methods
QPointF	finalPosition () const

bool	handleInput (Input input, const QPointF &position, qint64 timestamp=0)

QPointF	pixelPerMeter () const

QScrollerProperties	scrollerProperties () const

void	setSnapPositionsX (const QList< qreal > &positions)

void	setSnapPositionsX (qreal first, qreal interval)

void	setSnapPositionsY (const QList< qreal > &positions)

void	setSnapPositionsY (qreal first, qreal interval)

State	state () const

void	stop ()

QObject *	target () const

QPointF	velocity () const

Public Methods inherited from QObject
	QObject (QObject *parent=nullptr)

	~QObject ()

bool	blockSignals (bool block)

const QList< QObject * > &	children () const

bool	connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QString >	dynamicPropertyNames () const

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

template<typename T >
T	findChild (const QString &childName=QString ()) const

template<class T >
QList< T >	findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<class T >
QList< T >	findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

bool	inherits (const QString &className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	property (const QString &name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const QString &name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

QThread *	thread () const

Static Public Methods
static QList< QScroller * >	activeScrollers ()

static Qt::GestureType	grabbedGesture (QObject *target)

static Qt::GestureType	grabGesture (QObject *target, ScrollerGestureType gestureType=TouchGesture)

static bool	hasScroller (QObject *target)

static const QScroller *	scroller (const QObject *target)

static QScroller *	scroller (QObject *target)

static void	ungrabGesture (QObject *target)

Static Public Methods inherited from QObject
static bool	connect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

static bool	connect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())

static bool	connect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, std::nullptr_t, const QObject receiver, std::nullptr_t)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...))

template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)

static QMetaObject &	staticMetaObject ()

static QString	tr (const char text, const char comment=nullptr, std::optional< int > numArg=std::optional< int >())

Properties
	scrollerProperties

	state

Properties inherited from QObject
	objectName

Additional Inherited Members
Protected Methods inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signalMethod) const

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signalMethod) const

bool	isSignalConnected (const QMetaMethod &signalMethod) const

int	receivers (const QString &signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

Detailed Description

The 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 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 as shown in the first example.

QWidget *widget = ...;

QScroller::grabGesture(widget, QScroller::LeftMouseButtonGesture);

It can also be set up directly as in this example.

QWidget *widget = ...;
QScroller *scroller = QScroller::scroller(widget);
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 QScrollerProperties::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 the plot example in the scroller examples directory.

See also: QScrollEvent, QScrollPrepareEvent, QScrollerProperties

Member Enumeration Documentation

enum QScroller::Input

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

Constant	Value	Description
QScroller::InputPress	1	User pressed the input device (e.g. QEvent::MouseButtonPress, QEvent::GraphicsSceneMousePress, QEvent::TouchBegin)
QScroller::InputMove	2	User moved the input device (e.g. QEvent::MouseMove, QEvent::GraphicsSceneMouseMove, QEvent::TouchUpdate)
QScroller::InputRelease	3	User released the input device (e.g. QEvent::MouseButtonRelease, QEvent::GraphicsSceneMouseRelease, QEvent::TouchEnd)

enum QScroller::ScrollerGestureType

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

Constant	Value	Description
QScroller::TouchGesture	0	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	1	Gesture recognizer will only trigger on left mouse button events.
QScroller::MiddleMouseButtonGesture	3	Gesture recognizer will only trigger on middle mouse button events.
QScroller::RightMouseButtonGesture	2	Gesture recognizer will only trigger on right mouse button events.

enum QScroller::State

This enum contains the different QScroller states.

Constant

Value

Description

QOpenGLWidget::NoPartialUpdate

0

QOpenGLWidget will discard the contents of the color buffer and the ancillary buffers after the QOpenGLWidget is rendered to screen. This is the same behavior that can be expected by calling QOpenGLContext::swapBuffers with a default opengl enabled QWindow as the argument. NoPartialUpdate can have some performance benefits on certain hardware architectures common in the mobile and embedded space when a framebuffer object is used as the rendering target. The framebuffer object is invalidated between frames with glDiscardFramebufferEXT if supported or a glClear.

Refer to the documentation of EXT_discard_framebuffer for more information:
https://www.khronos.org/registry/gles/extensions/EXT/EXT_discard_framebuffer.txt

QOpenGLWidget::PartialUpdate

1

The framebuffer objects color buffer and ancillary buffers are not invalidated between frames.

Method Documentation

QList< QScroller * > QScroller::activeScrollers ( )

static

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

void QScroller::ensureVisible	(	const QRectF &	rect,
		qreal	xmargin,
		qreal	ymargin
	)

slot

Starts scrolling so rect is visible inside the viewport with additional margins specified in pixels by xmargin and ymargin around the rectangle. In cases where it is not possible to fit the rectangle plus margins inside the viewport the contents are scrolled to make as much of the rectangle visible as possible. The scrolling speed is calculated so the given position is reached after a platform-defined time span.

This method performs scrolling by calling scrollTo().

See also: scrollTo()

void QScroller::ensureVisible	(	const QRectF &	rect,
		qreal	xmargin,
		qreal	ymargin,
		int	scrollTime
	)

slot

This version of ensureVisible() will reach its destination position in scrollTime milliseconds.

QPointF QScroller::finalPosition ( ) const

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()

Qt::GestureType QScroller::grabbedGesture ( QObject * target )

static

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

See also: grabGesture(), ungrabGesture()

Qt::GestureType QScroller::grabGesture	(	QObject *	target,
		QScroller::ScrollerGestureType	gestureType = `TouchGesture`
	)

static

Registers a custom scroll gesture recognizer, grabs it for the target and returns the resulting gesture type. If gestureType 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 method 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: ungrabGesture(), grabbedGesture()

bool QScroller::handleInput	(	QScroller::Input	input,
		const QPointF &	position,
		qint64	timestamp = `0`
	)

This method is used by gesture recognizers to inform the scroller about a new input event. 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.

bool QScroller::hasScroller ( QObject * target )

static

Returns true if a QScroller object was already created for the target, otherwise returns false.

See also: scroller()

QPointF QScroller::pixelPerMeter ( ) const

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.

This value should be physically correct. The actual DPI settings returned for the display may be reported incorrectly on purpose by the underlying windowing system, for example on Mac OS X.

void QScroller::resendPrepareEvent ( )

slot

Resends the QScrollPrepareEvent. Calling this method triggers a QScrollPrepareEvent from the scroller. This allows the receiver to re-set content position and content size while scrolling. There is no reason to call this method when the scroller is in the Inactive state since the prepare event is sent again before scrolling starts.

const QScroller * QScroller::scroller ( const QObject * target )

static

This is the const version of of the scroller() method.

QScroller * QScroller::scroller ( QObject * target )

static

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

See also: hasScroller(), target()

QScrollerProperties QScroller::scrollerProperties ( ) const

Returns the value of the property.

void QScroller::scrollerPropertiesChanged ( const QScrollerProperties & newProperties )

signal

This signal is emitted when the value of the property changes. The specified newProperties represents the updated value.

See also: QScroller::scrollerProperties

void QScroller::scrollTo ( const QPointF & pos )

slot

Starts scrolling the widget to pos, which is at the top-left position in the viewport. The behavior 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.

The given pos is in viewport coordinates.

See also: ensureVisible()

void QScroller::scrollTo	(	const QPointF &	pos,
		int	scrollTime
	)

slot

This version of scrollTo() will reach its destination position in scrollTime milliseconds.

void QScroller::setScrollerProperties ( const QScrollerProperties & prop )

slot

Sets the value of the property to prop.

void QScroller::setSnapPositionsX ( const QList< qreal > & 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.

void QScroller::setSnapPositionsX	(	qreal	first,
		qreal	interval
	)

Set the snap positions for the horizontal axis to regular spaced intervals. The first snap position is at first. The next at first plus 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.

void QScroller::setSnapPositionsY ( const QList< qreal > & 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.

void QScroller::setSnapPositionsY	(	qreal	first,
		qreal	interval
	)

Set the snap positions for the vertical axis to regular spaced intervals. The first snap position is at first. The next at first plus 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.

QScroller::State QScroller::state ( ) const

Returns the value of the property.

void QScroller::stateChanged ( QScroller::State newState )

signal

This signal is emitted when the value of the property changes. The specified newState represents the updated value.

See also: QScroller::state

void QScroller::stop ( )

Stops the scroller and resets its state back to Inactive.

QObject * QScroller::target ( ) const

Returns the target object of this scroller.

See also: hasScroller(), scroller()

void QScroller::ungrabGesture ( QObject * target )

static

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

See also: grabGesture(), grabbedGesture()

QPointF QScroller::velocity ( ) const

Returns the current scrolling velocity in meters 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: pixelPerMeter()

Property Documentation

QScroller::scrollerProperties

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

Properties	Class Methods
read	scrollerProperties
write	setScrollerProperties
notify	scrollerPropertiesChanged

QScroller::state

This property holds the state of the scroller.

See also: QScroller::State

Properties	Class Methods
read	state
notify	stateChanged

Public Types

Public Signals

Public Slots

Public Methods

Static Public Methods

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Method Documentation

Property Documentation