androidx.ui.core.gesture

Interfaces

DragObserver

Defines the callbacks associated with dragging.

LongPressDragObserver

RawScaleObserver

Observes various events sent by rawScaleGestureFilter.

ScaleObserver

Observes various events sent by scaleGestureFilter.

ScrollCallback

Defines the callbacks associated with scrolling.

Annotations

ExperimentalPointerInput

Top-level properties summary

Duration

The minimum time from the end of the first tap to the start of the second tap in a double-tap gesture.

Dp

Distance between the initial position of the first touch and the start position of a potential second touch for the second touch to be considered the second touch of a double-tap gesture.

Duration

The maximum time from the start of the first tap to the start of the second tap in a double-tap gesture.

Dp

The maximum distance that the first touch in a double-tap gesture can travel before deciding that it is not part of a double-tap gesture.

Dp

Maximum distance between the down and up pointers for a tap.

Duration

Maximum length of time between a tap down and a tap up for the gesture to be considered a tap.

Duration

The maximum time from the start of the first tap to the start of the second tap in a jump-tap gesture.

Duration

The time before a long press gesture attempts to win.

Dp

Drag gesture fling velocities are clipped to this value.

Dp

The minimum velocity for a touch to consider that touch to trigger a fling gesture.

DpSquared

The distance a touch has to travel for the framework to be confident that the gesture is a paging gesture.

DpSquared

The distance a touch has to travel for the framework to be confident that the gesture is a panning gesture.

Duration

The time that must elapse before a tap gesture sends onTapDown, if there's any doubt that the gesture is a tap.

Dp

The absolute cumulative average change in distance of all pointers from the average pointer over time that must be surpassed to indicate the user is trying to scale.

Dp

The distance a touch has to travel for the framework to be confident that the gesture is a scroll gesture, or, inversely, the maximum distance that a touch can travel before the framework becomes confident that it is not a tap.

Dp

The margin around a dialog, popup menu, or other window-like composable inside which we do not consider a tap to dismiss the composable.

Duration

