AutoScrollHelper

Added in 1.1.0

public abstract class AutoScrollHelper implements View.OnTouchListener

Known direct subclasses
ListViewAutoScrollHelper

An implementation of AutoScrollHelper that knows how to scroll through a ListView.


AutoScrollHelper is a utility class for adding automatic edge-triggered scrolling to Views.

Note: Implementing classes are responsible for overriding the scrollTargetBy, canTargetScrollHorizontally, and canTargetScrollVertically methods. See ListViewAutoScrollHelper for a android.widget.ListView -specific implementation.

Activation

Automatic scrolling starts when the user touches within an activation area. By default, activation areas are defined as the top, left, right, and bottom 20% of the host view's total area. Touching within the top activation area scrolls up, left scrolls to the left, and so on.

As the user touches closer to the extreme edge of the activation area, scrolling accelerates up to a maximum velocity. When using the default edge type, EDGE_TYPE_INSIDE_EXTEND, moving outside of the view bounds will scroll at the maximum velocity.

The following activation properties may be configured:

Scrolling

When automatic scrolling is active, the helper will repeatedly call scrollTargetBy to apply new scrolling offsets.

The following scrolling properties may be configured:

  • Acceleration ramp-up duration, see setRampUpDuration. Default value is 500 milliseconds.
  • Acceleration ramp-down duration, see setRampDownDuration. Default value is 500 milliseconds.
  • Target velocity relative to view size, see setRelativeVelocity. Default value is 100% per second for both vertical and horizontal.
  • Minimum velocity used to constrain relative velocity, see setMinimumVelocity. When set, scrolling will accelerate to the larger of either this value or the relative target value. Default value is approximately 5 centimeters or 315 dips per second.
  • Maximum velocity used to constrain relative velocity, see setMaximumVelocity. Default value is approximately 25 centimeters or 1575 dips per second.

Summary

Constants

static final int

Edge type that specifies an activation area starting at the view bounds and extending inward.

static final int

Edge type that specifies an activation area starting at the view bounds and extending inward.

static final int

Edge type that specifies an activation area starting at the view bounds and extending outward.

static final float
NO_MAX = 3.4028235E38f

Constant passed to setMaximumEdges, setMaximumVelocity, or setMinimumVelocity.

static final float
NO_MIN = 0.0f

Constant passed to setMaximumEdges, or setMaximumVelocity, or setMinimumVelocity.

static final float

Constant passed to setRelativeEdges or setRelativeVelocity.

Public constructors

Creates a new helper for scrolling the specified target view.

Public methods

abstract boolean

Override this method to return whether the target view can be scrolled horizontally in a certain direction.

abstract boolean

Override this method to return whether the target view can be scrolled vertically in a certain direction.

boolean
boolean

Indicates whether the scroll helper handles touch events exclusively during scrolling.

boolean
onTouch(View v, MotionEvent event)

Handles touch events by activating automatic scrolling, adjusting scroll velocity, or stopping.

abstract void
scrollTargetBy(int deltaX, int deltaY)

Override this method to scroll the target view by the specified number of pixels.

@NonNull AutoScrollHelper
setActivationDelay(int delayMillis)

Sets the delay after entering an activation edge before activation of auto-scrolling.

@NonNull AutoScrollHelper
setEdgeType(int type)

Sets the activation edge type, one of:

AutoScrollHelper
setEnabled(boolean enabled)

Sets whether the scroll helper is enabled and should respond to touch events.

AutoScrollHelper
setExclusive(boolean exclusive)

Enables or disables exclusive handling of touch events during scrolling.

@NonNull AutoScrollHelper
setMaximumEdges(float horizontalMax, float verticalMax)

Sets the absolute maximum edge size.

@NonNull AutoScrollHelper
setMaximumVelocity(float horizontalMax, float verticalMax)

Sets the absolute maximum scrolling velocity.

@NonNull AutoScrollHelper
setMinimumVelocity(float horizontalMin, float verticalMin)

Sets the absolute minimum scrolling velocity.

@NonNull AutoScrollHelper
setRampDownDuration(int durationMillis)

Sets the amount of time after de-activation of auto-scrolling that is takes to slow to a stop.

@NonNull AutoScrollHelper
setRampUpDuration(int durationMillis)

Sets the amount of time after activation of auto-scrolling that is takes to reach target velocity for the current touch position.

@NonNull AutoScrollHelper
setRelativeEdges(float horizontal, float vertical)

Sets the activation edge size relative to the host view's dimensions.

@NonNull AutoScrollHelper
setRelativeVelocity(float horizontal, float vertical)

