Qt Reference Documentation

QAbstractKineticScroller Class Reference

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

 #include <QAbstractKineticScroller>

This class is under development and is subject to change.

This class was introduced in Qt 4.6.

Public Types

enum Mode { AutoMode, PushMode, AccelerationMode }
enum OvershootPolicy { OvershootWhenScrollable, OvershootAlwaysOff, OvershootAlwaysOn }
enum State { Inactive, MousePressed, Pushing, AutoScrolling }

Public Functions

~QAbstractKineticScroller ()
qreal axisLockThreshold () const
qreal decelerationFactor () const
int directionErrorMargin () const
qreal dragInertia () const
void ensureVisible ( const QPoint & pos, int xmargin = 50, int ymargin = 50 )
qreal fastVelocityFactor () const
bool isEnabled () const
bool isLowFrictionEnabled () const
qreal maximumVelocity () const
qreal minimumVelocity () const
Mode mode () const
OvershootPolicy overshootPolicy () const
int panningThreshold () const
void reset ()
void scrollTo ( const QPoint & pos )
int scrollsPerSecond () const
void setAxisLockThreshold ( qreal threshold )
void setDecelerationFactor ( qreal f )
void setDirectionErrorMargin ( int errorMargin )
void setDragInertia ( qreal inertia )
void setEnabled ( bool enable )
void setFastVelocityFactor ( qreal f )
void setLowFrictionEnabled ( bool enable )
void setMaximumVelocity ( qreal v )
void setMinimumVelocity ( qreal v )
void setMode ( Mode mode )
void setOvershootPolicy ( OvershootPolicy policy )
void setPanningThreshold ( int threshold )
void setScrollsPerSecond ( int sps )
State state () const

Protected Functions

QAbstractKineticScroller ()
virtual bool canStartScrollingAt ( const QPoint & globalPos ) const
virtual void cancelLeftMouseButtonPress ( const QPoint & globalPressPos )
bool handleMouseEvent ( QMouseEvent * event )
bool handleMouseEvent ( QGraphicsSceneMouseEvent * event )
virtual QPoint maximumScrollPosition () const = 0
virtual QPoint scrollPosition () const = 0
virtual void setScrollPosition ( const QPoint & pos, const QPoint & overshoot ) = 0
virtual void stateChanged ( State oldState )
virtual QSize viewportSize () const = 0

Detailed Description

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

To enable kinetic scrolling for a widget or graphics item, you need to derive from this class and implement at least all the pure-virtual functions.

Qt for Maemo 5 already comes with two implementations for QAbstractScrollArea and QWebView, and those kinetic scrollers are automatically instantiated and attached to these widgets on creation. In the QAbstractScrollArea case, the kinetic scroller is initially disabled. However, for QAbstractItemView and QScrollArea derived classes it is enabled by default. You can obtain these automatically created objects via a dynamic property:

 // disable the kinetic scroller on scrollArea
 QAbstractKineticScroller *scroller = scrollArea->property("kineticScroller")
                                          .value<QAbstractKineticScroller *>();
 if (scroller)

In addition there is also an example on how you would add kinetic scrolling to a QGraphicsView based application in maemobrowser examples in the maemo5 examples directory.

The kinetic scroller installs an event filter on the widget to handle mouse presses and moves on the widget — presses and moves on a device's touch screen are also handled by this mechanism. These events will be interpreted as scroll actions depending on the current state() of the scroller.

Even though this kinetic scroller has a huge number of settings, we recommend that you leave them all at their default values. In case you really want to change them you can try out the kineticscroller example in the maemo5 examples directory.

See also QWidget.

Member Type Documentation

enum QAbstractKineticScroller::Mode

This enum contains the different modes for the QAbstractKineticScroller.

QAbstractKineticScroller::AutoMode0The mode will allow both pushing and acceleration.
QAbstractKineticScroller::PushMode1The area will be scrolled as long as the user drags it around with pressed mouse button.
QAbstractKineticScroller::AccelerationMode2The area will continue scrolling after the user releases the mouse button.

enum QAbstractKineticScroller::OvershootPolicy

This enum describes the various modes of overshooting.

QAbstractKineticScroller::OvershootWhenScrollable0Overshooting is when the content is scrollable. This is the default.
QAbstractKineticScroller::OvershootAlwaysOff1Overshooting is never enabled (even when the content is scrollable).
QAbstractKineticScroller::OvershootAlwaysOn2Overshooting is always enabled (even when the content is not scrollable).

enum QAbstractKineticScroller::State

This enum describes the possible states the kinetic scroller can be in.

QAbstractKineticScroller::Inactive0The scroller is inactive. It may also have been disabled.
QAbstractKineticScroller::MousePressed1The user has pressed the mouse button (or pressed the the touch screen).
QAbstractKineticScroller::Pushing2The user is dragging the mouse cursor (or other input point) over the scroll area.
QAbstractKineticScroller::AutoScrolling3Scrolling is occurring without direct user input.

Member Function Documentation

