AlignmentLine

sealed class AlignmentLine(internal val merger: (Int, Int) -> Int)

Defines an offset line that can be used by parent layouts to align and position their children. Text baselines are representative examples of AlignmentLines. For example, they can be used by Row, to align its children by baseline, or by paddingFrom to achieve a layout with a specific distance from the top to the baseline of the text content. AlignmentLines can be understood as an abstraction over text baselines.

When a layout provides a value for a particular AlignmentLine, this can be read by the parents of the layout after measuring, using the Placeable.get operator on the corresponding Placeable instance. Based on the position of the AlignmentLine, the parents can then decide the positioning of the children.

Note that when a layout provides a value for an AlignmentLine, this will be automatically inherited by the layout's parent, which will offset the value by the position of the child within itself. This way, nested layout hierarchies are able to preserve the AlignmentLines defined for deeply nested children, making it possible for non-direct parents to use these for positioning and alignment. When a layout inherits multiple values for the same AlignmentLine from different children, the position of the line within the layout will be computed by merging the children values using the provided merger. If a layout provides a value for an AlignmentLine, this will always be the position of the line, regardless of the values provided by children for the same line.

AlignmentLines cannot be created directly, please create VerticalAlignmentLine or HorizontalAlignmentLine instances instead.

Companion Object

Properties

const val Unspecified = Int.MIN_VALUE

Constant representing that an AlignmentLine has not been provided.

Code Examples

AlignmentLineSample

@Composable
fun AlignmentLineSample() {
    // Create a horizontal alignment line. Note it is not common for alignment lines to be created
    // in the scope of one composable, since they are usually used across more than one function.
    // We use ::min as merging strategy, which means that the parent will have the minimum of
    // the values of the alignment line, when this is inherited from more than one child.
    val exampleLine = remember { HorizontalAlignmentLine(::min) }
    // A layout with a fixed size, and a given position for the exampleLine alignment line.
    @Composable
    fun LineProviderLayout(exampleLinePosition: Int) {
        val size: Int = 20
        Layout({}) { _, _ -> layout(size, size, mapOf(exampleLine to exampleLinePosition)) {} }
    }
    Layout({
        LineProviderLayout(exampleLinePosition = 5)
        LineProviderLayout(exampleLinePosition = 10)
    }) { measurables, constraints ->
        val placeables = measurables.map { it.measure(constraints) }
        // placeables[0][line] will be 5
        // placeables[1][line] will be 10
        layout(constraints.maxWidth, constraints.maxHeight) {
            placeables[0].place(0, 3)
            placeables[1].place(constraints.maxWidth / 2, 0)
        }
    }
    // Note that if the parent of this Layout (the parent of AlignmentLineSample) was able to
    // query its position of exampleLine (assuming this was in a shared scope), its position would
    // be 8. This is because the Layout positioned its first child at 3 from the top,
    // and because of the ::min merging strategy the position of exampleLine will be
    // min(5 + 3, 10 + 0).
}