PointerInputChange

Describes a change that has occurred for a particular pointer, as well as how much of the change has been consumed (meaning, used by a node in the UI).

The position represents the position of the pointer relative to the element that this PointerInputChange is being dispatched to.

Note 1: A PointerEvent's PointerEventType is the cause of an event and the associated PointerInputChange's properties reflecting that. Most of those are exclusive, in other words, a Press/Release PointerEventType will not cause a scrollDelta change and a Scroll PointerEventType will not cause a pressed or previousPressed change. However, either a a Scroll or a Press/Release may contain a position change in its PointerInputChanges. (You can imagine one finger moving while another is lifted up.)

Examples of PointerEventType and the associated PointerInputChange property changes:

  • Press -> press will change (position may change) but scroll delta will not.

  • Release -> press will change (position may change) but scroll delta will not.

  • Move -> position will change but press and scroll delta will not.

  • Scroll -> scroll delta will change (position may change) but press will not.

Note 2: The position values can be outside the actual bounds of the element itself meaning the numbers can be negative or larger than the element bounds.

The previousPosition represents the position of the pointer offset to the current position of the pointer relative to the screen.

This means that position and previousPosition can always be used to understand how much a pointer has moved relative to an element, even if that element is moving along with the changes to the pointer. For example, if a pointer touches a 1x1 pixel box in the middle, position will report a position of (0, 0) when dispatched to it. If the next event moves x position 5 pixels, position will report (5, 0) and previousPosition will report (0, 0). If the box moves all 5 pixels, and the next event represents the pointer moving along the x axis for 5 more pixels, position will again report (5, 0) and previousPosition will report (0, 0).

Summary

Public constructors
PointerInputChange(
    id: PointerId,
    uptimeMillis: Long,
    position: Offset,
    pressed: Boolean,
    previousUptimeMillis: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    isInitiallyConsumed: Boolean,
    type: PointerType,
    scrollDelta: Offset
)
Cmn
PointerInputChange(
    id: PointerId,
    uptimeMillis: Long,
    position: Offset,
    pressed: Boolean,
    pressure: Float,
    previousUptimeMillis: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    isInitiallyConsumed: Boolean,
    type: PointerType,
    scrollDelta: Offset
)
Cmn

Public functions
Unit

Consume change event, claiming all the corresponding change info to the caller.
Cmn
PointerInputChange
copy(
    id: PointerId,
    currentTime: Long,
    currentPosition: Offset,
    currentPressed: Boolean,
    previousTime: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    type: PointerType,
    scrollDelta: Offset
)

Make a shallow copy of the PointerInputChange
Cmn
PointerInputChange
copy(
    id: PointerId,
    currentTime: Long,
    currentPosition: Offset,
    currentPressed: Boolean,
    pressure: Float,
    previousTime: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    type: PointerType,
    scrollDelta: Offset
)

Make a shallow copy of the PointerInputChange
Cmn
PointerInputChange
copy(
    id: PointerId,
    currentTime: Long,
    currentPosition: Offset,
    currentPressed: Boolean,
    previousTime: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    consumed: ConsumedData,
    type: PointerType,
    scrollDelta: Offset
)

This function is deprecated. Partial consumption has been deprecated.
Cmn
PointerInputChange
@ExperimentalComposeUiApi
copy(
    id: PointerId,
    currentTime: Long,
    currentPosition: Offset,
    currentPressed: Boolean,
    previousTime: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    type: PointerType,
    historical: List<HistoricalChange>,
    scrollDelta: Offset
)

Make a shallow copy of the PointerInputChange
Cmn
PointerInputChange
copy(
    id: PointerId,
    currentTime: Long,
    currentPosition: Offset,
    currentPressed: Boolean,
    pressure: Float,
    previousTime: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    type: PointerType,
    historical: List<HistoricalChange>,
    scrollDelta: Offset
)

Make a shallow copy of the PointerInputChange
Cmn
open String
Cmn

Public properties
ConsumedData

This property is deprecated. use isConsumed and consume() pair of methods instead
Cmn
List<HistoricalChange>

Optional high-frequency pointer moves in between the last two dispatched events.
Cmn
PointerId

The unique id of the pointer associated with this PointerInputChange.
Cmn
Boolean

Indicates whether the change was consumed or not.
Cmn
Offset

The Offset of the current pointer event, relative to the containing element (values can be negative or larger than the element bounds).
Cmn
Boolean

true if the pointer event is considered "pressed." For example, finger touching the screen or a mouse button is pressed pressed would be true.
Cmn
Float

