Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public class

OverScroller

extends Object
java.lang.Object
   ↳ android.widget.OverScroller

Class Overview

This class encapsulates scrolling with the ability to overshoot the bounds of a scrolling operation. This class is a drop-in replacement for Scroller in most cases.

Summary

Public Constructors
OverScroller ( Context context)
Creates an OverScroller with a viscous fluid scroll interpolator and flywheel.
OverScroller ( Context context, Interpolator interpolator)
Creates an OverScroller with flywheel enabled.
OverScroller ( Context context, Interpolator interpolator, float bounceCoefficientX, float bounceCoefficientY)
Creates an OverScroller with flywheel enabled.
OverScroller ( Context context, Interpolator interpolator, float bounceCoefficientX, float bounceCoefficientY, boolean flywheel)
Creates an OverScroller.
Public Methods
void abortAnimation ()
Stops the animation.
boolean computeScrollOffset ()
Call this when you want to know the new location.
void fling (int startX, int startY, int velocityX, int velocityY, int minX, int maxX, int minY, int maxY)
void fling (int startX, int startY, int velocityX, int velocityY, int minX, int maxX, int minY, int maxY, int overX, int overY)
Start scrolling based on a fling gesture.
final void forceFinished (boolean finished)
Force the finished field to a particular value.
float getCurrVelocity ()
Returns the absolute value of the current velocity.
final int getCurrX ()
Returns the current X offset in the scroll.
final int getCurrY ()
Returns the current Y offset in the scroll.
final int getFinalX ()
Returns where the scroll will end.
final int getFinalY ()
Returns where the scroll will end.
final int getStartX ()
Returns the start X offset in the scroll.
final int getStartY ()
Returns the start Y offset in the scroll.
final boolean isFinished ()
Returns whether the scroller has finished scrolling.
boolean isOverScrolled ()
Returns whether the current Scroller is currently returning to a valid position.
void notifyHorizontalEdgeReached (int startX, int finalX, int overX)
Notify the scroller that we've reached a horizontal boundary.
void notifyVerticalEdgeReached (int startY, int finalY, int overY)
Notify the scroller that we've reached a vertical boundary.
final void setFriction (float friction)
The amount of friction applied to flings.
boolean springBack (int startX, int startY, int minX, int maxX, int minY, int maxY)
Call this when you want to 'spring back' into a valid coordinate range.
void startScroll (int startX, int startY, int dx, int dy)
Start scrolling by providing a starting point and the distance to travel.
void startScroll (int startX, int startY, int dx, int dy, int duration)
Start scrolling by providing a starting point and the distance to travel.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public OverScroller ( Context context)

Added in API level 9

Creates an OverScroller with a viscous fluid scroll interpolator and flywheel.

public OverScroller ( Context context, Interpolator interpolator)

Added in API level 9

Creates an OverScroller with flywheel enabled.

Parameters
context The context of this application.
interpolator The scroll interpolator. If null, a default (viscous) interpolator will be used.

public OverScroller ( Context context, Interpolator interpolator, float bounceCoefficientX, float bounceCoefficientY)

Added in API level 9

Creates an OverScroller with flywheel enabled.

