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 |
abort()
|
open Unit |
cancel() The result of a call to this method is equivalent to |
open Unit |
captureChildView(@NonNull childView: View, activePointerId: Int) Capture a specific child view for dragging within the parent. |
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 |
continueSettling(deferCallbacks: Boolean) Move the captured settling view by the appropriate amount for the current time. |
open static ViewDragHelper! |
create(@NonNull forParent: ViewGroup, @NonNull cb: ViewDragHelper.Callback) Factory method to create a new ViewDragHelper. |
open static ViewDragHelper! |
create(@NonNull forParent: ViewGroup, sensitivity: Float, @NonNull cb: ViewDragHelper.Callback) Factory method to create a new ViewDragHelper. |
open View? |
findTopChildUnder(x: Int, y: Int) Find the topmost child under the given point within the parent view's coordinate system. |
open Unit |
flingCapturedView(minLeft: Int, minTop: Int, maxLeft: Int, maxTop: Int) Settle the captured view based on standard free-moving fling behavior. |
open Int | |
open View? | |
open Int |
Return the size of an edge. |
open Float |
Return the currently configured minimum velocity. |
open Int | |
open Int |
Retrieve the current drag state of this helper. |
open Boolean |
isCapturedViewUnder(x: Int, y: Int) Determine if the currently captured view is under the given point in the parent view's coordinate system. |
open Boolean |
isEdgeTouched(edges: Int) 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 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 |
isViewUnder(@Nullable view: View?, x: Int, y: Int) Determine if the supplied view is under the given point in the parent view's coordinate system. |
open Unit |
processTouchEvent(@NonNull ev: MotionEvent) Process a touch event received by the parent view. |
open Unit |
setEdgeTrackingEnabled(edgeFlags: Int) Enable edge tracking for the selected edges of the parent view. |
open Unit |
setMinVelocity(minVel: Float) Set the minimum velocity that will be detected as having a magnitude greater than zero in pixels per second. |
open Boolean |
settleCapturedViewAt(finalLeft: Int, finalTop: Int) Settle the captured view at the given (left, top) position. |
open Boolean |
shouldInterceptTouchEvent(@NonNull ev: MotionEvent) Check if this event as provided to the parent view's onInterceptTouchEvent should cause the parent to intercept the touch event stream. |
open Boolean |
smoothSlideViewTo(@NonNull child: View, finalLeft: Int, finalTop: Int) Animate the view |
Protected methods |
|
---|---|
open Boolean |
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: DIRECTION_HORIZONTAL | DIRECTION_VERTICAL
DIRECTION_HORIZONTAL
static val DIRECTION_HORIZONTAL: Int
Indicates that a check should occur along the horizontal axis
Value: 1 << 0
DIRECTION_VERTICAL
static val DIRECTION_VERTICAL: Int
Indicates that a check should occur along the vertical axis
Value: 1 << 1
EDGE_ALL
static val EDGE_ALL: Int
Edge flag set indicating all edges should be affected.
Value: EDGE_LEFT | EDGE_TOP | EDGE_RIGHT | EDGE_BOTTOM
EDGE_BOTTOM
static val EDGE_BOTTOM: Int
Edge flag indicating that the bottom edge should be affected.
Value: 1 << 3
EDGE_LEFT
static val EDGE_LEFT: Int
Edge flag indicating that the left edge should be affected.
Value: 1 << 0
EDGE_RIGHT
static val EDGE_RIGHT: Int
Edge flag indicating that the right edge should be affected.
Value: 1 << 1
EDGE_TOP
static val EDGE_TOP: Int
Edge flag indicating that the top edge should be affected.
Value: 1 << 2
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
abort
open fun abort(): Unit
cancel()
, but also abort all motion in progress and snap to the end of any animation.
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.
captureChildView
open fun captureChildView(@NonNull 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 |
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 |
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 |
create
open static fun create(@NonNull forParent: ViewGroup, @NonNull 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(@NonNull forParent: ViewGroup, sensitivity: Float, @NonNull 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 |
findTopChildUnder
@Nullable 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. |
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 |
getActivePointerId
open fun getActivePointerId(): Int
Return | |
---|---|
Int: The ID of the pointer currently dragging the captured view, or INVALID_POINTER . |
getCapturedView
@Nullable open fun getCapturedView(): View?
Return | |
---|---|
View?: The currently captured view, or null if no view has been captured. |
getEdgeSize
@Px 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 |
See Also
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 |
getTouchSlop
@Px open fun getTouchSlop(): Int
Return | |
---|---|
Int: The minimum distance in pixels that the user must travel to initiate a drag |
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 |
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 |
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 |
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 |
isViewUnder
open fun isViewUnder(@Nullable 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 |
processTouchEvent
open fun processTouchEvent(@NonNull 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 |
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 |
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 |
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 |
shouldInterceptTouchEvent
open fun shouldInterceptTouchEvent(@NonNull 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 |
smoothSlideViewTo
open fun smoothSlideViewTo(@NonNull 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 |
Protected methods
canScroll
protected open fun canScroll(@NonNull 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. |