ViewDragHelper

open class ViewDragHelper
kotlin.Any
   ↳ androidx.customview.widget.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 classes
abstract

A Callback is used as a communication channel with the ViewDragHelper back to the parent view using it.

Constants
static Int

Indicates that a check should occur along all axes

static Int

Indicates that a check should occur along the horizontal axis

static Int

Indicates that a check should occur along the vertical axis

static Int

Edge flag set indicating all edges should be affected.

static Int

Edge flag indicating that the bottom edge should be affected.

static Int

Edge flag indicating that the left edge should be affected.

static Int

Edge flag indicating that the right edge should be affected.

static Int

Edge flag indicating that the top edge should be affected.

static Int

A null/invalid pointer ID.

static Int

A view is currently being dragged.

static Int

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

static Int

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

Public methods
open Unit
flingCapturedView(minLeft: Int, minTop: Int, maxLeft: Int, maxTop: Int)

Settle the captured view based on standard free-moving fling behavior.

open Int

Retrieve the current drag state of this helper.

open 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).

open Boolean
checkTouchSlop(directions: Int)

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

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

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

open 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.

open Int

Return the size of an edge.

open Unit

The result of a call to this method is equivalent to #processTouchEvent(android.view.MotionEvent) receiving an ACTION_CANCEL event.

open Boolean

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

open Unit

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

open Boolean

Check if any of the edges specified were initially touched in the currently active gesture.

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

Check if any of the edges specified were initially touched by the pointer with the specified ID.

open Int

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

Animate the view child to the given (left, top) position.

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

Capture a specific child view for dragging within the parent.

open View?

Find the topmost child under the given point within the parent view's coordinate system.

open Int

open View?

open Boolean

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

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

Settle the captured view at the given (left, top) position.

open Boolean
continueSettling(deferCallbacks: Boolean)

Move the captured settling view by the appropriate amount for the current time.

open Unit

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

open Unit

Enable edge tracking for the selected edges of the parent view.

open Float

Return the currently configured minimum velocity.

open Unit

Process a touch event received by the parent view.

open static ViewDragHelper!

Factory method to create a new ViewDragHelper.

open static ViewDragHelper!
create(forParent: ViewGroup, sensitivity: Float, cb: ViewDragHelper.Callback)

Factory method to create a new ViewDragHelper.

Protected methods
open 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

static val DIRECTION_ALL: Int

Indicates that a check should occur along all axes

Value: 3

DIRECTION_HORIZONTAL

static val DIRECTION_HORIZONTAL: Int

Indicates that a check should occur along the horizontal axis

Value: 1

DIRECTION_VERTICAL

static val DIRECTION_VERTICAL: Int

Indicates that a check should occur along the vertical axis

Value: 2

EDGE_ALL

static val EDGE_ALL: Int

Edge flag set indicating all edges should be affected.

Value: 15

EDGE_BOTTOM

static val EDGE_BOTTOM: Int

Edge flag indicating that the bottom edge should be affected.

Value: 8

EDGE_LEFT

static val EDGE_LEFT: Int

Edge flag indicating that the left edge should be affected.

Value: 1

EDGE_RIGHT

static val EDGE_RIGHT: Int

Edge flag indicating that the right edge should be affected.

Value: 2

EDGE_TOP

static val EDGE_TOP: Int

Edge flag indicating that the top edge should be affected.

Value: 4

INVALID_POINTER

static val INVALID_POINTER: Int

A null/invalid pointer ID.

Value: -1

STATE_DRAGGING

static val STATE_DRAGGING: Int

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

Value: 1

STATE_IDLE

static val STATE_IDLE: Int

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

Value: 0

STATE_SETTLING

static val STATE_SETTLING: Int

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

Value: 2

Public methods

flingCapturedView

open 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(boolean) 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

getViewDragState

open fun getViewDragState(): Int

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

Return
Int: The current drag state

isPointerDown

open 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(android.view.MotionEvent) or #processTouchEvent(android.view.MotionEvent). 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
Return
Boolean: true if the pointer with the given ID is still down

