ViewDragHelper

Artifact: androidx.customview:customview

Added in 1.0.0

Kotlin |Java

class ViewDragHelper

ViewDragHelper is a utility class for writing custom ViewGroups. It offers a number of useful operations and state tracking for allowing a user to drag and reposition views within their parent ViewGroup.

Summary

Nested types
`abstract class ViewDragHelper.Callback` A Callback is used as a communication channel with the ViewDragHelper back to the parent view using it.

Constants
`const Int`	`DIRECTION_ALL = 3` Indicates that a check should occur along all axes
`const Int`	`DIRECTION_HORIZONTAL = 1` Indicates that a check should occur along the horizontal axis
`const Int`	`DIRECTION_VERTICAL = 2` Indicates that a check should occur along the vertical axis
`const Int`	`EDGE_ALL = 15` Edge flag set indicating all edges should be affected.
`const Int`	`EDGE_BOTTOM = 8` Edge flag indicating that the bottom edge should be affected.
`const Int`	`EDGE_LEFT = 1` Edge flag indicating that the left edge should be affected.
`const Int`	`EDGE_RIGHT = 2` Edge flag indicating that the right edge should be affected.
`const Int`	`EDGE_TOP = 4` Edge flag indicating that the top edge should be affected.
`const Int`	`INVALID_POINTER = -1` A null/invalid pointer ID.
`const Int`	`STATE_DRAGGING = 1` A view is currently being dragged.
`const Int`	`STATE_IDLE = 0` A view is not currently being dragged or animating as a result of a fling/snap.
`const Int`	`STATE_SETTLING = 2` A view is currently settling into place as a result of a fling or predefined non-interactive motion.

