Added in API level 1

Scroller


public class Scroller
extends Object

java.lang.Object
   ↳ android.widget.Scroller


This class encapsulates scrolling. You can use scrollers (Scroller or OverScroller) to collect the data you need to produce a scrolling animation—for example, in response to a fling gesture. Scrollers track scroll offsets for you over time, but they don't automatically apply those positions to your view. It's your responsibility to get and apply new coordinates at a rate that will make the scrolling animation look smooth.

Here is a simple example:

 private Scroller mScroller = new Scroller(context);
 ...
 public void zoomIn() {
     // Revert any animation currently in progress
     mScroller.forceFinished(true);
     // Start scrolling by providing a starting point and
     // the distance to travel
     mScroller.startScroll(0, 0, 100, 0);
     // Invalidate to request a redraw
     invalidate();
 }

To track the changing positions of the x/y coordinates, use computeScrollOffset(). The method returns a boolean to indicate whether the scroller is finished. If it isn't, it means that a fling or programmatic pan operation is still in progress. You can use this method to find the current offsets of the x and y coordinates, for example:

if (mScroller.computeScrollOffset()) {
     // Get current x and y positions
     int currX = mScroller.getCurrX();
     int currY = mScroller.getCurrY();
    ...
 }

Summary

Public constructors

Scroller(Context context)

Create a Scroller with the default duration and interpolator.

Scroller(Context context, Interpolator interpolator)

Create a Scroller with the specified interpolator.

Scroller(Context context, Interpolator interpolator, boolean flywheel)

Create a Scroller with the specified interpolator.

Public methods

void abortAnimation()

Stops the animation.

boolean computeScrollOffset()

Call this when you want to know the new location.

void extendDuration(int extend)

Extend the scroll animation.

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

Start scrolling based on a fling gesture.

final void forceFinished(boolean finished)

Force the finished field to a particular value.

float getCurrVelocity()

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

Returns how long the scroll event will take, in milliseconds.

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.

void setFinalX(int newX)

Sets the final position (X) for this scroller.

void setFinalY(int newY)

Sets the final position (Y) for this scroller.

final void setFriction(float friction)

The amount of friction applied to flings.

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

Start scrolling by providing a starting point, the distance to travel, and the duration of the scroll.

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

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

int timePassed()

Returns the time elapsed since the beginning of the scrolling.

Inherited methods

Public constructors

Scroller

Added in API level 1
public Scroller (Context context)

Create a Scroller with the default duration and interpolator.

Parameters
context Context

Scroller

Added in API level 1
public Scroller (Context context, 
                Interpolator interpolator)

Create a Scroller with the specified interpolator. If the interpolator is null, the default (viscous) interpolator will be used. "Flywheel" behavior will be in effect for apps targeting Honeycomb or newer.

Parameters
context Context

interpolator Interpolator

Scroller

Added in API level 11
public Scroller (Context context, 
                Interpolator interpolator, 
                boolean flywheel)

Create a Scroller with the specified interpolator. If the interpolator is null, the default (viscous) interpolator will be used. Specify whether or not to support progressive "flywheel" behavior in flinging.

Parameters
context Context

interpolator Interpolator

flywheel boolean

Public methods

abortAnimation

Added in API level 1
public void abortAnimation ()

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

computeScrollOffset

Added in API level 1
public boolean computeScrollOffset ()

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

Returns
boolean

extendDuration

Added in API level 1
public void extendDuration (int extend)

Extend the scroll animation. This allows a running animation to scroll further and longer, when used with setFinalX(int) or setFinalY(int).

Parameters
extend int: Additional time to scroll in milliseconds.

fling

Added in API level 1
public void fling (int startX, 
                int startY, 
                int velocityX, 
                int velocityY, 
                int minX, 
                int maxX, 
                int minY, 
                int maxY)

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

Parameters
startX int: Starting point of the scroll (X)

startY int: Starting point of the scroll (Y)

velocityX int: Initial velocity of the fling (X) measured in pixels per second.

velocityY int: Initial velocity of the fling (Y) measured in pixels per second

minX int: Minimum X value. The scroller will not scroll past this point.

maxX int: Maximum X value. The scroller will not scroll past this point.

minY int: Minimum Y value. The scroller will not scroll past this point.

maxY int: Maximum Y value. The scroller will not scroll past this point.

forceFinished

Added in API level 1
public final void forceFinished (boolean finished)

Force the finished field to a particular value.

Parameters
finished boolean: The new finished value.

getCurrVelocity

Added in API level 14
public float getCurrVelocity ()

Returns the current velocity.

Returns
float The original velocity less the deceleration. Result may be negative.

getCurrX

Added in API level 1
public final int getCurrX ()

Returns the current X offset in the scroll.

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

getCurrY

Added in API level 1
public final int getCurrY ()

Returns the current Y offset in the scroll.

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

getDuration

Added in API level 1
public final int getDuration ()

Returns how long the scroll event will take, in milliseconds.

Returns
int The duration of the scroll in milliseconds.

getFinalX

Added in API level 1
public final int getFinalX ()

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

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

getFinalY

Added in API level 1
public final int getFinalY ()

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

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

getStartX

Added in API level 3
public final int getStartX ()

Returns the start X offset in the scroll.

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

getStartY

Added in API level 3
public final int getStartY ()

Returns the start Y offset in the scroll.

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

isFinished

Added in API level 1
public final boolean isFinished ()

Returns whether the scroller has finished scrolling.

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

setFinalX

Added in API level 1
public void setFinalX (int newX)

Sets the final position (X) for this scroller.

Parameters
newX int: The new X offset as an absolute distance from the origin.

setFinalY

Added in API level 1
public void setFinalY (int newY)

Sets the final position (Y) for this scroller.

Parameters
newY int: The new Y offset as an absolute distance from the origin.

setFriction

Added in API level 11
public final void setFriction (float friction)

The amount of friction applied to flings. The default value is ViewConfiguration#getScrollFriction.

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

startScroll

Added in API level 1
public void startScroll (int startX, 
                int startY, 
                int dx, 
                int dy, 
                int duration)

Start scrolling by providing a starting point, the distance to travel, and the duration of the scroll.

Parameters
startX int: Starting horizontal scroll offset in pixels. Positive numbers will scroll the content to the left.

startY int: Starting vertical scroll offset in pixels. Positive numbers will scroll the content up.

dx int: Horizontal distance to travel. Positive numbers will scroll the content to the left.

dy int: Vertical distance to travel. Positive numbers will scroll the content up.

duration int: Duration of the scroll in milliseconds.

startScroll

Added in API level 1
public void startScroll (int startX, 
                int startY, 
                int dx, 
                int dy)

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 int: Starting horizontal scroll offset in pixels. Positive numbers will scroll the content to the left.

startY int: Starting vertical scroll offset in pixels. Positive numbers will scroll the content up.

dx int: Horizontal distance to travel. Positive numbers will scroll the content to the left.

dy int: Vertical distance to travel. Positive numbers will scroll the content up.

timePassed

Added in API level 1
public int timePassed ()

Returns the time elapsed since the beginning of the scrolling.

Returns
int The elapsed time in milliseconds.