androidx.ui.core.gesture

Top-level functions summary

Unit
DoubleTapGestureDetector(onDoubleTap: (PxPosition) -> Unit, children: () -> Unit)

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.

Unit
LongPressDragGestureDetector(longPressDragObserver: LongPressDragObserver, children: () -> Unit)

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

Unit
LongPressGestureDetector(onLongPress: (PxPosition) -> Unit, children: () -> Unit)

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

Unit
PressGestureDetector(onPress: (PxPosition) -> Unit = null, onRelease: () -> Unit = null, onCancel: () -> Unit = null, enabled: Boolean = true, children: () -> Unit)

Unit
PressIndicatorGestureDetector(onStart: (PxPosition) -> Unit = null, onStop: () -> Unit = null, onCancel: () -> Unit = null, enabled: Boolean = true, children: () -> Unit)

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

Unit
PressReleasedGestureDetector(onRelease: () -> Unit = null, consumeDownOnStart: Boolean = true, enabled: Boolean = true, children: () -> Unit)

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

Unit
RawDragGestureDetector(dragObserver: DragObserver, canStartDragging: () -> Boolean = null, children: () -> Unit)

This gesture detector detects dragging in any direction.

Unit
RawScaleGestureDetector(scaleObserver: RawScaleObserver, canStartScaling: () -> Boolean = null, children: () -> Unit)

This gesture detector detects scaling.

Unit
ScaleGestureDetector(scaleObserver: ScaleObserver, children: () -> Unit)

This gesture detector detects scaling.

Unit
ScaleSlopExceededGestureDetector(onScaleSlopExceeded: () -> Unit, children: () -> Unit)

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

Unit
TouchSlopDragGestureDetector(dragObserver: DragObserver, canDrag: (Direction) -> Boolean = null, startDragImmediately: Boolean = false, children: () -> Unit)

This gesture detector detects dragging in any direction.

Unit
TouchSlopExceededGestureDetector(onTouchSlopExceeded: () -> Unit, canDrag: (Direction) -> Boolean = null, children: () -> Unit)

This gesture filter detects when at least one pointer has moved far enough to exceed touch slop.

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.

Top-level functions

DoubleTapGestureDetector

@Composable fun DoubleTapGestureDetector(
    onDoubleTap: (PxPosition) -> Unit,
    children: () -> Unit
): Unit

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.

LongPressDragGestureDetector

@Composable fun LongPressDragGestureDetector(
    longPressDragObserver: LongPressDragObserver,
    children: () -> Unit
): Unit

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.

LongPressGestureDetector

@Composable fun LongPressGestureDetector(
    onLongPress: (PxPosition) -> Unit,
    children: () -> Unit
): Unit

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.

PressGestureDetector

@Composable fun PressGestureDetector(
    onPress: (PxPosition) -> Unit = null,
    onRelease: () -> Unit = null,
    onCancel: () -> Unit = null,
    enabled: Boolean = true,
    children: () -> Unit
): Unit

PressIndicatorGestureDetector

@Composable fun PressIndicatorGestureDetector(
    onStart: (PxPosition) -> Unit = null,
    onStop: () -> Unit = null,
    onCancel: () -> Unit = null,
    enabled: Boolean = true,
    children: () -> Unit
): Unit

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.

PressReleasedGestureDetector

@Composable fun PressReleasedGestureDetector(
    onRelease: () -> Unit = null,
    consumeDownOnStart: Boolean = true,
    enabled: Boolean = true,
    children: () -> Unit
): Unit

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

More specifically, it will call onRelease 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.

By default, this gesture detector also consumes the down change during the PointerEventPass.PostUp pass if it has not already been consumed. That behavior can be changed via consumeDownOnStart.

RawDragGestureDetector

@Composable fun RawDragGestureDetector(
    dragObserver: DragObserver,
    canStartDragging: () -> Boolean = null,
    children: () -> Unit
): Unit

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

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.

RawScaleGestureDetector

@Composable fun RawScaleGestureDetector(
    scaleObserver: RawScaleObserver,
    canStartScaling: () -> Boolean = null,
    children: () -> Unit
): Unit

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

ScaleGestureDetector

@Composable fun ScaleGestureDetector(
    scaleObserver: ScaleObserver,
    children: () -> Unit
): Unit

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

ScaleSlopExceededGestureDetector

@Composable fun ScaleSlopExceededGestureDetector(
    onScaleSlopExceeded: () -> Unit,
    children: () -> Unit
): Unit

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

This gesture detector is very similar to RawScaleGestureDetector 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 RawScaleGestureDetector, 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).

TouchSlopDragGestureDetector

@Composable fun TouchSlopDragGestureDetector(
    dragObserver: DragObserver,
    canDrag: (Direction) -> Boolean = null,
    startDragImmediately: Boolean = false,
    children: () -> Unit
): Unit

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.

TouchSlopExceededGestureDetector

@Composable fun TouchSlopExceededGestureDetector(
    onTouchSlopExceeded: () -> Unit,
    canDrag: (Direction) -> Boolean = null,
    children: () -> Unit
): Unit

This gesture filter detects when at least one pointer has moved far enough to exceed touch slop.

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

Parameters
onTouchSlopExceeded: () -> Unit Lamba that will be called when touch slop by at least 1 pointer has been exceeded in a supported direction. See canDrag.
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.

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

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. DoubleTapGestureRecognizer 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 TapGestureRecognizer; PrimaryPointerGestureRecognizer, which TapGestureRecognizer inherits from, uses kTouchSlop.)

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

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.