Google is committed to advancing racial equity for Black communities. See how.

ColumnScope

@Immutable object ColumnScope
kotlin.Any
   ↳ androidx.ui.layout.ColumnScope

Scope for the children of Column.

Summary

Public methods
Modifier

Position the element horizontally such that its alignmentLine aligns with sibling elements also configured to alignWithSiblings.

Modifier
Modifier.alignWithSiblings(alignmentLineBlock: (Measured) -> Int)

Position the element horizontally such that the alignment line for the content as determined by alignmentLineBlock aligns with sibling elements also configured to alignWithSiblings.

Modifier

Position the element horizontally within the Column according to align.

Modifier
Modifier.weight(@FloatRange(0.0, false) weight: Float, fill: Boolean = true)

Size the element's height proportional to its weight relative to other weighted sibling elements in the Column.

Public methods

alignWithSiblings

@Stable fun Modifier.alignWithSiblings(alignmentLine: VerticalAlignmentLine): Modifier

Position the element horizontally such that its alignmentLine aligns with sibling elements also configured to alignWithSiblings. alignWithSiblings is a form of gravity, so both modifiers will not work together if specified for the same layout. Within a Column, all components with alignWithSiblings will align horizontally using the specified VerticalAlignmentLines or values provided using the other alignWithSiblings overload, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Start gravity 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 alignWithSiblings modifier specified the element will be positioned as if it had Alignment.Start gravity.

Example usage:

import androidx.ui.core.Layout
import androidx.ui.core.VerticalAlignmentLine
import androidx.ui.foundation.Box
import androidx.ui.foundation.drawBackground
import androidx.ui.layout.Column
import androidx.ui.layout.preferredSize

// 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 alignWithSiblings.
val start = VerticalAlignmentLine(::min)
val end = VerticalAlignmentLine(::min)

@Composable
fun RectangleWithStartEnd(modifier: Modifier = Modifier, color: Color, width: Dp, height: Dp) {
    Layout(
        children = { },
        modifier = modifier.drawBackground(color = color)
    ) { _, constraints, _ ->
        val widthPx = max(width.toIntPx(), constraints.minWidth)
        val heightPx = max(height.toIntPx(), 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.preferredSize(80.dp, 40.dp).alignWithSiblings { it.width / 2 },
        backgroundColor = Color.Blue
    )
    RectangleWithStartEnd(
        Modifier.alignWithSiblings(end),
        color = Color.Magenta,
        width = 80.dp,
        height = 40.dp
    )
    RectangleWithStartEnd(
        Modifier.alignWithSiblings(start),
        color = Color.Red,
        width = 80.dp,
        height = 40.dp
    )
}

alignWithSiblings

@Stable fun Modifier.alignWithSiblings(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 alignWithSiblings. alignWithSiblings is a form of gravity, so both modifiers will not work together if specified for the same layout. Within a Column, all components with alignWithSiblings 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 gravity 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 alignWithSiblings modifier specified the element will be positioned as if it had Alignment.Start gravity.

Example usage:

import androidx.ui.foundation.Box
import androidx.ui.layout.Column
import androidx.ui.layout.preferredSize

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.preferredSize(80.dp, 40.dp).alignWithSiblings { it.width / 2 },
        backgroundColor = Color.Blue
    )
    Box(
        Modifier.preferredSize(80.dp, 40.dp).alignWithSiblings { it.width },
        backgroundColor = Color.Magenta
    )
    Box(
        Modifier.preferredSize(80.dp, 40.dp).alignWithSiblings { 0 },
        backgroundColor = Color.Red
    )
}

gravity

@Stable fun Modifier.gravity(align: Alignment.Horizontal): Modifier

Position the element horizontally within the Column according to align.

Example usage:

import androidx.ui.foundation.Box
import androidx.ui.layout.Column
import androidx.ui.layout.fillMaxWidth
import androidx.ui.layout.preferredSize

Column(Modifier.fillMaxWidth()) {
    // The child with no gravity modifier is positioned by default so that its start edge
    // aligned with the start edge of the horizontal axis.
    Box(Modifier.preferredSize(80.dp, 40.dp), backgroundColor = Color.Magenta)
    // Gravity.Start, the child will be positioned so that its start edge is aligned with
    // the start edge of the horizontal axis.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .gravity(Alignment.Start),
        backgroundColor = Color.Red
    )
    // Gravity.Center, the child will be positioned so that its center is in the middle of
    // the horizontal axis.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .gravity(Alignment.CenterHorizontally),
        backgroundColor = Color.Yellow
    )
    // Gravity.End, the child will be positioned so that its end edge aligned to the end of
    // the horizontal axis.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .gravity(Alignment.End),
        backgroundColor = Color.Green
    )
}

weight

@Stable fun Modifier.weight(
    @FloatRange(0.0, false) weight: 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.

import androidx.ui.foundation.Box
import androidx.ui.layout.Column
import androidx.ui.layout.preferredSize
import androidx.ui.layout.preferredWidth

Column {
    // The child with no weight will have the specified size.
    Box(Modifier.preferredSize(40.dp, 80.dp), backgroundColor = Color.Magenta)
    // Has weight, the child will occupy half of the remaining height.
    Box(Modifier.preferredWidth(40.dp).weight(1f), backgroundColor = 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.preferredSize(40.dp, 80.dp)
            .weight(1f, fill = false),
        backgroundColor = Color.Green
    )
}