QScroller Class

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

Header:	#include <QScroller>
qmake:	QT += widgets
Since:	Qt 5.0
Inherits:	QObject

This class was introduced in Qt 5.0.

List of all members, including inherited members

Public Types

enum	Input { InputPress, InputMove, InputRelease }
enum	ScrollerGestureType { TouchGesture, LeftMouseButtonGesture, MiddleMouseButtonGesture, RightMouseButtonGesture }
enum	State { Inactive, Pressed, Dragging, Scrolling }

Properties

scrollerProperties : QScrollerProperties
state : const State

Public Functions

QScrollerProperties	scrollerProperties() const
QScroller::State	state() const

Public Slots

void	setScrollerProperties(const QScrollerProperties &prop)

Signals

void	scrollerPropertiesChanged(const QScrollerProperties &)
void	stateChanged(QScroller::State newstate)

Detailed Description

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

     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 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.

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, and QScrollerProperties.

Member Type 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`	The user pressed the input device (e.g. QEvent::MouseButtonPress, QEvent::GraphicsSceneMousePress, QEvent::TouchBegin)
`QScroller::InputMove`	`2`	The user moved the input device (e.g. QEvent::MouseMove, QEvent::GraphicsSceneMouseMove, QEvent::TouchUpdate)
`QScroller::InputRelease`	`3`	The 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`	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`	`1`	The gesture recognizer will only trigger on left mouse button events.
`QScroller::MiddleMouseButtonGesture`	`3`	The gesture recognizer will only trigger on middle mouse button events.
`QScroller::RightMouseButtonGesture`	`2`	The gesture recognizer will only trigger on right mouse button events.

enum QScroller::State

This enum contains the different QScroller states.

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

Property Documentation

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:

QScrollerProperties	scrollerProperties() const
void	setScrollerProperties(const QScrollerProperties &prop)

Notifier signal:

void	scrollerPropertiesChanged(const QScrollerProperties &)

state : const State

This property holds the state of the scroller