The pressure of the of the pointer event
Cmn
Offset

The Offset of the previous pointer event, offset to the position and relative to the containing element.
Cmn
Boolean

true if the pointer event was considered "pressed." For example , if a finger was touching the screen or a mouse button was pressed, previousPressed would be true.
Cmn
Long

The uptimeMillis of the previous pointer event
Cmn
Offset

The amount of scroll wheel movement in the horizontal and vertical directions.
Cmn
PointerType

The device type that produced the event, such as mouse, or touch.git
Cmn
Long

The time of the current pointer event, in milliseconds.
Cmn

Extension functions
Boolean

This function is deprecated. Partial consumption has been deprecated.
Cmn
Boolean

True if this PointerInputChange represents a pointer coming in contact with the screen and that change has not been consumed.
Cmn
Boolean

True if this PointerInputChange represents a pointer coming in contact with the screen, whether or not that change has been consumed.
Cmn
Boolean

True if this PointerInputChange represents a pointer breaking contact with the screen and that change has not been consumed.
Cmn
Boolean

True if this PointerInputChange represents a pointer breaking contact with the screen, whether or not that change has been consumed.
Cmn
Unit

This function is deprecated. Use consume() instead
Cmn
Unit

This function is deprecated. Partial consumption has been deprecated.
Cmn
Unit

This function is deprecated. Partial consumption has been deprecated.
Cmn
Boolean

This function is deprecated. Use isOutOfBounds() that supports minimum touch target
Cmn
Boolean
PointerInputChange.isOutOfBounds(
    size: IntSize,
    extendedTouchPadding: Size
)

Returns true if the pointer has moved outside of the pointer region.
Cmn
Offset

The distance that the pointer has moved on the screen minus any distance that has been consumed.
Cmn
Boolean

This function is deprecated. Partial consumption has been deprecated.
Cmn
Offset

The distance that the pointer has moved on the screen, ignoring the fact that it might have been consumed.
Cmn
Boolean

True if this PointerInputChange represents a pointer moving on the screen and some of that movement has not been consumed.
Cmn
Boolean

True if this PointerInputChange represents a pointer moving on the screen ignoring how much of that movement may have been consumed.
Cmn

Public constructors

PointerInputChange

Cmn 
PointerInputChange(
    id: PointerId,
    uptimeMillis: Long,
    position: Offset,
    pressed: Boolean,
    previousUptimeMillis: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    isInitiallyConsumed: Boolean,
    type: PointerType = PointerType.Touch,
    scrollDelta: Offset = Offset.Zero
)

PointerInputChange

Cmn 
PointerInputChange(
    id: PointerId,
    uptimeMillis: Long,
    position: Offset,
    pressed: Boolean,
    pressure: Float,
    previousUptimeMillis: Long,
    previousPosition: Offset,
    previousPressed: Boolean,
    isInitiallyConsumed: Boolean,
    type: PointerType = PointerType.Touch,
    scrollDelta: Offset = Offset.Zero
)
Parameters
id: PointerId

The unique id of the pointer associated with this PointerInputChange.
uptimeMillis: Long

The time of the current pointer event, in milliseconds. The start (0) time is platform-dependent
position: Offset

The Offset of the current pointer event, relative to the containing element (values can be negative or larger than the element bounds).
pressed: Boolean

true if the pointer event is considered "pressed." For example, finger touching the screen or a mouse button is pressed pressed would be true.
pressure: Float

The pressure of the of the pointer event
previousUptimeMillis: Long

The uptimeMillis of the previous pointer event
previousPosition: Offset

The Offset of the previous pointer event, offset to the position and relative to the containing element.
previousPressed: Boolean

true if the pointer event was considered "pressed." For example , if a finger was touching the screen or a mouse button was pressed, previousPressed would be true.
isInitiallyConsumed: Boolean

whether the change was consumed from the start or not. This value can change over time as change is propagated through the pointer handlers. To query the actual status of the change use isConsumed
type: PointerType = PointerType.Touch

The device type that produced the event, such as mouse, or touch.git
scrollDelta: Offset = Offset.Zero

The amount of scroll wheel movement in the horizontal and vertical directions.

Public functions

consume

Cmn
Added in 1.1.0
fun consume(): Unit

Consume change event, claiming all the corresponding change info to the caller. This is usually needed when, button, when being clicked, consumed the "up" event so no other parents of this button could consume this "up" again.

"Consumption" is just an indication of the claim and each pointer input handler implementation must manually check this flag to respect it.