checkTouchSlop

open 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(android.view.MotionEvent) or #processTouchEvent(android.view.MotionEvent). 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
Return
Boolean: true if the slop threshold has been crossed, false otherwise

checkTouchSlop

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

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

This depends on internal state populated by #shouldInterceptTouchEvent(android.view.MotionEvent) or #processTouchEvent(android.view.MotionEvent). 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
pointerId Int: ID of the pointer to slop check as specified by MotionEvent
Return
Boolean: true if the slop threshold has been crossed, false otherwise

isViewUnder

open 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 View?: X position to test in the parent's coordinate system
y View?: Y position to test in the parent's coordinate system
Return
Boolean: true if the supplied view is under the given point, false otherwise

getEdgeSize

open fun getEdgeSize(): 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.

Return
Int: The size of an edge in pixels

cancel

open fun cancel(): Unit

The result of a call to this method is equivalent to #processTouchEvent(android.view.MotionEvent) receiving an ACTION_CANCEL event.

isCapturedViewUnder

open 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
Return
Boolean: true if the captured view is under the given point, false otherwise

abort

open fun abort(): Unit

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

isEdgeTouched

open 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
Return
Boolean: true if any of the edges specified were initially touched in the current gesture

isEdgeTouched

open 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
Return
Boolean: true if any of the edges specified were initially touched in the current gesture

getActivePointerId

open fun getActivePointerId(): Int
Return
Int: The ID of the pointer currently dragging the captured view, or #INVALID_POINTER.

smoothSlideViewTo

open 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(boolean) 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 View: Final left position of child
finalTop View: Final top position of child
Return
Boolean: true if animation should continue through #continueSettling(boolean) calls

captureChildView

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

Capture a specific child view for dragging within the parent. The callback will be notified but Callback#tryCaptureView(android.view.View, int) will not be asked permission to capture this view.

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

findTopChildUnder

open 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 Callback#getOrderedChildIndex(int).

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
Return
View?: The topmost child view under (x, y) or null if none found.

getTouchSlop

open fun getTouchSlop(): Int
Return
Int: The minimum distance in pixels that the user must travel to initiate a drag

getCapturedView

open fun getCapturedView(): View?
Return
View?: The currently captured view, or null if no view has been captured.

shouldInterceptTouchEvent

open 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
Return
Boolean: true if the parent view should return true from onInterceptTouchEvent

settleCapturedViewAt

open 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(boolean) 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
Return
Boolean: true if animation should continue through #continueSettling(boolean) calls

continueSettling

open 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 android.view.View#computeScroll() or similar methods invoked as part of layout or drawing.
Return
Boolean: true if settle is still in progress

setMinVelocity

open 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

setEdgeTrackingEnabled

open fun setEdgeTrackingEnabled(edgeFlags: Int): Unit

Enable edge tracking for the selected edges of the parent view. The callback's Callback#onEdgeTouched(int, int) and Callback#onEdgeDragStarted(int, int) 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

getMinVelocity

open 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.

Return
Float: the minimum velocity that will be detected

processTouchEvent

open 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

create

open static fun create(forParent: ViewGroup, cb: ViewDragHelper.Callback): ViewDragHelper!

Factory method to create a new ViewDragHelper.

Parameters
forParent ViewGroup: Parent view to monitor
cb ViewGroup: Callback to provide information and receive events
Return
ViewDragHelper!: a new ViewDragHelper instance

create

open 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 ViewGroup: 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 ViewGroup: Callback to provide information and receive events
Return
ViewDragHelper!: a new ViewDragHelper instance

Protected methods

canScroll

protected open 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 View: Whether the view v passed should itself be checked for scrollability (true), or just its children (false).
dx View: Delta scrolled in pixels along the X axis
dy View: Delta scrolled in pixels along the Y axis
x View: X coordinate of the active touch point
y View: Y coordinate of the active touch point
Return
Boolean: true if child views of v can be scrolled by delta of dx.