RowScope
-
Cmn
@LayoutScopeMarker
interface RowScope
ContextualFlowRowScope |
Defines the scope for items within a |
FlowRowScope |
Scope for the children of |
MultiChoiceSegmentedButtonRowScope |
Scope for the children of a |
SingleChoiceSegmentedButtonRowScope |
Scope for the children of a |
ContextualFlowRowOverflowScope |
Scope for the overflow |
FlowRowOverflowScope |
Scope for the overflow |
Scope for the children of Row.
Summary
Public functions |
||
|---|---|---|
Modifier |
Modifier.align(alignment: Alignment.Vertical)Align the element vertically within the |
Cmn
|
Modifier |
Position the element vertically such that the alignment line for the content as determined by |
Cmn
|
Modifier |
Modifier.alignBy(alignmentLine: HorizontalAlignmentLine)Position the element vertically such that its |
Cmn
|
Modifier |
Position the element vertically such that its first baseline aligns with sibling elements also configured to |
Cmn
|
Modifier |
Modifier.weight(Size the element's width proportional to its |
Cmn
|
Extension functions |
||
|---|---|---|
Unit |
@Composable
|
Cmn
|
Unit |
@Composable
|
Cmn
|
Unit |
@Composable |
Cmn
|
Unit |
@ComposableMaterial Design navigation bar item. |
Cmn
|
Public functions
align
fun Modifier.align(alignment: Alignment.Vertical): Modifier
Align the element vertically within the Row. This alignment will have priority over the Row's verticalAlignment parameter.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
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
Row(Modifier.fillMaxHeight()) {
// The child with no align modifier is positioned by default so that its top edge is
// aligned to the top of the vertical axis.
Box(Modifier.size(80.dp, 40.dp).background(Color.Magenta))
// Gravity.Top, the child will be positioned so that its top edge is aligned to the top
// of the vertical axis.
Box(Modifier.size(80.dp, 40.dp).align(Alignment.Top).background(Color.Red))
// Gravity.Center, the child will be positioned so that its center is in the middle of
// the vertical axis.
Box(Modifier.size(80.dp, 40.dp).align(Alignment.CenterVertically).background(Color.Yellow))
// Gravity.Bottom, the child will be positioned so that its bottom edge is aligned to the
// bottom of the vertical axis.
Box(Modifier.size(80.dp, 40.dp).align(Alignment.Bottom).background(Color.Green))
}
alignBy
fun Modifier.alignBy(alignmentLineBlock: (Measured) -> Int): Modifier
Position the element vertically 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 Row, all components with alignBy will align vertically using the specified HorizontalAlignmentLines or values obtained from alignmentLineBlock, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Top align in Row, 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 Row has the alignBy modifier specified the element will be positioned as if it had Alignment.Top align.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.size
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
Row(Modifier.fillMaxHeight()) {
// The center of the magenta Box and the baselines of the two texts will be
// vertically aligned. Note that alignBy() or alignByBaseline() has to be specified
// for all children we want to take part in the alignment. For example, alignByBaseline()
// means that the baseline of the text should be aligned with the alignment line
// (possibly another baseline) specified for siblings using alignBy or alignByBaseline.
// If no other sibling had alignBy() or alignByBaseline(), the modifier would have no
// effect.
Box(
modifier =
Modifier.size(80.dp, 40.dp)
.alignBy { it.measuredHeight / 2 }
.background(Color.Magenta)
)
Text(
text = "Text 1",
fontSize = 40.sp,
modifier = Modifier.alignByBaseline().background(color = Color.Red)
)
Text(text = "Text 2", modifier = Modifier.alignByBaseline().background(color = Color.Cyan))
}
alignBy
fun Modifier.alignBy(alignmentLine: HorizontalAlignmentLine): Modifier
Position the element vertically 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. alignBy can be used to align two layouts by baseline inside a Row, using alignBy(FirstBaseline). Within a Row, all components with alignBy will align vertically using the specified HorizontalAlignmentLines 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.Top align in Row, 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 Row has the alignBy modifier specified the element will be positioned as if it had Alignment.Top align.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.size
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
Row(Modifier.fillMaxHeight()) {
// The center of the magenta Box and the baselines of the two texts will be
// vertically aligned. Note that alignBy() or alignByBaseline() has to be specified
// for all children we want to take part in the alignment. For example, alignByBaseline()
// means that the baseline of the text should be aligned with the alignment line
// (possibly another baseline) specified for siblings using alignBy or alignByBaseline.
// If no other sibling had alignBy() or alignByBaseline(), the modifier would have no
// effect.
Box(
modifier =
Modifier.size(80.dp, 40.dp)
.alignBy { it.measuredHeight / 2 }
.background(Color.Magenta)
)
Text(
text = "Text 1",
fontSize = 40.sp,
modifier = Modifier.alignByBaseline().background(color = Color.Red)
)
Text(text = "Text 2", modifier = Modifier.alignByBaseline().background(color = Color.Cyan))
}
| See also | |
|---|---|
alignByBaseline |
alignByBaseline
fun Modifier.alignByBaseline(): Modifier
Position the element vertically such that its first baseline aligns with sibling elements also configured to alignByBaseline or alignBy. This modifier is a form of align, so both modifiers will not work together if specified for the same layout. alignByBaseline is a particular case of alignBy. See alignBy for more details.
Example usage:
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.size
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
Row(Modifier.fillMaxHeight()) {
// The center of the magenta Box and the baselines of the two texts will be
// vertically aligned. Note that alignBy() or alignByBaseline() has to be specified
// for all children we want to take part in the alignment. For example, alignByBaseline()
// means that the baseline of the text should be aligned with the alignment line
// (possibly another baseline) specified for siblings using alignBy or alignByBaseline.
// If no other sibling had alignBy() or alignByBaseline(), the modifier would have no
// effect.
Box(
modifier =
Modifier.size(80.dp, 40.dp)
.alignBy { it.measuredHeight / 2 }
.background(Color.Magenta)
)
Text(
text = "Text 1",
fontSize = 40.sp,
modifier = Modifier.alignByBaseline().background(color = Color.Red)
)
Text(text = "Text 2", modifier = Modifier.alignByBaseline().background(color = Color.Cyan))
}
| See also | |
|---|---|
alignBy |
weight
fun Modifier.weight(
weight: @FloatRange(from = 0.0, fromInclusive = false) Float,
fill: Boolean = true
): Modifier
Size the element's width proportional to its weight relative to other weighted sibling elements in the Row. The parent will divide the horizontal 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 width allocated to it. Otherwise, the element is allowed to be smaller - this will result in Row being smaller, as the unused allocated width will not be redistributed to other siblings.
| Parameters | |
|---|---|
weight: @FloatRange(from = 0.0, fromInclusive = false) Float |
The proportional width 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 RowScope.AnimatedVisibility(
visible: Boolean,
modifier: Modifier = Modifier,
enter: EnterTransition = fadeIn() + expandHorizontally(),
exit: ExitTransition = fadeOut() + shrinkHorizontally(),
label: String = "AnimatedVisibility",
content: @Composable AnimatedVisibilityScope.() -> Unit
): Unit
RowScope.AnimatedVisibility composable animates the appearance and disappearance of its content when the AnimatedVisibility is in a Row. The default animations are tailored specific to the Row 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 horizontal layout of a Row. enter defaults to a combination of fading in and expanding the content horizontally. (The end of the content will be the leading edge as the content expands to its full width.) And exit defaults to shrinking the content horizontally with the end of the content being the leading edge while fading out. The expanding and shrinking will likely also animate the parent and siblings in the row 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 RowScope.AnimatedVisibility in a Row:
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.material.Button
import androidx.compose.material.FloatingActionButton
import androidx.compose.material.Icon
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
var expanded by remember { mutableStateOf(true) }
FloatingActionButton(
onClick = { expanded = !expanded },
modifier = Modifier.align(Alignment.CenterHorizontally)
) {
Row(Modifier.padding(start = 12.dp, end = 12.dp)) {
Icon(
Icons.Default.Favorite,
contentDescription = "Favorite",
modifier = Modifier.align(Alignment.CenterVertically)
)
AnimatedVisibility(expanded, modifier = Modifier.align(Alignment.CenterVertically)) {
Text(modifier = Modifier.padding(start = 12.dp), text = "Favorite")
}
}
}
Spacer(Modifier.requiredHeight(20.dp))
| Parameters | |
|---|---|
visible: Boolean |
defines whether the content should be visible |
modifier: Modifier = Modifier |
|
enter: EnterTransition = fadeIn() + expandHorizontally() |
EnterTransition(s) used for the appearing animation, fading in while expanding horizontally by default |
exit: ExitTransition = fadeOut() + shrinkHorizontally() |
ExitTransition(s) used for the disappearing animation, fading out while shrinking horizontally by default |
content: @Composable AnimatedVisibilityScope.() -> Unit |
Content to appear or disappear based on the value of |
AnimatedVisibility
@Composable
fun RowScope.AnimatedVisibility(
visibleState: MutableTransitionState<Boolean>,
modifier: Modifier = Modifier,
enter: EnterTransition = expandHorizontally() + fadeIn(),
exit: ExitTransition = shrinkHorizontally() + fadeOut(),
label: String = "AnimatedVisibility",
content: @Composable AnimatedVisibilityScope.() -> Unit
): Unit
RowScope.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 Row 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 horizontal layout of a Row. enter defaults to a combination of fading in and expanding the content horizontally. (The end of the content will be the leading edge as the content expands to its full width.) And exit defaults to shrinking the content horizontally with the end of the content being the leading edge while fading out. The expanding and shrinking will likely also animate the parent and siblings in the row 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.
| Parameters | |
|---|---|
visibleState: MutableTransitionState<Boolean> |
defines whether the content should be visible |
modifier: Modifier = Modifier |
|
enter: EnterTransition = expandHorizontally() + fadeIn() |
EnterTransition(s) used for the appearing animation, fading in while expanding vertically by default |
exit: ExitTransition = shrinkHorizontally() + 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 the value of |
BottomNavigationItem
@Composable
fun RowScope.BottomNavigationItem(
selected: Boolean,
onClick: () -> Unit,
icon: @Composable () -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
label: (@Composable () -> Unit)? = null,
alwaysShowLabel: Boolean = true,
interactionSource: MutableInteractionSource? = null,
selectedContentColor: Color = LocalContentColor.current,
unselectedContentColor: Color = selectedContentColor.copy(alpha = ContentAlpha.medium)
): Unit
Material Design bottom navigation item.
The recommended configuration for a BottomNavigationItem depends on how many items there are inside a BottomNavigation:
-
Three destinations: Display icons and text labels for all destinations.
-
Four destinations: Active destinations display an icon and text label. Inactive destinations display icons, and text labels are recommended.
-
Five destinations: Active destinations display an icon and text label. Inactive destinations use icons, and use text labels if space permits.
A BottomNavigationItem always shows text labels (if it exists) when selected. Showing text labels if not selected is controlled by alwaysShowLabel.
| Parameters | |
|---|---|
selected: Boolean |
whether this item is selected |
onClick: () -> Unit |
the callback to be invoked when this item is selected |
icon: @Composable () -> Unit |
icon for this item, typically this will be an |
modifier: Modifier = Modifier |
optional |
enabled: Boolean = true |
controls the enabled state of this item. When |
label: (@Composable () -> Unit)? = null |
optional text label for this item |
alwaysShowLabel: Boolean = true |
whether to always show the label for this item. If false, the label will only be shown when this item is selected. |
interactionSource: MutableInteractionSource? = null |
an optional hoisted |
selectedContentColor: Color = LocalContentColor.current |
the color of the text label and icon when this item is selected, and the color of the ripple. |
unselectedContentColor: Color = selectedContentColor.copy(alpha = ContentAlpha.medium) |
the color of the text label and icon when this item is not selected |
NavigationBarItem
@Composable
fun RowScope.NavigationBarItem(
selected: Boolean,
onClick: () -> Unit,
icon: @Composable () -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
label: (@Composable () -> Unit)? = null,
alwaysShowLabel: Boolean = true,
colors: NavigationBarItemColors = NavigationBarItemDefaults.colors(),
interactionSource: MutableInteractionSource? = null
): Unit
Material Design navigation bar item.
Navigation bars offer a persistent and convenient way to switch between primary destinations in an app.
The recommended configuration for a NavigationBarItem depends on how many items there are inside a NavigationBar:
-
Three destinations: Display icons and text labels for all destinations.
-
Four destinations: Active destinations display an icon and text label. Inactive destinations display icons, and text labels are recommended.
-
Five destinations: Active destinations display an icon and text label. Inactive destinations use icons, and use text labels if space permits.
A NavigationBarItem always shows text labels (if it exists) when selected. Showing text labels if not selected is controlled by alwaysShowLabel.
| Parameters | |
|---|---|
selected: Boolean |
whether this item is selected |
onClick: () -> Unit |
called when this item is clicked |
icon: @Composable () -> Unit |
icon for this item, typically an |
modifier: Modifier = Modifier |
the |
enabled: Boolean = true |
controls the enabled state of this item. When |
label: (@Composable () -> Unit)? = null |
optional text label for this item |
alwaysShowLabel: Boolean = true |
whether to always show the label for this item. If |
colors: NavigationBarItemColors = NavigationBarItemDefaults.colors() |
|
interactionSource: MutableInteractionSource? = null |
an optional hoisted |