copy

Cmn 
fun copy(
    id: PointerId = this.id,
    currentTime: Long = this.uptimeMillis,
    currentPosition: Offset = this.position,
    currentPressed: Boolean = this.pressed,
    previousTime: Long = this.previousUptimeMillis,
    previousPosition: Offset = this.previousPosition,
    previousPressed: Boolean = this.previousPressed,
    type: PointerType = this.type,
    scrollDelta: Offset = this.scrollDelta
): PointerInputChange

Make a shallow copy of the PointerInputChange

NOTE: Due to the need of the inner contract of the PointerInputChange, this method performs a shallow copy of the PointerInputChange. Any consume call between any of the copies will consume any other copy automatically. Therefore, copy with the new isConsumed is not possible. Consider creating a new PointerInputChange

copy

Cmn 
fun copy(
    id: PointerId = this.id,
    currentTime: Long = this.uptimeMillis,
    currentPosition: Offset = this.position,
    currentPressed: Boolean = this.pressed,
    pressure: Float = this.pressure,
    previousTime: Long = this.previousUptimeMillis,
    previousPosition: Offset = this.previousPosition,
    previousPressed: Boolean = this.previousPressed,
    type: PointerType = this.type,
    scrollDelta: Offset = this.scrollDelta
): PointerInputChange

Make a shallow copy of the PointerInputChange

NOTE: Due to the need of the inner contract of the PointerInputChange, this method performs a shallow copy of the PointerInputChange. Any consume call between any of the copies will consume any other copy automatically. Therefore, copy with the new isConsumed is not possible. Consider creating a new PointerInputChange.

copy

Cmn 
fun copy(
    id: PointerId = this.id,
    currentTime: Long = this.uptimeMillis,
    currentPosition: Offset = this.position,
    currentPressed: Boolean = this.pressed,
    previousTime: Long = this.previousUptimeMillis,
    previousPosition: Offset = this.previousPosition,
    previousPressed: Boolean = this.previousPressed,
    consumed: ConsumedData,
    type: PointerType = this.type,
    scrollDelta: Offset = this.scrollDelta
): PointerInputChange

copy

Cmn 
@ExperimentalComposeUiApi
fun copy(
    id: PointerId = this.id,
    currentTime: Long = this.uptimeMillis,
    currentPosition: Offset = this.position,
    currentPressed: Boolean = this.pressed,
    previousTime: Long = this.previousUptimeMillis,
    previousPosition: Offset = this.previousPosition,
    previousPressed: Boolean = this.previousPressed,
    type: PointerType = this.type,
    historical: List<HistoricalChange>,
    scrollDelta: Offset = this.scrollDelta
): PointerInputChange

Make a shallow copy of the PointerInputChange

NOTE: Due to the need of the inner contract of the PointerInputChange, this method performs a shallow copy of the PointerInputChange. Any consume call between any of the copies will consume any other copy automatically. Therefore, copy with the new isConsumed is not possible. Consider creating a new PointerInputChange.

copy

Cmn 
fun copy(
    id: PointerId = this.id,
    currentTime: Long = this.uptimeMillis,
    currentPosition: Offset = this.position,
    currentPressed: Boolean = this.pressed,
    pressure: Float = this.pressure,
    previousTime: Long = this.previousUptimeMillis,
    previousPosition: Offset = this.previousPosition,
    previousPressed: Boolean = this.previousPressed,
    type: PointerType = this.type,
    historical: List<HistoricalChange> = this.historical,
    scrollDelta: Offset = this.scrollDelta
): PointerInputChange

Make a shallow copy of the PointerInputChange

NOTE: Due to the need of the inner contract of the PointerInputChange, this method performs a shallow copy of the PointerInputChange. Any consume call between any of the copies will consume any other copy automatically. Therefore, copy with the new isConsumed is not possible. Consider creating a new PointerInputChange.

toString

Cmn 
open fun toString(): String

Public properties

consumed

Cmn
Added in 1.0.0
Deprecated in 1.2.0
val consumed: ConsumedData

historical

Cmn
Added in 1.1.0
val historical: List<HistoricalChange>

Optional high-frequency pointer moves in between the last two dispatched events. Can be used for extra accuracy when touchscreen rate exceeds framerate.

id

Cmn
Added in 1.0.0
val id: PointerId

The unique id of the pointer associated with this PointerInputChange.

isConsumed

Cmn
Added in 1.1.0
val isConsumed: Boolean

Indicates whether the change was consumed or not. Note that the change must be consumed in full as there's no partial consumption system provided.

