Interaction¶
The touch physics behind Button, Slider, and Toggle, exposed so custom components can feel
the same. Everything lives in framework.cortena.ui.interaction in the ui artifact.
Concept¶
Every touchable CortenaUI component is built from the same four pieces:
InteractiveHighlightdrives tap surfaces such asButton. It tracks the press and the finger, and draws a tint plus a glow that follows the finger.DampedAnimationdrives draggable values such as theSliderthumb and theToggleknob. It runs spring tracks for the value, its velocity, the press progress, and the press scale.applyInteractiveAnimationturns either source into motion insidegraphicsLayer: the element grows while pressed, follows the finger with a soft pull, and stretches along the drag.inspectDragGesturesis the gesture detector under both. It reports the press immediately instead of waiting for touch slop.
All per-frame values are plain Float and Offset reads backed by Compose state. Read them inside
graphicsLayer or a draw block so the animation never recomposes.
The springs inside DampedAnimation and InteractiveHighlight are tuned per track and do not read
LocalMotion. This is the one documented exception to the Motion rule.
API Reference¶
expect class InteractiveHighlight(
animationScope: CoroutineScope,
color: Color = Color.Unspecified,
position: (size: Size, offset: Offset) -> Offset = { _, offset -> offset },
) {
val pressProgress: Float
val offset: Offset
val modifier: Modifier
val gestureModifier: Modifier
}
class DampedAnimation(
animationScope: CoroutineScope,
val initialValue: Float,
val valueRange: ClosedRange<Float>,
val visibilityThreshold: Float,
val initialScale: Float,
val pressedScale: Float,
val onDragStarted: DampedAnimation.(position: Offset) -> Unit,
val onDragStopped: DampedAnimation.() -> Unit,
val onDrag: DampedAnimation.(size: IntSize, dragAmount: Offset) -> Unit,
) {
val value: Float
val progress: Float
val targetValue: Float
val pressProgress: Float
val scaleX: Float
val scaleY: Float
val velocity: Float
val modifier: Modifier
fun press()
fun release()
fun updateValue(value: Float)
}
fun GraphicsLayerScope.applyInteractiveAnimation(
pressProgress: Float,
offset: Offset,
baseTranslationX: Float = 0f,
baseTranslationY: Float = 0f,
scaleXMultiplier: Float = 1f,
scaleYMultiplier: Float = 1f,
)
suspend fun PointerInputScope.inspectDragGestures(
onDragStart: (down: PointerInputChange) -> Unit = {},
onDragEnd: (change: PointerInputChange) -> Unit = {},
onDragCancel: () -> Unit = {},
onDrag: (change: PointerInputChange, dragAmount: Offset) -> Unit,
)
Create InteractiveHighlight and DampedAnimation in remember(animationScope) with a scope
from rememberCoroutineScope(). The scope carries the frame clock the springs need.
InteractiveHighlight¶
| Parameter / member | Type | Description |
|---|---|---|
animationScope |
CoroutineScope |
Runs the animations. |
color |
Color |
Surface color under the highlight. Dark colors get a lighter highlight, very light colors a darker one. Unspecified is gray. |
position |
(Size, Offset) -> Offset |
Maps the element size and the pointer position to the glow center. Defaults to the pointer position. |
pressProgress |
Float |
0 at rest, 1 while pressed. |
offset |
Offset |
Drag distance from the press origin in pixels. |
gestureModifier |
Modifier |
Tracks presses and drags. Leave it off while disabled. |
modifier |
Modifier |
Draws the tint and the glow. Place it after the clip so the glow stays inside the shape. |
On Android the glow is an AGSL RuntimeShader.
DampedAnimation¶
| Parameter / member | Type | Description |
|---|---|---|
initialValue |
Float |
Starting value, inside valueRange. |
valueRange |
ClosedRange<Float> |
Range that updateValue clamps to and that progress maps to 0..1. |
visibilityThreshold |
Float |
Smallest value change worth animating. |
initialScale |
Float |
Scale at rest. |
pressedScale |
Float |
Scale while pressed. |
onDragStarted |
(Offset) -> Unit |
Called by modifier when a press starts, with the touch position. |
onDragStopped |
() -> Unit |
Called by modifier when the press ends or is canceled. |
onDrag |
(IntSize, Offset) -> Unit |
Called by modifier for every move, with the size of the element that carries modifier and the delta. |
value |
Float |
Current animated value. |
progress |
Float |
value as a fraction of valueRange. |
targetValue |
Float |
Value the spring is heading to. |
pressProgress |
Float |
0 at rest, 1 while pressed. |
scaleX, scaleY |
Float |
Press scale per axis. The axes settle at different rates, which gives the squash. |
velocity |
Float |
Smoothed speed of value in range widths per second. |
modifier |
Modifier |
Optional pointer input that calls the three callbacks and runs press and release. |
press() |
— | Animates pressProgress to 1 and the scales to pressedScale. |
release() |
— | Animates back to rest, after value is within 2.5% of the range from its target. |
updateValue(value) |
— | Springs toward value, clamped to valueRange. |
The callbacks are captured once. Read changing values inside them through rememberUpdatedState.
applyInteractiveAnimation¶
| Parameter | Type | Description |
|---|---|---|
pressProgress |
Float |
0 at rest, 1 fully pressed. |
offset |
Offset |
Drag distance from the press origin in pixels. Offset.Zero gives no pull or stretch. |
baseTranslationX, baseTranslationY |
Float |
Translation in pixels that the pull is added to, for elements that already move. |
scaleXMultiplier, scaleYMultiplier |
Float |
Extra scale per axis, such as DampedAnimation.scaleX and scaleY. |
Fully pressed, the element grows by 4dp of its height, and its width grows by at most 4dp × φ²
(about 10.5dp). The cap keeps wide surfaces, such as a full-width tile, growing about as much as a
Button instead of scaling with their width.
inspectDragGestures¶
onDragStart fires on the first down. onDrag then fires once with Offset.Zero and again for
every move, and onDragEnd fires when the last pointer lifts. If the pointer is lost or another
handler consumes a move first, onDragCancel fires instead. Every move reported to onDrag is
consumed.
Examples¶
For most tap surfaces, Pressable wires all of this for you. Use the pieces directly when you need a different layout of the same physics. Build Your Own Component walks through a full component on each layer.
A tappable chip with the same press feel as Button, built by hand:
@Composable
fun Chip(label: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
val colors = LocalColors.current
val spacing = LocalSpacing.current
val background = Color(colors.surfaceVariant)
val animationScope = rememberCoroutineScope()
val highlight =
remember(animationScope) {
InteractiveHighlight(animationScope = animationScope, color = background)
}
Box(
modifier
.graphicsLayer {
applyInteractiveAnimation(
pressProgress = highlight.pressProgress,
offset = highlight.offset,
)
}
.clip(CapsuleShape())
.background(background)
.then(highlight.gestureModifier)
.clickable(
interactionSource = null,
indication = null,
role = Role.Button,
onClick = onClick,
)
.then(highlight.modifier)
.padding(horizontal = spacing.Md.dp, vertical = spacing.Sm.dp)
) {
Text(label)
}
}
A knob that springs along a track and snaps to the nearest end on release, built by hand. DragTrack handles this track-and-thumb layout for you:
@Composable
fun SnapKnob(modifier: Modifier = Modifier) {
val colors = LocalColors.current
val size = LocalSizeToken.current
val travel = size.toggleTrackWidth - size.toggleTrackHeight
val animationScope = rememberCoroutineScope()
val knob =
remember(animationScope) {
DampedAnimation(
animationScope = animationScope,
initialValue = 0f,
valueRange = 0f..1f,
visibilityThreshold = 0.001f,
initialScale = 1f,
pressedScale = 1.3f,
onDragStarted = {},
onDragStopped = { updateValue(if (targetValue > 0.5f) 1f else 0f) },
onDrag = { trackSize, dragAmount ->
updateValue(targetValue + dragAmount.x / trackSize.width)
},
)
}
// The track carries knob.modifier, so onDrag receives the track size. LTR only, for brevity.
Box(
modifier
.size(size.toggleTrackWidth, size.toggleTrackHeight)
.background(Color(colors.surfaceVariant), CapsuleShape())
.then(knob.modifier)
) {
Box(
Modifier.size(size.toggleTrackHeight)
.graphicsLayer {
applyInteractiveAnimation(
pressProgress = knob.pressProgress,
offset = Offset.Zero,
baseTranslationX = knob.progress * travel.toPx(),
scaleXMultiplier = knob.scaleX,
scaleYMultiplier = knob.scaleY,
)
}
.background(Color(colors.primary), CapsuleShape())
)
}
}