QAbstractKineticScroller::QAbstractKineticScroller () [protected]

Constructs a new kinetic scroller.

QAbstractKineticScroller::~QAbstractKineticScroller ()

Destroys the scroller.

qreal QAbstractKineticScroller::axisLockThreshold () const

Returns the axis lock threshold.

On every mouse move, the scroller computes the angle between the vector of the mouse movement the and the nearest X or Y axis.

If the tangens of this angle is less than the axis lock threshold, the scroll direction is restricted to the nearest axis.

The threshold is a floating point value in the range 0.0 to 1.0.

The default value of 0.0 will not restrict the scroll direction at all, while a value of 1.0 (wich corresponds to a 45 degree angle) restricts the scroll direction to either the X or Y axis.

See also setAxisLockThreshold().

bool QAbstractKineticScroller::canStartScrollingAt ( const QPoint & globalPos ) const [virtual protected]

If kinetic scrolling can be started at the global screen coordinate globalPos within the widget or graphics object, this function needs to return true; otherwise it needs to return false.

The default value is true, regardless of globalPos.

void QAbstractKineticScroller::cancelLeftMouseButtonPress ( const QPoint & globalPressPos ) [virtual protected]

Since a mouse press is always delivered normally when the scroller is in the Inactive state, we may need to cancel it as soon as the user has moved the mouse far enough to actually start a kinetic scroll operation.

The globalPressPos parameter can be used to find out which widget received the mouse press in the first place.

Subclasses may choose to simulate a fake mouse release event for that widget, preferably not within its boundaries. The default implementation does nothing.

qreal QAbstractKineticScroller::decelerationFactor () const

Returns the deceleration factor used to slow down scrolling over time.

This value is the percentage (expressed as a value between 0.0 and 1.0) of the scrolling velocity remaining after every scroll step.

See also setDecelerationFactor().

int QAbstractKineticScroller::directionErrorMargin () const

Returns the margin of error that controls how close to horizontal and vertical motion the user's input must be to cause scrolling to occur.

This value influences whether a scroll is recognized as such if the point of input moved diagonally.

See also setDirectionErrorMargin().

qreal QAbstractKineticScroller::dragInertia () const

Returns the value of the drag inertia.

This value is a value between 0.0 and 1.0 that describes the effect of dragging on a scrolling widget that may already be scrolling. This value is used to smoothen the user input from the dragging motion.

A value of 0.0 causes no scrolling to occur at all if the widget is not scrolling. A value of 1.0 causes the dragging motion to dominate, but may result in oversensitive scrolling behavior.

By default, the drag inertia is set to 0.85. This smoothens the input, reducing the sensitivity of the widget to the dragging motion, while keeping it responsive.

See also setDragInertia().

void QAbstractKineticScroller::ensureVisible ( const QPoint & pos, int xmargin = 50, int ymargin = 50 )

Starts scrolling the widget so that the point pos is visible inside the viewport with margins specified in pixels by xmargin and ymargin.

If the specified point cannot be reached, the contents are scrolled to the nearest valid position. The default value for both margins is 50 pixels.

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

See also maximumScrollPosition().

qreal QAbstractKineticScroller::fastVelocityFactor () const

Returns the fast velocity factor. This value, between 0.0 and 1.0, is the factor that determines if the scrolling speed is too fast for a mouse click.

If the current velocity is greater then maximumVelocity()*fastVelocityFactor() then the mouse click (or press on a touch screen) will just stop the scrolling, and the scroller will not send the click event to the scroll area.

If the velocity is less than the calculated value then a click (or press) will stop the scrolling, and the scroller will send the click event to the scroll area for further processing.

See also setFastVelocityFactor().

bool QAbstractKineticScroller::handleMouseEvent ( QMouseEvent * event ) [protected]

This filter function changes, blocks or creates mouse events passed as event for the attached widget depending on the detected kinetic scrolling state.

Subclass implementations need to call this function for every mouse event.

The return value of this function is analogous to QObject::eventFilter(). Returns true if the event should be filtered out (not handled further); otherwise returns false.

bool QAbstractKineticScroller::handleMouseEvent ( QGraphicsSceneMouseEvent * event ) [protected]

This is an overloaded function.

This filter function changes, blocks or creates mouse events passed as event for the attached graphics item depending on the detected kinetic scrolling state.

See also handleMouseEvent().

bool QAbstractKineticScroller::isEnabled () const

Returns wether this kinetic scroller is enabled or not.

bool QAbstractKineticScroller::isLowFrictionEnabled () const

Returns the value of the low-friction mode.

Low friction means that scrolling will not be slowed down by the current deceleration factor.

See also decelerationFactor() and setLowFrictionEnabled().

QPoint QAbstractKineticScroller::maximumScrollPosition () const [pure virtual protected]

Returns the maximum valid scroll position. The minimum is always (0,0).

See also scrollTo().

qreal QAbstractKineticScroller::maximumVelocity () const

Returns the maximum scrolling velocity.

