core/com.composables.core.androidx.compose.foundation.gestures/UnstyledAnchoredDraggableState

UnstyledAnchoredDraggableState

class UnstyledAnchoredDraggableState<T>(initialValue: T, positionalThreshold: (totalDistance: Float) -> Float, velocityThreshold: () -> Float, val snapAnimationSpec: AnimationSpec<Float>, val decayAnimationSpec: DecayAnimationSpec<Float>, confirmValueChange: (newValue: T) -> Boolean = { true })

State of the unstyledAnchoredDraggable modifier. Use the constructor overload with anchors if the anchors are defined in composition, or update the anchors using updateAnchors.

This contains necessary information about any ongoing drag or animation and provides methods to change the state either immediately or by starting an animation.

Parameters

initialValue

The initial value of the state.

positionalThreshold

The positional threshold, in px, to be used when calculating the target state while a drag is in progress and when settling after the drag ends. This is the distance from the start of a transition. It will be, depending on the direction of the interaction, added or subtracted from/to the origin offset. It should always be a positive value.

velocityThreshold

The velocity threshold (in px per second) that the end velocity has to exceed in order to animate to the next state, even if the positionalThreshold has not been reached.

snapAnimationSpec

The default animation spec that will be used to animate to a new state.

decayAnimationSpec

The animation spec that will be used when flinging with a large enough velocity to reach or cross the target state.

confirmValueChange

Optional callback invoked to confirm or veto a pending state change.

Constructors

UnstyledAnchoredDraggableState

constructor(initialValue: T, anchors: UnstyledDraggableAnchors<T>, positionalThreshold: (totalDistance: Float) -> Float, velocityThreshold: () -> Float, snapAnimationSpec: AnimationSpec<Float>, decayAnimationSpec: DecayAnimationSpec<Float>, confirmValueChange: (newValue: T) -> Boolean = { true })

Construct an UnstyledAnchoredDraggableState instance with anchors.

constructor(initialValue: T, positionalThreshold: (totalDistance: Float) -> Float, velocityThreshold: () -> Float, snapAnimationSpec: AnimationSpec<Float>, decayAnimationSpec: DecayAnimationSpec<Float>, confirmValueChange: (newValue: T) -> Boolean = { true })

Types

Companion

object Companion

Properties

anchors

var anchors: UnstyledDraggableAnchors<T>

currentValue

var currentValue: T

The current value of the UnstyledAnchoredDraggableState.

decayAnimationSpec

val decayAnimationSpec: DecayAnimationSpec<Float>

isAnimationRunning

val isAnimationRunning: Boolean

Whether an animation is currently in progress.

lastVelocity

var lastVelocity: Float

The velocity of the last known animation. Gets reset to 0f when an animation completes successfully, but does not get reset when an animation gets interrupted. You can use this value to provide smooth reconciliation behavior when re-targeting an animation.

offset

var offset: Float

The current offset, or Float.NaN if it has not been initialized yet.

progress

@get:FloatRange(from = 0.0, to = 1.0)

val ~~progress~~: Float

The fraction of the progress going from settledValue to targetValue, within 0f..1f bounds, or 1f if the UnstyledAnchoredDraggableState is in a settled state.

settledValue

var settledValue: T

The value the UnstyledAnchoredDraggableState is currently settled at.

snapAnimationSpec

val snapAnimationSpec: AnimationSpec<Float>

targetValue

val targetValue: T

The target value. This is the closest value to the current offset. If no interactions like animations or drags are in progress, this will be the current value.

Functions

anchoredDrag

suspend fun anchoredDrag(dragPriority: MutatePriority = MutatePriority.Default, block: suspend AnchoredDragScope.(anchors: UnstyledDraggableAnchors<T>) -> Unit)

Call this function to take control of drag logic and perform anchored drag with the latest anchors.

suspend fun anchoredDrag(targetValue: T, dragPriority: MutatePriority = MutatePriority.Default, block: suspend AnchoredDragScope.(anchor: UnstyledDraggableAnchors<T>, targetValue: T) -> Unit)

Call this function to take control of drag logic and perform anchored drag with the latest anchors and target.

animateTo

suspend fun <T> UnstyledAnchoredDraggableState<T>.animateTo(targetValue: T)

Animate to a targetValue. If the targetValue is not in the set of anchors, the UnstyledAnchoredDraggableState.currentValue will be updated to the targetValue without updating the offset.

animateToWithDecay

suspend fun <T> UnstyledAnchoredDraggableState<T>.animateToWithDecay(targetValue: T, velocity: Float): Float

Attempt to animate using decay Animation to a targetValue. If the velocity is high enough to get to the target offset, we'll use UnstyledAnchoredDraggableState.decayAnimationSpec to get to that offset and return the consumed velocity. If the velocity is not high enough, we'll use UnstyledAnchoredDraggableState.snapAnimationSpec to reach the target offset.

dispatchRawDelta

fun dispatchRawDelta(delta: Float): Float

Drag by the delta, coerce it in the bounds and dispatch it to the UnstyledAnchoredDraggableState.

progress

@FloatRange(from = 0.0, to = 1.0)

fun progress(from: T, to: T): Float

The fraction of the offset between from and to, as a fraction between 0f..1f, or 1f if from is equal to to.

requireOffset

fun requireOffset(): Float

Require the current offset.

settle

suspend fun settle(velocity: Float): Float

Find the closest anchor, taking into account the velocityThreshold and positionalThreshold, and settle at it with an animation.

snapTo

suspend fun <T> UnstyledAnchoredDraggableState<T>.snapTo(targetValue: T)

Snap to a targetValue without any animation. If the targetValue is not in the set of anchors, the UnstyledAnchoredDraggableState.currentValue will be updated to the targetValue without updating the offset.

updateAnchors

fun updateAnchors(newAnchors: UnstyledDraggableAnchors<T>, newTarget: T = if (!offset.isNaN()) { newAnchors.closestAnchor(offset) ?: targetValue } else targetValue)

Update the anchors. If there is no ongoing anchoredDrag operation, snap to the newTarget, otherwise restart the ongoing anchoredDrag operation (e.g. an animation) with the new anchors.