androidx.ui.core.gesture

Top-level functions summary

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

Responds to pointers going up, down within a small duration, and then up again.

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, children: () -> Unit)

Unit
PressIndicatorGestureDetector(onStart: (PxPosition) -> Unit = null, onStop: () -> Unit = null, onCancel: () -> Unit = null, 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, 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, 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 up, down within a small duration, and then up again.

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 have moved. LongPressDragObserver.onStop is called when the dragging 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).

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,
    children: () -> Unit
): Unit

PressIndicatorGestureDetector

@Composable fun PressIndicatorGestureDetector(
    onStart: (PxPosition) -> Unit = null,
    onStop: () -> Unit = null,
    onCancel: () -> Unit = null,
    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,
    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. 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).

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. RawScaleObserver.onStop is called when no pointers remain.

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, RawScaleObserver.onStart is called followed immediately by a call to RawScaleObserver.onScale. RawScaleObserver.onScale is then continuously called whenever the movement of pointers denotes scaling. RawScaleObserver.onStop is called when no pointers remain.

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,
    children: () -> Unit
): Unit

This gesture detector detects dragging in any direction.

Dragging begins when the touch slop distance (currently defined by TouchSlop) is surpassed in a supported direction (see DragObserver.onDrag). When dragging begins, DragObserver.onStart is called, followed immediately by a call to DragObserver.onDrag. DragObserver.onDrag is then continuously called whenever pointers have moved. DragObserver.onStop is called when the dragging ends due to all of the pointers no longer interacting with the DragGestureDetector (for example, the last finger has been lifted off of the DragGestureDetector).

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

Parameters
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.
dragObserver: DragObserver The callback interface to report all events related to dragging.

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.