![]() |
Home · All Classes · All Functions · Overviews |
The QAbstractKineticScroller class enables kinetic scrolling for any scrolling widget or graphics item. More...
#include <QAbstractKineticScroller>
This class was introduced in Qt 4.6.
enum | Mode { AutoMode, PushMode, AccelerationMode } |
enum | State { Inactive, MousePressed, Pushing, AutoScrolling } |
~QAbstractKineticScroller () | |
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 |
int | panningThreshold () const |
void | reset () |
void | scrollTo ( const QPoint & pos ) |
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 | setPanningThreshold ( int threshold ) |
State | state () const |
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 |
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)
scroller->setEnabled(false);
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.
This enum contains the different modes for the QMaemo5KineticScroller.
Constant | Value | Description |
---|---|---|
QAbstractKineticScroller::AutoMode | 0 | The mode will allow both pushing and acceleration. |
QAbstractKineticScroller::PushMode | 1 | The area will be scrolled as long as the user drags it around with pressed mouse button. |
QAbstractKineticScroller::AccelerationMode | 2 | The area will continue scrolling after the user releases the mouse button. |
This enum describes the possible states the kinetic scroller can be in.
Constant | Value | Description |
---|---|---|
QAbstractKineticScroller::Inactive | 0 | The scroller is inactive. It may also have been disabled. |
QAbstractKineticScroller::MousePressed | 1 | The user has pressed the mouse button (or pressed the the touch screen). |
QAbstractKineticScroller::Pushing | 2 | The user is dragging the mouse cursor (or other input point) over the scroll area. |
QAbstractKineticScroller::AutoScrolling | 3 | Scrolling is occurring without direct user input. |
Constructs a new kinetic scroller.
Destroys the scroller.
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.
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.
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().
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().
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().
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().
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().
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.
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().
Returns wether this kinetic scroller is enabled or not.
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().
Returns the maximum valid scroll position. The minimum is always (0,0).
See also scrollTo().
Returns the maximum scrolling velocity.
The maximum velocity is the slowest speed used in the acceleration mode.
See also setMaximumVelocity().
Returns the minimum scrolling velocity.
The minimum velocity is the slowest speed used in the acceleration mode.
See also setMinimumVelocity().
Returns the scrolling mode.
Returns the amount in pixels the point of input must move before scrolling is started.
See also setPanningThreshold().
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.
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().
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().
Sets the deceleration factor to f.
See also decelerationFactor().
Sets the margin of error for the direction to the given errorMargin value.
See also directionErrorMargin().
Sets the value of the drag inertia to the given inertia value.
See also dragInertia().
If enable is true, enables the kinetic scroller; otherwise disables it.
See also isEnabled().
Sets the fast velocity factor to f.
See also fastVelocityFactor().
If enable is true, enables low-friction mode; otherwise disables it.
See also decelerationFactor() and isLowFrictionEnabled().
Sets the maximum scrolling velocity to v.
See also maximumVelocity().
Sets the minimum scrolling velocity to v.
See also minimumVelocity().
Set the scrolling mode to the given mode.
Sets the panning threshold to the given threshold value.
See also panningThreshold().
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().
Returns the current state of the kinetic scroller.
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().
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().
Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies) | Trademarks | Qt 4.6.2 |