The time for which zoom controls (e.

Extension functions summary

For kotlin.collections.List
Boolean

Utility method that determines if any pointers are currently in bounds.

For Modifier
Modifier

Responds to pointers going down and up (tap) and then down and up again (another tap) with minimal gap of time between the first up and the second down.

Modifier
Modifier.dragGestureFilter(dragObserver: DragObserver, canDrag: (Direction) -> Boolean = null, startDragImmediately: Boolean = false)

This gesture detector detects dragging in any direction.

Modifier
Modifier.dragSlopExceededGestureFilter(onDragSlopExceeded: () -> Unit, canDrag: (Direction) -> Boolean = null, orientation: Orientation? = null)

This gesture filter detects when the average distance change of all pointers surpasses the touch slop.

Modifier

This gesture detector detects dragging in any direction, but only after a long press has first occurred.

Modifier

Responds to a pointer being "down" for an extended amount of time.

Modifier
Modifier.pressIndicatorGestureFilter(onStart: (Offset) -> Unit = null, onStop: () -> Unit = null, onCancel: () -> Unit = null, enabled: Boolean = true)

This gesture detector has callbacks for when a press gesture starts and ends for the purposes of displaying visual feedback for those two states.

Modifier
Modifier.rawDragGestureFilter(dragObserver: DragObserver, canStartDragging: () -> Boolean = null, orientation: Orientation? = null)

This gesture detector detects dragging in any direction.

Modifier
Modifier.rawPressStartGestureFilter(onPressStart: (Offset) -> Unit, enabled: Boolean = false, executionPass: PointerEventPass = PointerEventPass.PostUp)

Reacts if the first pointer input change it sees is an unconsumed down change, and if it reacts, consumes all further down changes.

Modifier
Modifier.rawScaleGestureFilter(scaleObserver: RawScaleObserver, canStartScaling: () -> Boolean = null)

This gesture detector detects scaling.

Modifier

This gesture detector detects scaling.

Modifier
Modifier.scaleSlopExceededGestureFilter(onScaleSlopExceeded: () -> Unit)

This gesture detector detects when a user's pointer input is intended to include scaling.

Modifier
Modifier.scrollGestureFilter(scrollCallback: ScrollCallback, orientation: Orientation, canDrag: (Direction) -> Boolean = null, startDragImmediately: Boolean = false)

Like Modifier.dragGestureFilter, this gesture filter will detect dragging, but will only do so along the given orientation.

Modifier

This gesture detector fires a callback when a traditional press is being released.

Top-level properties

DoubleTapMinTime

val DoubleTapMinTime: Duration

The minimum time from the end of the first tap to the start of the second tap in a double-tap gesture. (Currently not honored by the DoubleTapGestureFilter.)

DoubleTapSlop

val DoubleTapSlop: Dp

Distance between the initial position of the first touch and the start position of a potential second touch for the second touch to be considered the second touch of a double-tap gesture.

DoubleTapTimeout

val DoubleTapTimeout: Duration

The maximum time from the start of the first tap to the start of the second tap in a double-tap gesture.

DoubleTapTouchSlop

val DoubleTapTouchSlop: Dp

The maximum distance that the first touch in a double-tap gesture can travel before deciding that it is not part of a double-tap gesture. DoubleTapGestureFilter also restricts the second touch to this distance.

HoverTapSlop

val HoverTapSlop: Dp

Maximum distance between the down and up pointers for a tap. (Currently not honored by the TapGestureFilter.

HoverTapTimeout

val HoverTapTimeout: Duration

Maximum length of time between a tap down and a tap up for the gesture to be considered a tap. (Currently not honored by the TapGestureFilter.)

JumpTapTimeout

val JumpTapTimeout: Duration

The maximum time from the start of the first tap to the start of the second tap in a jump-tap gesture.

LongPressTimeout

val LongPressTimeout: Duration

The time before a long press gesture attempts to win.

MaxFlingVelocity

val MaxFlingVelocity: Dp

Drag gesture fling velocities are clipped to this value.

MinFlingVelocity

val MinFlingVelocity: Dp

The minimum velocity for a touch to consider that touch to trigger a fling gesture.

PagingTouchSlop

val PagingTouchSlop: DpSquared

The distance a touch has to travel for the framework to be confident that the gesture is a paging gesture. (Currently not used, because paging uses a regular drag gesture, which uses kTouchSlop.)

PanSlop

val PanSlop: DpSquared

The distance a touch has to travel for the framework to be confident that the gesture is a panning gesture.

PressTimeout

val PressTimeout: Duration

The time that must elapse before a tap gesture sends onTapDown, if there's any doubt that the gesture is a tap.

ScaleSlop

val ScaleSlop: Dp

The absolute cumulative average change in distance of all pointers from the average pointer over time that must be surpassed to indicate the user is trying to scale.

For example, if ScaleSlop is 5 DP and 2 pointers were 1 DP away from each other and now are 11.00001 DP away from each other, the gesture will be interpreted to include scaling (both pointers are slightly more than 5 pixels away from the average of the pointers than they were).

TouchSlop

val TouchSlop: Dp

The distance a touch has to travel for the framework to be confident that the gesture is a scroll gesture, or, inversely, the maximum distance that a touch can travel before the framework becomes confident that it is not a tap.

WindowTouchSlop

val WindowTouchSlop: Dp

The margin around a dialog, popup menu, or other window-like composable inside which we do not consider a tap to dismiss the composable. (Not currently used.)

ZoomControlsTimeout

val ZoomControlsTimeout: Duration

The time for which zoom controls (e.g. in a map interface) are to be displayed on the screen, from the moment they were last requested.

Extension functions

anyPointersInBounds

fun List<PointerInputChange>.anyPointersInBounds(bounds: IntSize): Boolean

Utility method that determines if any pointers are currently in bounds.

A pointer is considered in bounds if it is currently down and it's current position is within the provided bounds

Return
True if at least one pointer is in bounds.

doubleTapGestureFilter

fun Modifier.doubleTapGestureFilter(onDoubleTap: (Offset) -> Unit): Modifier

Responds to pointers going down and up (tap) and then down and up again (another tap) with minimal gap of time between the first up and the second down.

Note: This is a temporary implementation to unblock dependents. Once the underlying API that allows double tap to temporarily block tap from firing is complete, this gesture detector will not block tap when the first "up" occurs. It will however block the 2nd up from causing tap to fire.

Also, given that this gesture detector is so temporary, opting to not write substantial tests.

dragGestureFilter

fun Modifier.dragGestureFilter(
    dragObserver: DragObserver,
    canDrag: (Direction) -> Boolean = null,
    startDragImmediately: Boolean = false
): Modifier

This gesture detector detects dragging in any direction.

Dragging normally begins when the touch slop distance (currently defined by TouchSlop) is surpassed in a supported direction (see DragObserver.onDrag). When dragging begins in this manner, DragObserver.onStart is called, followed immediately by a call to DragObserver.onDrag. DragObserver.onDrag is then continuously called whenever pointers have moved. The gesture ends with either a call to DragObserver.onStop or DragObserver.onCancel, only after DragObserver.onStart is called. DragObserver.onStop is called when the dragging ends due to all of the pointers no longer interacting with the DragGestureDetector (for example, the last pointer has been lifted off of the DragGestureDetector). DragObserver.onCancel is called when the dragging ends due to a system cancellation event.

If startDragImmediately is set to true, dragging will begin as soon as soon as a pointer comes in contact with it, effectively ignoring touch slop and blocking any descendants from reacting the "down" change. When dragging begins in this manner, DragObserver.onStart is called immediately and is followed by DragObserver.onDrag when some drag distance has occurred.

When multiple pointers are touching the detector, the drag distance is taken as the average of all of the pointers.

Parameters
dragObserver: DragObserver The callback interface to report all events related to dragging.
canDrag: (Direction) -> Boolean = null Set to limit the directions under which touch slop can be exceeded. Return true if you want a drag to be started due to the touch slop being surpassed in the given Direction. If canDrag is not provided, touch slop will be able to be exceeded in all directions.
startDragImmediately: Boolean = false Set to true to have dragging begin immediately when a pointer is "down", preventing children from responding to the "down" change. Generally, this parameter should be set to true when the child of the GestureDetector is animating, such that when a finger touches it, dragging is immediately started so the animation stops and dragging can occur.

dragSlopExceededGestureFilter

fun Modifier.dragSlopExceededGestureFilter(
    onDragSlopExceeded: () -> Unit,
    canDrag: (Direction) -> Boolean = null,
    orientation: Orientation? = null
): Modifier

This gesture filter detects when the average distance change of all pointers surpasses the touch slop.

The value of touch slop is currently defined internally as the constant TouchSlop.

Note: canDrag and orientation interact such that canDrag will only be called for Directions that are included in the given orientation.

Note: Changing the value of orientation will reset the gesture filter such that it will not respond to input until new pointers are detected.

Parameters
onDragSlopExceeded: () -> Unit Called when touch slop is exceeded in a supported direction and orientation.
canDrag: (Direction) -> Boolean = null Set to limit the types of directions under which touch slop can be exceeded. Return true if you want a drag to be started due to the touch slop being surpassed in the given Direction. If canDrag is not provided, touch slop will be able to be exceeded in all directions.
orientation: Orientation? = null If provided, limits the Directions that scroll slop can be exceeded in to those that are included in the given orientation and does not consider pointers that are locked to other orientations.

longPressDragGestureFilter

fun Modifier.longPressDragGestureFilter(longPressDragObserver: LongPressDragObserver): Modifier

This gesture detector detects dragging in any direction, but only after a long press has first occurred.

Dragging begins once a long press has occurred and then dragging occurs. When long press occurs, LongPressDragObserver.onLongPress is called. Once dragging has occurred, LongPressDragObserver.onDragStart will be called. LongPressDragObserver.onDrag is then continuously called whenever pointer movement results in a drag. The gesture will end with either a call to LongPressDragObserver.onStop or LongPressDragObserver.onCancel. Either will be called after LongPressDragObserver.onLongPress is called. LongPressDragObserver.onStop is called when the the gesture ends due to all of the pointers no longer interacting with the LongPressDragGestureDetector (for example, the last finger has been lifted off of the LongPressDragGestureDetector). LongPressDragObserver.onCancel is called in response to a system cancellation event.

When multiple pointers are touching the detector, the drag distance is taken as the average of all of the pointers.

Parameters
longPressDragObserver: LongPressDragObserver The callback interface to report all events.

longPressGestureFilter

fun Modifier.longPressGestureFilter(onLongPress: (Offset) -> Unit): Modifier

Responds to a pointer being "down" for an extended amount of time.

Note: this is likely a temporary, naive, and flawed approach. It is not necessarily guaranteed to interoperate well with forthcoming behavior related to disambiguation between multi-tap (double tap, triple tap) and tap.

pressIndicatorGestureFilter

fun Modifier.pressIndicatorGestureFilter(
    onStart: (Offset) -> Unit = null,
    onStop: () -> Unit = null,
    onCancel: () -> Unit = null,
    enabled: Boolean = true
): Modifier

This gesture detector has callbacks for when a press gesture starts and ends for the purposes of displaying visual feedback for those two states.

More specifically:

This gesture detector always consumes the down change during the PointerEventPass.PostUp pass.

rawDragGestureFilter

fun Modifier.rawDragGestureFilter(
    dragObserver: DragObserver,
    canStartDragging: () -> Boolean = null,
    orientation: Orientation? = null
): Modifier

This gesture detector detects dragging in any direction.

Note: By default, this gesture detector only waits for a single pointer to have moved to start dragging. It is extremely likely that you don't want to use this gesture detector directly, but instead use a drag gesture detector that does wait for some other condition to have occurred (such as dragGestureFilter which waits for a single pointer to have passed touch slop before dragging starts).

Dragging begins when the a single pointer has moved and either canStartDragging is null or returns true. When dragging begins, DragObserver.onStart is called. DragObserver.onDrag is then continuously called whenever the average movement of all pointers has movement along the x or y axis. The gesture ends with either a call to DragObserver.onStop or DragObserver.onCancel, only after DragObserver.onStart is called. DragObserver.onStop is called when the dragging ends due to all of the pointers no longer interacting with the DragGestureDetector (for example, the last pointer has been lifted off of the DragGestureDetector). DragObserver.onCancel is called when the dragging ends due to a system cancellation event.

When multiple pointers are touching the detector, the drag distance is taken as the average of all of the pointers.

Note: Changing the value of orientation will reset the gesture filter such that it will not respond to input until new pointers are detected.

Parameters
dragObserver: DragObserver The callback interface to report all events related to dragging.
canStartDragging: () -> Boolean = null If set, Before dragging is started (DragObserver.onStart is called), canStartDragging is called to check to see if it is allowed to start.
orientation: Orientation? = null Limits the directions under which dragging can occur to those that are within the provided orientation, locks pointers that are used to drag in the given orientation to that orientation, and ignores pointers that are locked to other orientations. If no orientation is provided, does none of the above.

rawPressStartGestureFilter

fun Modifier.rawPressStartGestureFilter(
    onPressStart: (Offset) -> Unit,
    enabled: Boolean = false,
    executionPass: PointerEventPass = PointerEventPass.PostUp
): Modifier

Reacts if the first pointer input change it sees is an unconsumed down change, and if it reacts, consumes all further down changes.

This GestureDetector is not generally intended to be used directly, but is instead intended to be used as a building block to create more complex GestureDetectors.

This GestureDetector is a bit more experimental then the other GestureDetectors (the number and types of GestureDetectors is still very much a work in progress) and is intended to be a generically useful building block for more complicated GestureDetectors.

The theory is that this GestureDetector can be reused in PressIndicatorGestureDetector, and there could be a corresponding RawPressReleasedGestureDetector.

Parameters
onPressStart: (Offset) -> Unit Called when the first pointer "presses" on the GestureDetector. Offset is the position of that first pointer on press.
enabled: Boolean = false If false, this GestureDetector will effectively act as if it is not in the hierarchy.
executionPass: PointerEventPass = PointerEventPass.PostUp The PointerEventPass during which this GestureDetector will attempt to react to and consume down changes. Defaults to PointerEventPass.PostUp.

rawScaleGestureFilter

fun Modifier.rawScaleGestureFilter(
    scaleObserver: RawScaleObserver,
    canStartScaling: () -> Boolean = null
): Modifier

This gesture detector detects scaling.

Scaling is when the average distance between a set of pointers changes over time. It is also known as pinch, or pinch to zoom.

Note: By default, this gesture detector will start as soon as the average distance between pointers changes by just a little bit. It is likely that you don't want to use this gesture detector directly, but instead use a scale gesture detector that is less aggressive about starting (such as rawScaleGestureFilter which waits for a pointer to have passed touch slop before starting).

Scaling begins when the average distance between a set of pointers changes and either canStartScaling is null or returns true. When scaling begins, RawScaleObserver.onStart is called followed immediately by a call to RawScaleObserver.onScale. RawScaleObserver.onScale is then continuously called whenever the movement of all pointers denotes scaling. The gesture stops with either a call to RawScaleObserver.onStop or RawScaleObserver.onCancel, either of which will only be called if RawScaleObserver.onStart was previously called. RawScaleObserver.onStop is called when no pointers remain. RawScaleObserver.onCancel is called due to a system cancellation event.

Parameters
scaleObserver: RawScaleObserver The callback interface to report all events related to scaling.
canStartScaling: () -> Boolean = null If set, before scaling is started (RawScaleObserver.onStart is called), canStartScaling is called for each pointer event to check to see if it is allowed to start.

scaleGestureFilter

fun Modifier.scaleGestureFilter(scaleObserver: ScaleObserver): Modifier

This gesture detector detects scaling.

Scaling is when the average distance between a set of pointers changes over time. It is also known as pinch, or pinch to zoom.

Scaling begins when the average distance between a set of pointers changes and at least 1 pointer moves beyond the touch slop distance (currently defined by TouchSlop). When scaling begins, ScaleObserver.onStart is called followed immediately by a call to ScaleObserver.onScale. ScaleObserver.onScale is then continuously called whenever the movement of pointers denotes scaling. The gesture stops with either a call to RawScaleObserver.onStop or RawScaleObserver.onCancel, either of which will only be called if RawScaleObserver.onStart was previously called. RawScaleObserver.onStop is called when no pointers remain. RawScaleObserver.onCancel is called due to a system cancellation event.

This gesture detector is similar to rawScaleGestureFilter except that it is made for more standard use cases where touch slop should likely be respected and no "nested scaling" is needed.

Parameters
scaleObserver: ScaleObserver The callback interface to report all events related to scaling.

scaleSlopExceededGestureFilter

fun Modifier.scaleSlopExceededGestureFilter(onScaleSlopExceeded: () -> Unit): Modifier

This gesture detector detects when a user's pointer input is intended to include scaling.

This gesture detector is very similar to rawScaleGestureFilter except that instead of providing callbacks for scaling, it instead provides one callback for when a user is intending to scale. It does so using the same semantics as rawScaleGestureFilter, and simply waits until the user has scaled just enough to suggest the user is truly intended to scale.

The gesture is considered to include scaling when the absolute cumulative average change in distance of all pointers from the average pointer over time surpasses a particular value (currently ScaleSlop).

For example, if the ScaleSlop is 5 pixels and 2 pointers were 1 pixel away from each other and now are 11.00001 pixels away from each other, the slop will have been surpassed and onScaleSlopExceeded will be called (both pointers are slightly more than 5 pixels away from the average of the pointers than they were).

scrollGestureFilter

fun Modifier.scrollGestureFilter(
    scrollCallback: ScrollCallback,
    orientation: Orientation,
    canDrag: (Direction) -> Boolean = null,
    startDragImmediately: Boolean = false
): Modifier

Like Modifier.dragGestureFilter, this gesture filter will detect dragging, but will only do so along the given orientation.

This gesture filter also disambiguates amongst other scrollGestureFilters such that for all pointers that this gesture filter uses to scroll in the given orientation, other scrollGestureFilters (or other clients of ScrollOrientationLocker) will not use those same pointers to drag in the other orientation. Likewise, this scrollGestureFilter will not use pointers to drag if they are already being used to drag in a different orientation.

Note: canDrag will only be queried in directions that exist within the given orientation.

Note: Changing the value of orientation will reset the gesture filter such that it will not respond to input until new pointers are detected.

Parameters
scrollCallback: ScrollCallback : The set of callbacks for scrolling.
orientation: Orientation : The orientation this gesture filter uses.
canDrag: (Direction) -> Boolean = null Set to limit the types of directions under which touch slop can be exceeded. Return true if you want a drag to be started due to the touch slop being surpassed in the given Direction. If canDrag is not provided, touch slop will be able to be exceeded in all directions that are in the provided orientation.
startDragImmediately: Boolean = false Set to true to have dragging begin immediately when a pointer is "down", preventing children from responding to the "down" change. Generally, this parameter should be set to true when the child of the GestureDetector is animating, such that when a finger touches it, dragging is immediately started so the animation stops and dragging can occur.

tapGestureFilter

fun Modifier.tapGestureFilter(onTap: (Offset) -> Unit): Modifier

This gesture detector fires a callback when a traditional press is being released. This is generally the same thing as "onTap" or "onClick".

onTap is called with the position of the last pointer to go "up".

More specifically, it will call onTap if:

  • All of the first PointerInputChanges it receives during the PointerEventPass.PostUp pass have unconsumed down changes, thus representing new set of pointers, none of which have had their down events consumed.
  • The last PointerInputChange it receives during the PointerEventPass.PostUp pass has an unconsumed up change.
  • While it has at least one pointer touching it, no PointerInputChange has had any movement consumed (as that would indicate that something in the heirarchy moved and this a press should be cancelled.
  • It also fully cooperates with DelayUpEvents it receives such that it will delay calling onTap if all of it's up events are being blocked. If it was being blocked and later is allowed to fire it's up event (which is onTap) it will do so and consume the delayed up custom event such that no other gesture filters will also respond to the delayed up.
Parameters
onTap: (Offset) -> Unit Called when a tap has occurred.