Parameters
context The context of this application.
interpolator The scroll interpolator. If null, a default (viscous) interpolator will be used.
bounceCoefficientX A value between 0 and 1 that will determine the proportion of the velocity which is preserved in the bounce when the horizontal edge is reached. A null value means no bounce. This behavior is no longer supported and this coefficient has no effect.
bounceCoefficientY Same as bounceCoefficientX but for the vertical direction. This behavior is no longer supported and this coefficient has no effect. !deprecated Use {!link #OverScroller(Context, Interpolator, boolean)} instead.

public OverScroller ( Context context, Interpolator interpolator, float bounceCoefficientX, float bounceCoefficientY, boolean flywheel)

Creates an OverScroller.

Parameters
context The context of this application.
interpolator The scroll interpolator. If null, a default (viscous) interpolator will be used.
bounceCoefficientX A value between 0 and 1 that will determine the proportion of the velocity which is preserved in the bounce when the horizontal edge is reached. A null value means no bounce. This behavior is no longer supported and this coefficient has no effect.
bounceCoefficientY Same as bounceCoefficientX but for the vertical direction. This behavior is no longer supported and this coefficient has no effect.
flywheel If true, successive fling motions will keep on increasing scroll speed. !deprecated Use {!link OverScroller(Context, Interpolator, boolean)} instead.

Public Methods

public void abortAnimation ()

Added in API level 9

Stops the animation. Contrary to forceFinished(boolean) , aborting the animating causes the scroller to move to the final x and y positions.

See Also

public boolean computeScrollOffset ()

Added in API level 9

Call this when you want to know the new location. If it returns true, the animation is not yet finished.

public void fling (int startX, int startY, int velocityX, int velocityY, int minX, int maxX, int minY, int maxY)

Added in API level 9

public void fling (int startX, int startY, int velocityX, int velocityY, int minX, int maxX, int minY, int maxY, int overX, int overY)

Added in API level 9

Start scrolling based on a fling gesture. The distance traveled will depend on the initial velocity of the fling.

Parameters
startX Starting point of the scroll (X)
startY Starting point of the scroll (Y)
velocityX Initial velocity of the fling (X) measured in pixels per second.
velocityY Initial velocity of the fling (Y) measured in pixels per second
minX Minimum X value. The scroller will not scroll past this point unless overX > 0. If overfling is allowed, it will use minX as a springback boundary.
maxX Maximum X value. The scroller will not scroll past this point unless overX > 0. If overfling is allowed, it will use maxX as a springback boundary.
minY Minimum Y value. The scroller will not scroll past this point unless overY > 0. If overfling is allowed, it will use minY as a springback boundary.
maxY Maximum Y value. The scroller will not scroll past this point unless overY > 0. If overfling is allowed, it will use maxY as a springback boundary.
overX Overfling range. If > 0, horizontal overfling in either direction will be possible.
overY Overfling range. If > 0, vertical overfling in either direction will be possible.

public final void forceFinished (boolean finished)

Added in API level 9

Force the finished field to a particular value. Contrary to abortAnimation() , forcing the animation to finished does NOT cause the scroller to move to the final x and y position.

Parameters
finished The new finished value.

public float getCurrVelocity ()

Returns the absolute value of the current velocity.

Returns
  • The original velocity less the deceleration, norm of the X and Y velocity vector.

public final int getCurrX ()

Added in API level 9

Returns the current X offset in the scroll.

Returns
  • The new X offset as an absolute distance from the origin.

public final int getCurrY ()

Added in API level 9

Returns the current Y offset in the scroll.

Returns
  • The new Y offset as an absolute distance from the origin.

public final int getFinalX ()

Added in API level 9

Returns where the scroll will end. Valid only for "fling" scrolls.

Returns
  • The final X offset as an absolute distance from the origin.

public final int getFinalY ()

Added in API level 9

Returns where the scroll will end. Valid only for "fling" scrolls.

Returns
  • The final Y offset as an absolute distance from the origin.

public final int getStartX ()

Added in API level 9

Returns the start X offset in the scroll.

Returns
  • The start X offset as an absolute distance from the origin.

public final int getStartY ()

Added in API level 9

Returns the start Y offset in the scroll.

Returns
  • The start Y offset as an absolute distance from the origin.

public final boolean isFinished ()

Added in API level 9

Returns whether the scroller has finished scrolling.

Returns
  • True if the scroller has finished scrolling, false otherwise.

public boolean isOverScrolled ()

Added in API level 9

Returns whether the current Scroller is currently returning to a valid position. Valid bounds were provided by the fling(int, int, int, int, int, int, int, int, int, int) method. One should check this value before calling startScroll(int, int, int, int) as the interpolation currently in progress to restore a valid position will then be stopped. The caller has to take into account the fact that the started scroll will start from an overscrolled position.

Returns
  • true when the current position is overscrolled and in the process of interpolating back to a valid value.

public void notifyHorizontalEdgeReached (int startX, int finalX, int overX)

Added in API level 9

Notify the scroller that we've reached a horizontal boundary. Normally the information to handle this will already be known when the animation is started, such as in a call to one of the fling functions. However there are cases where this cannot be known in advance. This function will transition the current motion and animate from startX to finalX as appropriate.

Parameters
startX Starting/current X position
finalX Desired final X position
overX Magnitude of overscroll allowed. This should be the maximum desired distance from finalX. Absolute value - must be positive.

public void notifyVerticalEdgeReached (int startY, int finalY, int overY)

Added in API level 9

Notify the scroller that we've reached a vertical boundary. Normally the information to handle this will already be known when the animation is started, such as in a call to one of the fling functions. However there are cases where this cannot be known in advance. This function will animate a parabolic motion from startY to finalY.

Parameters
startY Starting/current Y position
finalY Desired final Y position
overY Magnitude of overscroll allowed. This should be the maximum desired distance from finalY. Absolute value - must be positive.

public final void setFriction (float friction)

The amount of friction applied to flings. The default value is getScrollFriction() .

Parameters
friction A scalar dimension-less value representing the coefficient of friction.

public boolean springBack (int startX, int startY, int minX, int maxX, int minY, int maxY)

Added in API level 9

Call this when you want to 'spring back' into a valid coordinate range.

Parameters
startX Starting X coordinate
startY Starting Y coordinate
minX Minimum valid X value
maxX Maximum valid X value
minY Minimum valid Y value
maxY Minimum valid Y value
Returns
  • true if a springback was initiated, false if startX and startY were already within the valid range.

public void startScroll (int startX, int startY, int dx, int dy)

Added in API level 9

Start scrolling by providing a starting point and the distance to travel. The scroll will use the default value of 250 milliseconds for the duration.

Parameters
startX Starting horizontal scroll offset in pixels. Positive numbers will scroll the content to the left.
startY Starting vertical scroll offset in pixels. Positive numbers will scroll the content up.
dx Horizontal distance to travel. Positive numbers will scroll the content to the left.
dy Vertical distance to travel. Positive numbers will scroll the content up.

public void startScroll (int startX, int startY, int dx, int dy, int duration)

Added in API level 9

Start scrolling by providing a starting point and the distance to travel.

Parameters
startX Starting horizontal scroll offset in pixels. Positive numbers will scroll the content to the left.
startY Starting vertical scroll offset in pixels. Positive numbers will scroll the content up.
dx Horizontal distance to travel. Positive numbers will scroll the content to the left.
dy Vertical distance to travel. Positive numbers will scroll the content up.
duration Duration of the scroll in milliseconds.