The maximum velocity is the slowest speed used in the acceleration mode.

See also setMaximumVelocity().

qreal QAbstractKineticScroller::minimumVelocity () const

Returns the minimum scrolling velocity.

The minimum velocity is the slowest speed used in the acceleration mode.

See also setMinimumVelocity().

Mode QAbstractKineticScroller::mode () const

Returns the scrolling mode.

See also setMode() and Mode.

OvershootPolicy QAbstractKineticScroller::overshootPolicy () const

Returns the overshooting policy.

The default policy is OvershootWhenScrollable.

See also setOvershootPolicy().

int QAbstractKineticScroller::panningThreshold () const

Returns the amount in pixels the point of input must move before scrolling is started.

See also setPanningThreshold().

void QAbstractKineticScroller::reset ()

Resets the internal state of the kinetic scroller. This function is not needed for normal use. This function only needs to be called if the kinetic scroller is being re-attached to a different widget.

QPoint QAbstractKineticScroller::scrollPosition () const [pure virtual protected]

Returns the current scroll position. Note that overshooting is not considered to be "real" scrolling so the position might be (0,0) even if the user is currently dragging the widget outside the "normal" maximumScrollPosition().

See also setScrollPosition() and maximumScrollPosition().

void QAbstractKineticScroller::scrollTo ( const QPoint & pos )

Starts scrolling the widget so that the point pos is visible inside the viewport.

If the specified point cannot be reached, the contents are scrolled to the nearest valid position.

The scrolling speed will be calculated so that the given position will be reached after a platform-defined time span (1 second for Maemo 5). The final speed at the end position is not guaranteed to be zero.

See also ensureVisible() and maximumScrollPosition().

int QAbstractKineticScroller::scrollsPerSecond () const

Returns the number of scrolls (frames) per second.

This is the frame rate which will be used when the scroller is in the AutoScrolling state.

The default value for Maemo 5 is 20.

See also setScrollsPerSecond().

void QAbstractKineticScroller::setAxisLockThreshold ( qreal threshold )

Sets the axis lock threshold.

See also axisLockThreshold().

void QAbstractKineticScroller::setDecelerationFactor ( qreal f )

Sets the deceleration factor to f.

See also decelerationFactor().

void QAbstractKineticScroller::setDirectionErrorMargin ( int errorMargin )

Sets the margin of error for the direction to the given errorMargin value.

See also directionErrorMargin().

void QAbstractKineticScroller::setDragInertia ( qreal inertia )

Sets the value of the drag inertia to the given inertia value.

See also dragInertia().

void QAbstractKineticScroller::setEnabled ( bool enable )

If enable is true, enables the kinetic scroller; otherwise disables it.

See also isEnabled().

void QAbstractKineticScroller::setFastVelocityFactor ( qreal f )

Sets the fast velocity factor to f.

See also fastVelocityFactor().

void QAbstractKineticScroller::setLowFrictionEnabled ( bool enable )

If enable is true, enables low-friction mode; otherwise disables it.

See also decelerationFactor() and isLowFrictionEnabled().

void QAbstractKineticScroller::setMaximumVelocity ( qreal v )

Sets the maximum scrolling velocity to v.

See also maximumVelocity().

void QAbstractKineticScroller::setMinimumVelocity ( qreal v )

Sets the minimum scrolling velocity to v.

See also minimumVelocity().

void QAbstractKineticScroller::setMode ( Mode mode )

Set the scrolling mode to the given mode.

See also mode() and Mode.

void QAbstractKineticScroller::setOvershootPolicy ( OvershootPolicy policy )

Sets the overshooting policy to policy.

See also overshootPolicy().

void QAbstractKineticScroller::setPanningThreshold ( int threshold )

Sets the panning threshold to the given threshold value.

See also panningThreshold().

void QAbstractKineticScroller::setScrollPosition ( const QPoint & pos, const QPoint & overshoot ) [pure virtual protected]

Sets the scroll position of the widget to pos. This parameter will always be in the valid range returned by maximumScrollPosition().

In the case where overshooting is required, the overshoot parameter will give the direction and the absolute pixel distance to overshoot.

See also scrollPosition() and maximumScrollPosition().

void QAbstractKineticScroller::setScrollsPerSecond ( int sps )

Sets the number of scrolls (frames) per second to sps.

See also scrollsPerSecond().

State QAbstractKineticScroller::state () const

Returns the current state of the kinetic scroller.

void QAbstractKineticScroller::stateChanged ( State oldState ) [virtual protected]

This function get called whenever the state of the kinetic scroller changes. The old state is supplied as oldState, while the new state is returned by calling state().

The default implementation does nothing.

See also state().

QSize QAbstractKineticScroller::viewportSize () const [pure virtual protected]

Returns the size of the currently visible scroll positions. In the case where an QAbstractScrollArea is used, this is equivalent to the viewport() size.

See also scrollTo().


Thank you for giving your feedback.

Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.

[0]; s.parentNode.insertBefore(ga, s); })();