public abstract class AutoScrollHelper extends Object implements View.OnTouchListener
Note: Implementing classes are responsible for overriding the
scrollTargetBy(int, int)
, canTargetScrollHorizontally(int)
, and
canTargetScrollVertically(int)
methods. See
ListViewAutoScrollHelper
for a ListView
-specific implementation.
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:
setActivationDelay(int)
. Default value is
ViewConfiguration.getTapTimeout()
to avoid conflicting with taps.
setEdgeType(int)
. Default value is
EDGE_TYPE_INSIDE_EXTEND
.
setRelativeEdges(float, float)
. Default value is 20% for both vertical and
horizontal edges.
setMaximumEdges(float, float)
. Default value is NO_MAX
.
scrollTargetBy(int, int)
to apply new scrolling offsets.
The following scrolling properties may be configured:
setRampUpDuration(int)
. Default
value is 500 milliseconds.
setRampDownDuration(int)
.
Default value is 500 milliseconds.
setRelativeVelocity(float, float)
.
Default value is 100% per second for both vertical and horizontal.
setMinimumVelocity(float, float)
. 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.
setMaximumVelocity(float, float)
. Default value is approximately 25 centimeters or
1575 dips per second.
Modifier and Type | Field and Description |
---|---|
static int |
EDGE_TYPE_INSIDE
Edge type that specifies an activation area starting at the view bounds
and extending inward.
|
static int |
EDGE_TYPE_INSIDE_EXTEND
Edge type that specifies an activation area starting at the view bounds
and extending inward.
|
static int |
EDGE_TYPE_OUTSIDE
Edge type that specifies an activation area starting at the view bounds
and extending outward.
|
static float |
NO_MAX
Constant passed to
setMaximumEdges(float, float) , setMaximumVelocity(float, float) ,
or setMinimumVelocity(float, float) . |
static float |
NO_MIN
Constant passed to
setMaximumEdges(float, float) , or
setMaximumVelocity(float, float) , or setMinimumVelocity(float, float) . |
static float |
RELATIVE_UNSPECIFIED
Constant passed to
setRelativeEdges(float, float) or
setRelativeVelocity(float, float) . |
Constructor and Description |
---|
AutoScrollHelper(View target)
Creates a new helper for scrolling the specified target view.
|
Modifier and Type | Method and Description |
---|---|
abstract boolean |
canTargetScrollHorizontally(int direction)
Override this method to return whether the target view can be scrolled
horizontally in a certain direction.
|
abstract boolean |
canTargetScrollVertically(int direction)
Override this method to return whether the target view can be scrolled
vertically in a certain direction.
|
boolean |
isEnabled() |
boolean |
isExclusive()
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.
|
AutoScrollHelper |
setActivationDelay(int delayMillis)
Sets the delay after entering an activation edge before activation of
auto-scrolling.
|
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. |
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.
|
AutoScrollHelper |
setMaximumEdges(float horizontalMax,
float verticalMax)
Sets the absolute maximum edge size.
|
AutoScrollHelper |
setMaximumVelocity(float horizontalMax,
float verticalMax)
Sets the absolute maximum scrolling velocity.
|
AutoScrollHelper |
setMinimumVelocity(float horizontalMin,
float verticalMin)
Sets the absolute minimum scrolling velocity.
|
AutoScrollHelper |
setRampDownDuration(int durationMillis)
Sets the amount of time after de-activation of auto-scrolling that is
takes to slow to a stop.
|
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.
|
AutoScrollHelper |
setRelativeEdges(float horizontal,
float vertical)
Sets the activation edge size relative to the host view's dimensions.
|
AutoScrollHelper |
setRelativeVelocity(float horizontal,
float vertical)
Sets the target scrolling velocity relative to the host view's
dimensions.
|
public static final float RELATIVE_UNSPECIFIED
setRelativeEdges(float, float)
or
setRelativeVelocity(float, float)
. Using this value ensures that the computed
relative value is ignored and the absolute maximum value is always used.public static final float NO_MAX
setMaximumEdges(float, float)
, setMaximumVelocity(float, float)
,
or setMinimumVelocity(float, float)
. Using this value ensures that the
computed relative value is always used without constraining to a
particular minimum or maximum value.public static final float NO_MIN
setMaximumEdges(float, float)
, or
setMaximumVelocity(float, float)
, or setMinimumVelocity(float, float)
. Using this
value ensures that the computed relative value is always used without
constraining to a particular minimum or maximum value.public static final int EDGE_TYPE_INSIDE
setEdgeType(int)
,
Constant Field Valuespublic static final int EDGE_TYPE_INSIDE_EXTEND
setEdgeType(int)
,
Constant Field Valuespublic static final int EDGE_TYPE_OUTSIDE
setEdgeType(int)
,
Constant Field Valuespublic AutoScrollHelper(View target)
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(boolean)
.
target
- The view to automatically scroll.public AutoScrollHelper setEnabled(boolean enabled)
enabled
- Whether the scroll helper is enabled.public boolean isEnabled()
public AutoScrollHelper setExclusive(boolean exclusive)
When enabled, onTouch(android.view.View, android.view.MotionEvent)
will return true if the helper is
currently scrolling and false otherwise.
exclusive
- True to exclusively handle touch events during scrolling,
false to allow the target view to receive all touch events.public boolean isExclusive()
setExclusive(boolean)
public AutoScrollHelper setMaximumVelocity(float horizontalMax, float verticalMax)
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.
public AutoScrollHelper setMinimumVelocity(float horizontalMin, float verticalMin)
If both relative and minimum velocities are specified, the minimum velocity will be used to clamp the calculated relative velocity.
public AutoScrollHelper setRelativeVelocity(float horizontal, float vertical)
If both relative and maximum velocities are specified, the maximum velocity will be used to clamp the calculated relative velocity.
horizontal
- The target horizontal velocity as a fraction of the
host view width per second, or RELATIVE_UNSPECIFIED
to ignore.vertical
- The target vertical velocity as a fraction of the host
view height per second, or RELATIVE_UNSPECIFIED
to
ignore.public AutoScrollHelper setEdgeType(int type)
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.
type
- The type of edge to use.public AutoScrollHelper setRelativeEdges(float horizontal, float vertical)
If both relative and maximum edges are specified, the maximum edge will be used to constrain the calculated relative edge size.
horizontal
- The horizontal edge size as a fraction of the host view
width, or RELATIVE_UNSPECIFIED
to always use the
maximum value.vertical
- The vertical edge size as a fraction of the host view
height, or RELATIVE_UNSPECIFIED
to always use the
maximum value.public AutoScrollHelper setMaximumEdges(float horizontalMax, float verticalMax)
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.
horizontalMax
- The maximum horizontal edge size in pixels, or
NO_MAX
to use the unconstrained calculated relative
value.verticalMax
- The maximum vertical edge size in pixels, or
NO_MAX
to use the unconstrained calculated relative
value.public AutoScrollHelper setActivationDelay(int delayMillis)
ViewConfiguration.getTapTimeout()
.
Specifying a delay of zero will start auto-scrolling immediately after the touch position enters an activation edge.
delayMillis
- The activation delay in milliseconds.public AutoScrollHelper setRampUpDuration(int durationMillis)
Specifying a duration greater than zero prevents sudden jumps in velocity.
durationMillis
- The ramp-up duration in milliseconds.public AutoScrollHelper setRampDownDuration(int durationMillis)
Specifying a duration greater than zero prevents sudden jumps in velocity.
durationMillis
- The ramp-down duration in milliseconds.public boolean onTouch(View v, MotionEvent event)
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.
onTouch
in interface View.OnTouchListener
v
- The view the touch event has been dispatched to.event
- The MotionEvent object containing full information about
the event.public abstract void scrollTargetBy(int deltaX, int deltaY)
deltaX
- The number of pixels to scroll by horizontally.deltaY
- The number of pixels to scroll by vertically.public abstract boolean canTargetScrollHorizontally(int direction)
direction
- Negative to check scrolling left, positive to check
scrolling right.public abstract boolean canTargetScrollVertically(int direction)
direction
- Negative to check scrolling up, positive to check
scrolling down.