Public functions
`Unit`	`abort()` `cancel`, but also abort all motion in progress and snap to the end of any animation.
`Unit`	`cancel()` The result of a call to this method is equivalent to `processTouchEvent` receiving an ACTION_CANCEL event.
`Unit`	`captureChildView(childView: View, activePointerId: Int)` Capture a specific child view for dragging within the parent.
`Boolean`	`checkTouchSlop(directions: Int)` Check if any pointer tracked in the current gesture has crossed the required slop threshold.
`Boolean`	`checkTouchSlop(directions: Int, pointerId: Int)` Check if the specified pointer tracked in the current gesture has crossed the required slop threshold.
`Boolean`	`continueSettling(deferCallbacks: Boolean)` Move the captured settling view by the appropriate amount for the current time.
`java-static ViewDragHelper`	`create(forParent: ViewGroup, cb: ViewDragHelper.Callback)` Factory method to create a new ViewDragHelper.
`java-static ViewDragHelper`	`create( forParent: ViewGroup, sensitivity: Float, cb: ViewDragHelper.Callback )` Factory method to create a new ViewDragHelper.
`View?`	`findTopChildUnder(x: Int, y: Int)` Find the topmost child under the given point within the parent view's coordinate system.
`Unit`	`flingCapturedView(minLeft: Int, minTop: Int, maxLeft: Int, maxTop: Int)` Settle the captured view based on standard free-moving fling behavior.
`Int`	`getActivePointerId()`
`View?`	`getCapturedView()`
`@Px Int`	`getDefaultEdgeSize()` Return the default size used for edge tracking.
`@Px Int`	`getEdgeSize()` Return the size of an edge.
`Float`	`getMinVelocity()` Return the currently configured minimum velocity.
`@Px Int`	`getTouchSlop()`
`Int`	`getViewDragState()` Retrieve the current drag state of this helper.
`Boolean`	`isCapturedViewUnder(x: Int, y: Int)` Determine if the currently captured view is under the given point in the parent view's coordinate system.
`Boolean`	`isEdgeTouched(edges: Int)` Check if any of the edges specified were initially touched in the currently active gesture.
`Boolean`	`isEdgeTouched(edges: Int, pointerId: Int)` Check if any of the edges specified were initially touched by the pointer with the specified ID.
`Boolean`	`isPointerDown(pointerId: Int)` Check if the given pointer ID represents a pointer that is currently down (to the best of the ViewDragHelper's knowledge).
`Boolean`	`isViewUnder(view: View?, x: Int, y: Int)` Determine if the supplied view is under the given point in the parent view's coordinate system.
`Unit`	`processTouchEvent(ev: MotionEvent)` Process a touch event received by the parent view.
`Unit`	`setEdgeSize(size: @Px @IntRange(from = 0) Int)` Set the range in pixels along the edges of this view that will actively detect edge touches or drags if edge tracking is enabled.
`Unit`	`setEdgeTrackingEnabled(edgeFlags: Int)` Enable edge tracking for the selected edges of the parent view.
`Unit`	`setMinVelocity(minVel: Float)` Set the minimum velocity that will be detected as having a magnitude greater than zero in pixels per second.
`Boolean`	`settleCapturedViewAt(finalLeft: Int, finalTop: Int)` Settle the captured view at the given (left, top) position.
`Boolean`	`shouldInterceptTouchEvent(ev: MotionEvent)` Check if this event as provided to the parent view's onInterceptTouchEvent should cause the parent to intercept the touch event stream.
`Boolean`	`smoothSlideViewTo(child: View, finalLeft: Int, finalTop: Int)` Animate the view `child` to the given (left, top) position.

Protected functions
`Boolean`	`canScroll(v: View, checkV: Boolean, dx: Int, dy: Int, x: Int, y: Int)` Tests scrollability within child views of v given a delta of dx.

Constants

DIRECTION_ALL

Added in 1.0.0

const val DIRECTION_ALL = 3: Int

Indicates that a check should occur along all axes

DIRECTION_HORIZONTAL

Added in 1.0.0

const val DIRECTION_HORIZONTAL = 1: Int

Indicates that a check should occur along the horizontal axis

DIRECTION_VERTICAL

Added in 1.0.0

const val DIRECTION_VERTICAL = 2: Int

Indicates that a check should occur along the vertical axis

EDGE_ALL

Added in 1.0.0

const val EDGE_ALL = 15: Int

Edge flag set indicating all edges should be affected.

EDGE_BOTTOM

Added in 1.0.0

const val EDGE_BOTTOM = 8: Int

Edge flag indicating that the bottom edge should be affected.

EDGE_LEFT

Added in 1.0.0

const val EDGE_LEFT = 1: Int

Edge flag indicating that the left edge should be affected.

EDGE_RIGHT

Added in 1.0.0

const val EDGE_RIGHT = 2: Int

Edge flag indicating that the right edge should be affected.

EDGE_TOP

Added in 1.0.0

const val EDGE_TOP = 4: Int

Edge flag indicating that the top edge should be affected.

INVALID_POINTER

Added in 1.0.0

const val INVALID_POINTER = -1: Int

A null/invalid pointer ID.

STATE_DRAGGING

Added in 1.0.0

const val STATE_DRAGGING = 1: Int

A view is currently being dragged. The position is currently changing as a result of user input or simulated user input.

STATE_IDLE

Added in 1.0.0

const val STATE_IDLE = 0: Int

A view is not currently being dragged or animating as a result of a fling/snap.

STATE_SETTLING

Added in 1.0.0

const val STATE_SETTLING = 2: Int

A view is currently settling into place as a result of a fling or predefined non-interactive motion.

Public functions

abort

Added in 1.0.0

fun abort(): Unit

cancel, but also abort all motion in progress and snap to the end of any animation.

cancel

Added in 1.0.0

fun cancel(): Unit

The result of a call to this method is equivalent to processTouchEvent receiving an ACTION_CANCEL event.

captureChildView

Added in 1.0.0

fun captureChildView(childView: View, activePointerId: Int): Unit

Capture a specific child view for dragging within the parent. The callback will be notified but tryCaptureView will not be asked permission to capture this view.

Parameters
`childView: View`	Child view to capture
`activePointerId: Int`	ID of the pointer that is dragging the captured child view

checkTouchSlop

Added in 1.0.0

fun checkTouchSlop(directions: Int): Boolean

Check if any pointer tracked in the current gesture has crossed the required slop threshold.

This depends on internal state populated by shouldInterceptTouchEvent or processTouchEvent. You should only rely on the results of this method after all currently available touch data has been provided to one of these two methods.

Parameters
`directions: Int`	Combination of direction flags, see `DIRECTION_HORIZONTAL`, `DIRECTION_VERTICAL`, `DIRECTION_ALL`

Returns
`Boolean`	true if the slop threshold has been crossed, false otherwise

checkTouchSlop

Added in 1.0.0

fun checkTouchSlop(directions: Int, pointerId: Int): Boolean

Check if the specified pointer tracked in the current gesture has crossed the required slop threshold.

Parameters
`directions: Int`	Combination of direction flags, see `DIRECTION_HORIZONTAL`, `DIRECTION_VERTICAL`, `DIRECTION_ALL`
`pointerId: Int`	ID of the pointer to slop check as specified by MotionEvent

Returns
`Boolean`	true if the slop threshold has been crossed, false otherwise

continueSettling

Added in 1.0.0

fun continueSettling(deferCallbacks: Boolean): Boolean

Move the captured settling view by the appropriate amount for the current time. If continueSettling returns true, the caller should call it again on the next frame to continue.

Parameters
`deferCallbacks: Boolean`	true if state callbacks should be deferred via posted message. Set this to true if you are calling this method from `computeScroll` or similar methods invoked as part of layout or drawing.

Returns
`Boolean`	true if settle is still in progress

Added in 1.0.0

java-static fun create(forParent: ViewGroup, cb: ViewDragHelper.Callback): ViewDragHelper

Factory method to create a new ViewDragHelper.

Parameters
`forParent: ViewGroup`	Parent view to monitor
`cb: ViewDragHelper.Callback`	Callback to provide information and receive events

Returns
`ViewDragHelper`	a new ViewDragHelper instance

Added in 1.0.0

java-static fun create(
    forParent: ViewGroup,
    sensitivity: Float,
    cb: ViewDragHelper.Callback
): ViewDragHelper

Factory method to create a new ViewDragHelper.

Parameters
`forParent: ViewGroup`	Parent view to monitor
`sensitivity: Float`	Multiplier for how sensitive the helper should be about detecting the start of a drag. Larger values are more sensitive. 1.0f is normal.
`cb: ViewDragHelper.Callback`	Callback to provide information and receive events

Returns
`ViewDragHelper`	a new ViewDragHelper instance

findTopChildUnder

Added in 1.0.0

fun findTopChildUnder(x: Int, y: Int): View?

Find the topmost child under the given point within the parent view's coordinate system. The child order is determined using getOrderedChildIndex.

Parameters
`x: Int`	X position to test in the parent's coordinate system
`y: Int`	Y position to test in the parent's coordinate system

Returns
`View?`	The topmost child view under (x, y) or null if none found.

flingCapturedView

Added in 1.0.0

fun flingCapturedView(minLeft: Int, minTop: Int, maxLeft: Int, maxTop: Int): Unit

Settle the captured view based on standard free-moving fling behavior. The caller should invoke continueSettling on each subsequent frame to continue the motion until it returns false.

Parameters
`minLeft: Int`	Minimum X position for the view's left edge
`minTop: Int`	Minimum Y position for the view's top edge
`maxLeft: Int`	Maximum X position for the view's left edge
`maxTop: Int`	Maximum Y position for the view's top edge

getActivePointerId

Added in 1.0.0

fun getActivePointerId(): Int

Returns
`Int`	The ID of the pointer currently dragging the captured view, or `INVALID_POINTER`.

getCapturedView

Added in 1.0.0

fun getCapturedView(): View?

Returns
`View?`	The currently captured view, or null if no view has been captured.

getDefaultEdgeSize

Added in 1.1.0

fun getDefaultEdgeSize(): @Px Int

Return the default size used for edge tracking.

Returns
`@Px Int`	The default edge size

See also
`setEdgeTrackingEnabled`
`getEdgeSize`

getEdgeSize

Added in 1.0.0

fun getEdgeSize(): @Px Int

Return the size of an edge. This is the range in pixels along the edges of this view that will actively detect edge touches or drags if edge tracking is enabled.

Returns
`@Px Int`	The size of an edge in pixels

See also
`setEdgeTrackingEnabled`

getMinVelocity

Added in 1.0.0

fun getMinVelocity(): Float

Return the currently configured minimum velocity. Any flings with a magnitude less than this value in pixels per second. Callback methods accepting a velocity will receive zero as a velocity value if the real detected velocity was below this threshold.

Returns
`Float`	the minimum velocity that will be detected

getTouchSlop

Added in 1.0.0

fun getTouchSlop(): @Px Int

Returns
`@Px Int`	The minimum distance in pixels that the user must travel to initiate a drag

getViewDragState

Added in 1.0.0

fun getViewDragState(): Int

Retrieve the current drag state of this helper. This will return one of STATE_IDLE, STATE_DRAGGING or STATE_SETTLING.

Returns
`Int`	The current drag state

isCapturedViewUnder

Added in 1.0.0

fun isCapturedViewUnder(x: Int, y: Int): Boolean

Determine if the currently captured view is under the given point in the parent view's coordinate system. If there is no captured view this method will return false.

Parameters
`x: Int`	X position to test in the parent's coordinate system
`y: Int`	Y position to test in the parent's coordinate system

Returns
`Boolean`	true if the captured view is under the given point, false otherwise

isEdgeTouched

Added in 1.0.0

fun isEdgeTouched(edges: Int): Boolean

Check if any of the edges specified were initially touched in the currently active gesture. If there is no currently active gesture this method will return false.

Parameters
`edges: Int`	Edges to check for an initial edge touch. See `EDGE_LEFT`, `EDGE_TOP`, `EDGE_RIGHT`, `EDGE_BOTTOM` and `EDGE_ALL`

Returns
`Boolean`	true if any of the edges specified were initially touched in the current gesture

isEdgeTouched

Added in 1.0.0

fun isEdgeTouched(edges: Int, pointerId: Int): Boolean

Check if any of the edges specified were initially touched by the pointer with the specified ID. If there is no currently active gesture or if there is no pointer with the given ID currently down this method will return false.

Parameters
`edges: Int`	Edges to check for an initial edge touch. See `EDGE_LEFT`, `EDGE_TOP`, `EDGE_RIGHT`, `EDGE_BOTTOM` and `EDGE_ALL`

Returns
`Boolean`	true if any of the edges specified were initially touched in the current gesture

isPointerDown

Added in 1.0.0

fun isPointerDown(pointerId: Int): Boolean

Check if the given pointer ID represents a pointer that is currently down (to the best of the ViewDragHelper's knowledge).

The state used to report this information is populated by the methods shouldInterceptTouchEvent or processTouchEvent. If one of these methods has not been called for all relevant MotionEvents to track, the information reported by this method may be stale or incorrect.

Parameters
`pointerId: Int`	pointer ID to check; corresponds to IDs provided by MotionEvent

Returns
`Boolean`	true if the pointer with the given ID is still down

isViewUnder

Added in 1.0.0

fun isViewUnder(view: View?, x: Int, y: Int): Boolean

Determine if the supplied view is under the given point in the parent view's coordinate system.

Parameters
`view: View?`	Child view of the parent to hit test
`x: Int`	X position to test in the parent's coordinate system
`y: Int`	Y position to test in the parent's coordinate system

Returns
`Boolean`	true if the supplied view is under the given point, false otherwise

processTouchEvent

Added in 1.0.0

fun processTouchEvent(ev: MotionEvent): Unit

Process a touch event received by the parent view. This method will dispatch callback events as needed before returning. The parent view's onTouchEvent implementation should call this.

Parameters
`ev: MotionEvent`	The touch event received by the parent view

setEdgeSize

Added in 1.1.0

fun setEdgeSize(size: @Px @IntRange(from = 0) Int): Unit

Set the range in pixels along the edges of this view that will actively detect edge touches or drags if edge tracking is enabled.

Parameters
`size: @Px @IntRange(from = 0) Int`	Edge size in pixels

See also
`setEdgeTrackingEnabled`
`getEdgeSize`

setEdgeTrackingEnabled

Added in 1.0.0

fun setEdgeTrackingEnabled(edgeFlags: Int): Unit

Enable edge tracking for the selected edges of the parent view. The callback's onEdgeTouched and onEdgeDragStarted methods will only be invoked for edges for which edge tracking has been enabled.

Parameters
`edgeFlags: Int`	Combination of edge flags describing the edges to watch

See also
`EDGE_LEFT`
`EDGE_TOP`
`EDGE_RIGHT`
`EDGE_BOTTOM`

setMinVelocity

Added in 1.0.0

fun setMinVelocity(minVel: Float): Unit

Set the minimum velocity that will be detected as having a magnitude greater than zero in pixels per second. Callback methods accepting a velocity will be clamped appropriately.

Parameters
`minVel: Float`	Minimum velocity to detect

settleCapturedViewAt

Added in 1.0.0

fun settleCapturedViewAt(finalLeft: Int, finalTop: Int): Boolean

Settle the captured view at the given (left, top) position. The appropriate velocity from prior motion will be taken into account. If this method returns true, the caller should invoke continueSettling on each subsequent frame to continue the motion until it returns false. If this method returns false there is no further work to do to complete the movement.

Parameters
`finalLeft: Int`	Settled left edge position for the captured view
`finalTop: Int`	Settled top edge position for the captured view

Returns
`Boolean`	true if animation should continue through `continueSettling` calls

shouldInterceptTouchEvent

Added in 1.0.0

fun shouldInterceptTouchEvent(ev: MotionEvent): Boolean

Check if this event as provided to the parent view's onInterceptTouchEvent should cause the parent to intercept the touch event stream.

Parameters
`ev: MotionEvent`	MotionEvent provided to onInterceptTouchEvent

Returns
`Boolean`	true if the parent view should return true from onInterceptTouchEvent

smoothSlideViewTo

Added in 1.0.0

fun smoothSlideViewTo(child: View, finalLeft: Int, finalTop: Int): Boolean

Animate the view child to the given (left, top) position. If this method returns true, the caller should invoke continueSettling on each subsequent frame to continue the motion until it returns false. If this method returns false there is no further work to do to complete the movement.

This operation does not count as a capture event, though getCapturedView will still report the sliding view while the slide is in progress.

Parameters
`child: View`	Child view to capture and animate
`finalLeft: Int`	Final left position of child
`finalTop: Int`	Final top position of child

Returns
`Boolean`	true if animation should continue through `continueSettling` calls

Protected functions

canScroll

Added in 1.0.0

protected fun canScroll(v: View, checkV: Boolean, dx: Int, dy: Int, x: Int, y: Int): Boolean

Tests scrollability within child views of v given a delta of dx.

Parameters
`v: View`	View to test for horizontal scrollability
`checkV: Boolean`	Whether the view v passed should itself be checked for scrollability (true), or just its children (false).
`dx: Int`	Delta scrolled in pixels along the X axis
`dy: Int`	Delta scrolled in pixels along the Y axis
`x: Int`	X coordinate of the active touch point
`y: Int`	Y coordinate of the active touch point

Returns
`Boolean`	true if child views of v can be scrolled by delta of dx.

ViewDragHelper

Summary

Nested types

Constants

Public functions

Protected functions

Constants

DIRECTION_ALL

DIRECTION_HORIZONTAL

DIRECTION_VERTICAL

EDGE_ALL

EDGE_BOTTOM

EDGE_LEFT

EDGE_RIGHT

EDGE_TOP

INVALID_POINTER

STATE_DRAGGING

STATE_IDLE

STATE_SETTLING

Public functions

abort

cancel

captureChildView

checkTouchSlop

checkTouchSlop

continueSettling

create

create

findTopChildUnder

flingCapturedView

getActivePointerId

getCapturedView

getDefaultEdgeSize

getEdgeSize

getMinVelocity

getTouchSlop

getViewDragState

isCapturedViewUnder

isEdgeTouched

isEdgeTouched

isPointerDown

isViewUnder

processTouchEvent

setEdgeSize

setEdgeTrackingEnabled

setMinVelocity

settleCapturedViewAt

shouldInterceptTouchEvent

smoothSlideViewTo

Protected functions

canScroll