position

Cmn
Added in 1.0.0
val position: Offset

The Offset of the current pointer event, relative to the containing element (values can be negative or larger than the element bounds).

pressed

Cmn
Added in 1.0.0
val pressed: Boolean

true if the pointer event is considered "pressed." For example, finger touching the screen or a mouse button is pressed pressed would be true.

pressure

Cmn
Added in 1.3.0
val pressure: Float

The pressure of the of the pointer event

previousPosition

Cmn
Added in 1.0.0
val previousPosition: Offset

The Offset of the previous pointer event, offset to the position and relative to the containing element.

previousPressed

Cmn
Added in 1.0.0
val previousPressed: Boolean

true if the pointer event was considered "pressed." For example , if a finger was touching the screen or a mouse button was pressed, previousPressed would be true.

previousUptimeMillis

Cmn
Added in 1.0.0
val previousUptimeMillis: Long

The uptimeMillis of the previous pointer event

scrollDelta

Cmn
Added in 1.1.0
val scrollDelta: Offset

The amount of scroll wheel movement in the horizontal and vertical directions.

type

Cmn
Added in 1.0.0
val type: PointerType

The device type that produced the event, such as mouse, or touch.git

uptimeMillis

Cmn
Added in 1.0.0
val uptimeMillis: Long

The time of the current pointer event, in milliseconds. The start (0) time is platform-dependent

Extension functions

anyChangeConsumed

Cmn 
fun PointerInputChange.anyChangeConsumed(): Boolean

True if any aspect of this PointerInputChange has been consumed.

changedToDown

Cmn 
fun PointerInputChange.changedToDown(): Boolean

True if this PointerInputChange represents a pointer coming in contact with the screen and that change has not been consumed.

changedToDownIgnoreConsumed

Cmn 
fun PointerInputChange.changedToDownIgnoreConsumed(): Boolean

True if this PointerInputChange represents a pointer coming in contact with the screen, whether or not that change has been consumed.

changedToUp

Cmn 
fun PointerInputChange.changedToUp(): Boolean

True if this PointerInputChange represents a pointer breaking contact with the screen and that change has not been consumed.

changedToUpIgnoreConsumed

Cmn 
fun PointerInputChange.changedToUpIgnoreConsumed(): Boolean

True if this PointerInputChange represents a pointer breaking contact with the screen, whether or not that change has been consumed.

consumeAllChanges

Cmn 
fun PointerInputChange.consumeAllChanges(): Unit

Consumes all changes associated with the PointerInputChange

consumeDownChange

Cmn 
fun PointerInputChange.consumeDownChange(): Unit

Consume the up or down change of this PointerInputChange if there is an up or down change to consume.

consumePositionChange

Cmn 
fun PointerInputChange.consumePositionChange(): Unit

Consume position change if there is any

isOutOfBounds

Cmn 
fun PointerInputChange.isOutOfBounds(size: IntSize): Boolean

Returns true if the pointer has moved outside of the region of (0, 0, size.width, size.height) or false if the current pointer is up or it is inside the given bounds.

isOutOfBounds

Cmn 
fun PointerInputChange.isOutOfBounds(
    size: IntSize,
    extendedTouchPadding: Size
): Boolean

Returns true if the pointer has moved outside of the pointer region. For Touch events, this is (-extendedTouchPadding.width, -extendedTouchPadding.height, size.width + extendedTouchPadding.width, size.height + extendedTouchPadding.height) and for other events, this is (0, 0, size.width, size.height). Returnsfalse if the current pointer is up or it is inside the pointer region.

positionChange

Cmn 
fun PointerInputChange.positionChange(): Offset

The distance that the pointer has moved on the screen minus any distance that has been consumed.

positionChangeConsumed

Cmn 
fun PointerInputChange.positionChangeConsumed(): Boolean

True if this PointerInputChange's movement has been consumed.

positionChangeIgnoreConsumed

Cmn 
fun PointerInputChange.positionChangeIgnoreConsumed(): Offset

The distance that the pointer has moved on the screen, ignoring the fact that it might have been consumed.

positionChanged

Cmn 
fun PointerInputChange.positionChanged(): Boolean

True if this PointerInputChange represents a pointer moving on the screen and some of that movement has not been consumed.

positionChangedIgnoreConsumed

Cmn 
fun PointerInputChange.positionChangedIgnoreConsumed(): Boolean

True if this PointerInputChange represents a pointer moving on the screen ignoring how much of that movement may have been consumed.