Sets the target scrolling velocity relative to the host view's dimensions.

Constants

EDGE_TYPE_INSIDE

Added in 1.1.0
public static final int EDGE_TYPE_INSIDE = 0

Edge type that specifies an activation area starting at the view bounds and extending inward. Moving outside the view bounds will stop scrolling.

See also
setEdgeType

EDGE_TYPE_INSIDE_EXTEND

Added in 1.1.0
public static final int EDGE_TYPE_INSIDE_EXTEND = 1

Edge type that specifies an activation area starting at the view bounds and extending inward. After activation begins, moving outside the view bounds will continue scrolling.

See also
setEdgeType

EDGE_TYPE_OUTSIDE

Added in 1.1.0
public static final int EDGE_TYPE_OUTSIDE = 2

Edge type that specifies an activation area starting at the view bounds and extending outward. Moving inside the view bounds will stop scrolling.

See also
setEdgeType

NO_MAX

Added in 1.1.0
public static final float NO_MAX = 3.4028235E38f

Constant passed to setMaximumEdges, setMaximumVelocity, or setMinimumVelocity. Using this value ensures that the computed relative value is always used without constraining to a particular minimum or maximum value.

NO_MIN

Added in 1.1.0
public static final float NO_MIN = 0.0f

Constant passed to setMaximumEdges, or setMaximumVelocity, or setMinimumVelocity. Using this value ensures that the computed relative value is always used without constraining to a particular minimum or maximum value.

RELATIVE_UNSPECIFIED

Added in 1.1.0
public static final float RELATIVE_UNSPECIFIED = 0.0f

Constant passed to setRelativeEdges or setRelativeVelocity. Using this value ensures that the computed relative value is ignored and the absolute maximum value is always used.

Public constructors

AutoScrollHelper

Added in 1.1.0
public AutoScrollHelper(@NonNull View target)

Creates a new helper for scrolling the specified target view.

The resulting helper may be configured by chaining setter calls and should be set as a touch listener on the target view.

By default, the helper is disabled and will not respond to touch events until it is enabled using setEnabled.

Parameters
@NonNull View target

The view to automatically scroll.

Public methods

canTargetScrollHorizontally

Added in 1.1.0
public abstract boolean canTargetScrollHorizontally(int direction)

Override this method to return whether the target view can be scrolled horizontally in a certain direction.

Parameters
int direction

Negative to check scrolling left, positive to check scrolling right.

Returns
boolean

true if the target view is able to horizontally scroll in the specified direction.

canTargetScrollVertically

Added in 1.1.0
public abstract boolean canTargetScrollVertically(int direction)

Override this method to return whether the target view can be scrolled vertically in a certain direction.

Parameters
int direction

Negative to check scrolling up, positive to check scrolling down.

Returns
boolean

true if the target view is able to vertically scroll in the specified direction.

isEnabled

Added in 1.1.0
public boolean isEnabled()
Returns
boolean

True if this helper is enabled and responding to touch events.

isExclusive

Added in 1.1.0
public boolean isExclusive()

Indicates whether the scroll helper handles touch events exclusively during scrolling.

Returns
boolean

True if exclusive handling of touch events during scrolling is enabled, false otherwise.

See also
setExclusive

onTouch

Added in 1.1.0
public boolean onTouch(View v, MotionEvent event)

Handles touch events by activating automatic scrolling, adjusting scroll velocity, or stopping.

If isExclusive is false, always returns false so that the host view may handle touch events. Otherwise, returns true when automatic scrolling is active and false otherwise.

scrollTargetBy

Added in 1.1.0
public abstract void scrollTargetBy(int deltaX, int deltaY)

Override this method to scroll the target view by the specified number of pixels.

Parameters
int deltaX

The number of pixels to scroll by horizontally.

int deltaY

The number of pixels to scroll by vertically.

setActivationDelay

Added in 1.1.0
public @NonNull AutoScrollHelper setActivationDelay(int delayMillis)

Sets the delay after entering an activation edge before activation of auto-scrolling. By default, the activation delay is set to getTapTimeout.

Specifying a delay of zero will start auto-scrolling immediately after the touch position enters an activation edge.

Parameters
int delayMillis

The activation delay in milliseconds.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setEdgeType

Added in 1.1.0
public @NonNull AutoScrollHelper setEdgeType(int type)

Sets the activation edge type, one of:

  • EDGE_TYPE_INSIDE for edges that respond to touches inside the bounds of the host view. If touch moves outside the bounds, scrolling will stop.
  • EDGE_TYPE_INSIDE_EXTEND for inside edges that continued to scroll when touch moves outside the bounds of the host view.
  • EDGE_TYPE_OUTSIDE for edges that only respond to touches that move outside the bounds of the host view.
