ColumnScope
-
Cmn
@LayoutScopeMarker
interface ColumnScope
ContextualFlowColumnScope |
Provides a scope for items within a |
FlowColumnScope |
Scope for the children of |
ContextualFlowColumnOverflowScope |
Scope for the overflow |
FlowColumnOverflowScope |
Scope for the overflow |
Scope for the children of Column.
Summary
Public functions |
||
|---|---|---|
Modifier |
Modifier.align(alignment: Alignment.Horizontal)Align the element horizontally within the |
Cmn
|
Modifier |
Position the element horizontally such that the alignment line for the content as determined by |
Cmn
|
Modifier |
Modifier.alignBy(alignmentLine: VerticalAlignmentLine)Position the element horizontally such that its |
Cmn
|
Modifier |
Modifier.weight(Size the element's height proportional to its |
Cmn
|
Extension functions |
||
|---|---|---|
Unit |
@Composable
|
Cmn
|
Unit |
@Composable
|
Cmn
|
Public functions
align
fun Modifier.align(alignment: Alignment.Horizontal): Modifier
Align the element horizontally within the Column. This alignment will have priority over the Column's horizontalAlignment parameter.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
Column(Modifier.fillMaxWidth()) {
// The child with no align modifier is positioned by default so that its start edge
// aligned with the start edge of the horizontal axis.
Box(Modifier.size(80.dp, 40.dp).background(Color.Magenta))
// Alignment.Start, the child will be positioned so that its start edge is aligned with
// the start edge of the horizontal axis.
Box(Modifier.size(80.dp, 40.dp).align(Alignment.Start).background(Color.Red))
// Alignment.Center, the child will be positioned so that its center is in the middle of
// the horizontal axis.
Box(
Modifier.size(80.dp, 40.dp).align(Alignment.CenterHorizontally).background(Color.Yellow)
)
// Alignment.End, the child will be positioned so that its end edge aligned to the end of
// the horizontal axis.
Box(Modifier.size(80.dp, 40.dp).align(Alignment.End).background(Color.Green))
}
alignBy
fun Modifier.alignBy(alignmentLineBlock: (Measured) -> Int): Modifier
Position the element horizontally such that the alignment line for the content as determined by alignmentLineBlock aligns with sibling elements also configured to alignBy. alignBy is a form of align, so both modifiers will not work together if specified for the same layout. Within a Column, all components with alignBy will align horizontally using the specified VerticalAlignmentLines or values obtained from alignmentLineBlock, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Start align in Column, and the alignment of the other siblings will be then determined such that the alignment lines coincide. Note that if only one element in a Column has the alignBy modifier specified the element will be positioned as if it had Alignment.Start align.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
Column {
// Center of the first rectangle is aligned to the right edge of the second rectangle and
// left edge of the third one.
Box(Modifier.size(80.dp, 40.dp).alignBy { it.measuredWidth / 2 }.background(Color.Blue))
Box(Modifier.size(80.dp, 40.dp).alignBy { it.measuredWidth }.background(Color.Magenta))
Box(Modifier.size(80.dp, 40.dp).alignBy { 0 }.background(Color.Red))
}
alignBy
fun Modifier.alignBy(alignmentLine: VerticalAlignmentLine): Modifier
Position the element horizontally such that its alignmentLine aligns with sibling elements also configured to alignBy. alignBy is a form of align, so both modifiers will not work together if specified for the same layout. Within a Column, all components with alignBy will align horizontally using the specified VerticalAlignmentLines or values provided using the other alignBy overload, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Start align in Column, and the alignment of the other siblings will be then determined such that the alignment lines coincide. Note that if only one element in a Column has the alignBy modifier specified the element will be positioned as if it had Alignment.Start align.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.Layout
import androidx.compose.ui.layout.VerticalAlignmentLine
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
// Alignment lines provided by the RectangleWithStartEnd layout. We need to create these
// local alignment lines because Compose is currently not providing any top-level out of
// the box vertical alignment lines. Two horizontal alignment lines are provided though:
// FirstBaseline and LastBaseline, but these can only be used to align vertically children
// of Row because the baselines are horizontal. Therefore, we create these vertical alignment
// lines, that refer to the start and end of the RectangleWithStartEnd layout which knows
// how to provide them. Then Column will know how to align horizontally children such
// that the positions of the alignment lines coincide, as asked by alignBy.
val start = VerticalAlignmentLine(::min)
val end = VerticalAlignmentLine(::min)
@Composable
fun RectangleWithStartEnd(modifier: Modifier = Modifier, color: Color, width: Dp, height: Dp) {
Layout(content = {}, modifier = modifier.background(color = color)) { _, constraints ->
val widthPx = max(width.roundToPx(), constraints.minWidth)
val heightPx = max(height.roundToPx(), constraints.minHeight)
layout(widthPx, heightPx, mapOf(start to 0, end to widthPx)) {}
}
}
Column {
// Center of the first rectangle is aligned to the right edge of the second rectangle and
// left edge of the third one.
Box(Modifier.size(80.dp, 40.dp).alignBy { it.measuredWidth / 2 }.background(Color.Blue))
RectangleWithStartEnd(
Modifier.alignBy(end),
color = Color.Magenta,
width = 80.dp,
height = 40.dp
)
RectangleWithStartEnd(
Modifier.alignBy(start),
color = Color.Red,
width = 80.dp,
height = 40.dp
)
}
weight
fun Modifier.weight(
weight: @FloatRange(from = 0.0, fromInclusive = false) Float,
fill: Boolean = true
): Modifier
Size the element's height proportional to its weight relative to other weighted sibling elements in the Column. The parent will divide the vertical space remaining after measuring unweighted child elements and distribute it according to this weight. When fill is true, the element will be forced to occupy the whole height allocated to it. Otherwise, the element is allowed to be smaller - this will result in Column being smaller, as the unused allocated height will not be redistributed to other siblings.
In a FlowColumn, when a weight is applied to an item, the item is scaled based on the number of weighted items that fall on the column it was placed in.
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
Column {
// The child with no weight will have the specified size.
Box(Modifier.size(40.dp, 80.dp).background(Color.Magenta))
// Has weight, the child will occupy half of the remaining height.
Box(Modifier.width(40.dp).weight(1f).background(Color.Yellow))
// Has weight and does not fill, the child will occupy at most half of the remaining height.
// Therefore it will occupy 80.dp (its preferred height) if the assigned height is larger.
Box(Modifier.size(40.dp, 80.dp).weight(1f, fill = false).background(Color.Green))
}
| Parameters | |
|---|---|
weight: @FloatRange(from = 0.0, fromInclusive = false) Float |
The proportional height to give to this element, as related to the total of all weighted siblings. Must be positive. |
fill: Boolean = true |
When |
Extension functions
AnimatedVisibility
@Composable
fun ColumnScope.AnimatedVisibility(
visible: Boolean,
modifier: Modifier = Modifier,
enter: EnterTransition = fadeIn() + expandVertically(),
exit: ExitTransition = fadeOut() + shrinkVertically(),
label: String = "AnimatedVisibility",
content: @Composable AnimatedVisibilityScope.() -> Unit
): Unit
ColumnScope.AnimatedVisibility composable animates the appearance and disappearance of its content when the AnimatedVisibility is in a Column. The default animations are tailored specific to the Column layout. See more details below.
Different EnterTransitions and ExitTransitions can be defined in enter and exit for the appearance and disappearance animation. There are 4 types of EnterTransition and ExitTransition: Fade, Expand/Shrink, Scale and Slide. The enter transitions can be combined using +. Same for exit transitions. The order of the combination does not matter, as the transition animations will start simultaneously. See EnterTransition and ExitTransition for details on the three types of transition.
The default enter and exit transition is configured based on the vertical layout of a Column. enter defaults to a combination of fading in and expanding the content vertically. (The bottom of the content will be the leading edge as the content expands to its full height.) And the exit defaults to shrinking the content vertically with the bottom of the content being the leading edge while fading out. The expanding and shrinking will likely also animate the parent and siblings in the column since they rely on the size of appearing/disappearing content.
Aside from these three types of EnterTransition and ExitTransition, AnimatedVisibility also supports custom enter/exit animations. Some use cases may benefit from custom enter/exit animations on shape, scale, color, etc. Custom enter/exit animations can be created using the Transition<EnterExitState> object from the AnimatedVisibilityScope (i.e. AnimatedVisibilityScope.transition). See EnterExitState for an example of custom animations. These custom animations will be running along side of the built-in animations specified in enter and exit. In cases where the enter/exit animation needs to be completely customized, enter and/or exit can be specified as EnterTransition.None and/or ExitTransition.None as needed. AnimatedVisibility will wait until all of enter/exit animations to finish before it considers itself idle. content will only be removed after all the (built-in and custom) exit animations have finished.
AnimatedVisibility creates a custom Layout for its content. The size of the custom layout is determined by the largest width and largest height of the children. All children will be aligned to the top start of the Layout.
Note: Once the exit transition is finished, the content composable will be removed from the tree, and disposed. If there's a need to observe the state change of the enter/exit transition and follow up additional action (e.g. remove data, sequential animation, etc), consider the AnimatedVisibility API variant that takes a MutableTransitionState parameter.
Here's an example of using ColumnScope.AnimatedVisibility in a Column:
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ColumnScope
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
var itemIndex by remember { mutableStateOf(0) }
val colors = listOf(Color.Red, Color.Green, Color.Blue)
Column(Modifier.fillMaxWidth().clickable { itemIndex = (itemIndex + 1) % colors.size }) {
colors.forEachIndexed { i, color ->
// By default ColumnScope.AnimatedVisibility expands and shrinks new content while
// fading.
AnimatedVisibility(i <= itemIndex) {
Box(Modifier.requiredHeight(40.dp).fillMaxWidth().background(color))
}
}
}
| Parameters | |
|---|---|
visible: Boolean |
defines whether the content should be visible |
modifier: Modifier = Modifier |
|
enter: EnterTransition = fadeIn() + expandVertically() |
EnterTransition(s) used for the appearing animation, fading in while expanding vertically by default |
exit: ExitTransition = fadeOut() + shrinkVertically() |
ExitTransition(s) used for the disappearing animation, fading out while shrinking vertically by default |
content: @Composable AnimatedVisibilityScope.() -> Unit |
Content to appear or disappear based on the value of |
AnimatedVisibility
@Composable
fun ColumnScope.AnimatedVisibility(
visibleState: MutableTransitionState<Boolean>,
modifier: Modifier = Modifier,
enter: EnterTransition = expandVertically() + fadeIn(),
exit: ExitTransition = shrinkVertically() + fadeOut(),
label: String = "AnimatedVisibility",
content: @Composable AnimatedVisibilityScope.() -> Unit
): Unit
ColumnScope.AnimatedVisibility composable animates the appearance and disappearance of its content as visibleState's targetState changes. The default enter and exit transitions are tailored specific to the Column layout. See more details below. The visibleState can also be used to observe the state of AnimatedVisibility. For example: visibleState.isIdle indicates whether all the animations have finished in AnimatedVisibility, and visibleState.currentState returns the initial state of the current animations.
Different EnterTransitions and ExitTransitions can be defined in enter and exit for the appearance and disappearance animation. There are 4 types of EnterTransition and ExitTransition: Fade, Expand/Shrink, Scale and Slide. The enter transitions can be combined using +. Same for exit transitions. The order of the combination does not matter, as the transition animations will start simultaneously. See EnterTransition and ExitTransition for details on the three types of transition.
The default enter and exit transition is configured based on the vertical layout of a Column. enter defaults to a combination of fading in and expanding the content vertically. (The bottom of the content will be the leading edge as the content expands to its full height.) And the exit defaults to shrinking the content vertically with the bottom of the content being the leading edge while fading out. The expanding and shrinking will likely also animate the parent and siblings in the column since they rely on the size of appearing/disappearing content.
Aside from these three types of EnterTransition and ExitTransition, AnimatedVisibility also supports custom enter/exit animations. Some use cases may benefit from custom enter/exit animations on shape, scale, color, etc. Custom enter/exit animations can be created using the Transition<EnterExitState> object from the AnimatedVisibilityScope (i.e. AnimatedVisibilityScope.transition). See EnterExitState for an example of custom animations. These custom animations will be running along side of the built-in animations specified in enter and exit. In cases where the enter/exit animation needs to be completely customized, enter and/or exit can be specified as EnterTransition.None and/or ExitTransition.None as needed. AnimatedVisibility will wait until all of enter/exit animations to finish before it considers itself idle. content will only be removed after all the (built-in and custom) exit animations have finished.
AnimatedVisibility creates a custom Layout for its content. The size of the custom layout is determined by the largest width and largest height of the children. All children will be aligned to the top start of the Layout.
Note: Once the exit transition is finished, the content composable will be removed from the tree, and disposed. Both currentState and targetState will be false for visibleState.
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.animation.core.MutableTransitionState
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
var visible by remember { mutableStateOf(true) }
val colors = remember { listOf(Color(0xff2a9d8f), Color(0xffe9c46a), Color(0xfff4a261)) }
Column {
repeat(3) {
AnimatedVisibility(
visibleState =
remember {
// This sets up the initial state of the AnimatedVisibility to false to
// guarantee an initial enter transition. In contrast, initializing this
// as
// `MutableTransitionState(visible)` would result in no initial enter
// transition.
MutableTransitionState(initialState = false)
}
.apply {
// This changes the target state of the visible state. If it's different
// than
// the initial state, an enter/exit transition will be triggered.
targetState = visible
},
) { // Content that needs to appear/disappear goes here:
Box(Modifier.fillMaxWidth().height(100.dp).background(colors[it]))
}
}
}
| Parameters | |
|---|---|
visibleState: MutableTransitionState<Boolean> |
defines whether the content should be visible |
modifier: Modifier = Modifier |
|
enter: EnterTransition = expandVertically() + fadeIn() |
EnterTransition(s) used for the appearing animation, fading in while expanding vertically by default |
exit: ExitTransition = shrinkVertically() + fadeOut() |
ExitTransition(s) used for the disappearing animation, fading out while shrinking vertically by default |
content: @Composable AnimatedVisibilityScope.() -> Unit |
Content to appear or disappear based on of |