SheetState
-
Cmn
@ExperimentalMaterial3Api
class SheetState
State of a sheet composable, such as ModalBottomSheet
Contains states relating to its swipe position as well as animations between state values.
Summary
Public companion functions |
||
|---|---|---|
Saver<SheetState, SheetValue> |
Saver(The default |
Cmn
|
Public constructors |
|
|---|---|
SheetState( |
Cmn
|
Public functions |
||
|---|---|---|
suspend Unit |
expand()Fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled. |
Cmn
|
suspend Unit |
hide()Hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled. |
Cmn
|
suspend Unit |
Animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled. |
Cmn
|
Float |
Require the current offset (in pixels) of the bottom sheet. |
Cmn
|
suspend Unit |
show()Expand the bottom sheet with animation and suspend until it is |
Cmn
|
Public properties |
||
|---|---|---|
SheetValue |
The current value of the state. |
Cmn
|
Boolean |
Whether the sheet has an expanded state defined. |
Cmn
|
Boolean |
Whether the modal bottom sheet has a partially expanded state defined. |
Cmn
|
Boolean |
Whether an expanding or collapsing sheet animation is currently in progress. |
Cmn
|
Boolean |
Whether the modal bottom sheet is visible. |
Cmn
|
SheetValue |
The target value of the bottom sheet state. |
Cmn
|
Public companion functions
Saver
fun Saver(
skipPartiallyExpanded: Boolean,
positionalThreshold: () -> Float,
velocityThreshold: () -> Float,
confirmValueChange: (SheetValue) -> Boolean,
skipHiddenState: Boolean
): Saver<SheetState, SheetValue>
The default Saver implementation for SheetState.
Public constructors
SheetState
SheetState(
skipPartiallyExpanded: Boolean,
positionalThreshold: () -> Float,
velocityThreshold: () -> Float,
initialValue: SheetValue = Hidden,
confirmValueChange: (SheetValue) -> Boolean = { true },
skipHiddenState: Boolean = false
)
| Parameters | |
|---|---|
skipPartiallyExpanded: Boolean |
Whether the partially expanded state, if the sheet is large enough, should be skipped. If true, the sheet will always expand to the |
positionalThreshold: () -> Float |
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: () -> Float |
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 |
initialValue: SheetValue = Hidden |
The initial value of the state. |
confirmValueChange: (SheetValue) -> Boolean = { true } |
Optional callback invoked to confirm or veto a pending state change. |
skipHiddenState: Boolean = false |
Whether the hidden state should be skipped. If true, the sheet will always expand to the |
Public functions
expand
suspend fun expand(): Unit
Fully expand the bottom sheet with animation and suspend until it is fully expanded or animation has been cancelled.
| Throws | |
|---|---|
kotlinx.coroutines.CancellationException |
if the animation is interrupted |
hide
suspend fun hide(): Unit
Hide the bottom sheet with animation and suspend until it is fully hidden or animation has been cancelled.
| Throws | |
|---|---|
kotlinx.coroutines.CancellationException |
if the animation is interrupted |
partialExpand
suspend fun partialExpand(): Unit
Animate the bottom sheet and suspend until it is partially expanded or animation has been cancelled.
| Throws | |
|---|---|
kotlinx.coroutines.CancellationException |
if the animation is interrupted |
kotlin.IllegalStateException |
if |
requireOffset
fun requireOffset(): Float
Require the current offset (in pixels) of the bottom sheet.
The offset will be initialized during the first measurement phase of the provided sheet content.
These are the phases: Composition { -> Effects } -> Layout { Measurement -> Placement } -> Drawing
During the first composition, an IllegalStateException is thrown. In subsequent compositions, the offset will be derived from the anchors of the previous pass. Always prefer accessing the offset from a LaunchedEffect as it will be scheduled to be executed the next frame, after layout.
| Throws | |
|---|---|
kotlin.IllegalStateException |
If the offset has not been initialized yet |
show
suspend fun show(): Unit
Expand the bottom sheet with animation and suspend until it is PartiallyExpanded if defined else Expanded.
| Throws | |
|---|---|
kotlinx.coroutines.CancellationException |
if the animation is interrupted |
Public properties
currentValue
val currentValue: SheetValue
The current value of the state.
If no swipe or animation is in progress, this corresponds to the state the bottom sheet is currently in. If a swipe or an animation is in progress, this corresponds the state the sheet was in before the swipe or animation started.
hasPartiallyExpandedState
val hasPartiallyExpandedState: Boolean
Whether the modal bottom sheet has a partially expanded state defined.
isAnimationRunning
val isAnimationRunning: Boolean
Whether an expanding or collapsing sheet animation is currently in progress.
See expand, partialExpand, show or hide for more information.
targetValue
val targetValue: SheetValue
The target value of the bottom sheet state.
If a swipe is in progress, this is the value that the sheet would animate to if the swipe finishes. If an animation is running, this is the target value of that animation. Finally, if no swipe or animation is in progress, this is the same as the currentValue.