Parameters
int type

The type of edge to use.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setEnabled

Added in 1.1.0
public AutoScrollHelper setEnabled(boolean enabled)

Sets whether the scroll helper is enabled and should respond to touch events.

Parameters
boolean enabled

Whether the scroll helper is enabled.

Returns
AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setExclusive

Added in 1.1.0
public AutoScrollHelper setExclusive(boolean exclusive)

Enables or disables exclusive handling of touch events during scrolling. By default, exclusive handling is disabled and the target view receives all touch events.

When enabled, onTouch will return true if the helper is currently scrolling and false otherwise.

Parameters
boolean exclusive

True to exclusively handle touch events during scrolling, false to allow the target view to receive all touch events.

Returns
AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setMaximumEdges

Added in 1.1.0
public @NonNull AutoScrollHelper setMaximumEdges(float horizontalMax, float verticalMax)

Sets the absolute maximum edge size.

If relative edge size is not specified, activation edges will always be the maximum edge size. If both relative and maximum edges are specified, the maximum edge will be used to constrain the calculated relative edge size.

Parameters
float horizontalMax

The maximum horizontal edge size in pixels, or NO_MAX to use the unconstrained calculated relative value.

float verticalMax

The maximum vertical edge size in pixels, or NO_MAX to use the unconstrained calculated relative value.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setMaximumVelocity

Added in 1.1.0
public @NonNull AutoScrollHelper setMaximumVelocity(float horizontalMax, float verticalMax)

Sets the absolute maximum scrolling velocity.

If relative velocity is not specified, scrolling will always reach the same maximum velocity. If both relative and maximum velocities are specified, the maximum velocity will be used to clamp the calculated relative velocity.

Parameters
float horizontalMax

The maximum horizontal scrolling velocity, or NO_MAX to leave the relative value unconstrained.

float verticalMax

The maximum vertical scrolling velocity, or NO_MAX to leave the relative value unconstrained.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setMinimumVelocity

Added in 1.1.0
public @NonNull AutoScrollHelper setMinimumVelocity(float horizontalMin, float verticalMin)

Sets the absolute minimum scrolling velocity.

If both relative and minimum velocities are specified, the minimum velocity will be used to clamp the calculated relative velocity.

Parameters
float horizontalMin

The minimum horizontal scrolling velocity, or NO_MIN to leave the relative value unconstrained.

float verticalMin

The minimum vertical scrolling velocity, or NO_MIN to leave the relative value unconstrained.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setRampDownDuration

Added in 1.1.0
public @NonNull AutoScrollHelper setRampDownDuration(int durationMillis)

Sets the amount of time after de-activation of auto-scrolling that is takes to slow to a stop.

Specifying a duration greater than zero prevents sudden jumps in velocity.

Parameters
int durationMillis

The ramp-down duration in milliseconds.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setRampUpDuration

Added in 1.1.0
public @NonNull AutoScrollHelper setRampUpDuration(int durationMillis)

Sets the amount of time after activation of auto-scrolling that is takes to reach target velocity for the current touch position.

Specifying a duration greater than zero prevents sudden jumps in velocity.

Parameters
int durationMillis

The ramp-up duration in milliseconds.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setRelativeEdges

Added in 1.1.0
public @NonNull AutoScrollHelper setRelativeEdges(float horizontal, float vertical)

Sets the activation edge size relative to the host view's dimensions.

If both relative and maximum edges are specified, the maximum edge will be used to constrain the calculated relative edge size.

Parameters
float horizontal

The horizontal edge size as a fraction of the host view width, or RELATIVE_UNSPECIFIED to always use the maximum value.

float vertical

The vertical edge size as a fraction of the host view height, or RELATIVE_UNSPECIFIED to always use the maximum value.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.

setRelativeVelocity

Added in 1.1.0
public @NonNull AutoScrollHelper setRelativeVelocity(float horizontal, float vertical)

Sets the target scrolling velocity relative to the host view's dimensions.

If both relative and maximum velocities are specified, the maximum velocity will be used to clamp the calculated relative velocity.

Parameters
float horizontal

The target horizontal velocity as a fraction of the host view width per second, or RELATIVE_UNSPECIFIED to ignore.

float vertical

The target vertical velocity as a fraction of the host view height per second, or RELATIVE_UNSPECIFIED to ignore.

Returns
@NonNull AutoScrollHelper

The scroll helper, which may used to chain setter calls.