The AlignmentLine

In the previous part, we had the following custom layout:

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp
) = layout { measurable, constraints ->
    // Measure the composable
    val placeable = measurable.measure(constraints)

    // Check the composable has a first baseline and extract it
    check(placeable[FirstBaseline] != AlignmentLine.Unspecified)
    val firstBaseline = placeable[FirstBaseline]

    // Calculate: the total height of the composable after applying the firstBaselineToTop value is equal to its original height plus the diff between the firstBaselineToTop value and the first baseline, which is:
    val totalHeight = placeable.height + 
        (firstBaselineToTop.roundToPx() - firstBaseline)
    // Therefore, the starting point from top by which we place the composable is:
    val placeableY = totalHeight - placeable.height
    layout(placeable.width, totalHeight) {
        // Now place it
        placeable.placeRelative(0, placeableY)
    }
}

Let's focus on this part:

// Check the composable has a first baseline and extract it
check(placeable[FirstBaseline] != AlignmentLine.Unspecified)
val firstBaseline = placeable[FirstBaseline]

There is barely an explanation for it. It turns out that, here, we extract the value exported by the placeable, and use it to calculate and lay our composable out. This is mentioned in the document:

The Compose layout model lets you use AlignmentLine to create custom alignment lines that can be used by parent layouts to align and position their children. For example, Row can use its children's custom alignment lines to align them.

When a layout provides a value for a particular AlignmentLine, the layout's parents can read this value 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.

To better understand this, let consider this question: given a parent layout X with 3 children: A, B, C. How can we align B and C relatively to some value calculated by laying out A?

Based on the document, we can do this using AlignmentLine. But how?

To demonstrate the solution, consider this example:

• A is a block of text, which has the first baseline value (distance from the top of the text to the first baseline in pixel) and the last baseline value (distance from the top of the text block to the baseline of that last line in pixel).
• B is a text block whose first baseline is aligned horizontally with the first baseline of A,
• and C is another text block whose first baseline is aligned horizontally with the last baseline of A.
• X is the custom layout we build to fulfill our requirement:

The full code of this example is as below (with some adjustment to draw lines for our verification):

@Composable
fun TextWithBaselineIndicator(
  modifier: Modifier = Modifier,
  topLine: @Composable () -> Unit,
  bottomLine: @Composable () -> Unit,
  content: @Composable () -> Unit,
) {
  Layout(
    content = {
      content()
      Text(text = "first baseline")
      Text(text = "last baseline")
      topLine()
      bottomLine()
    },
    modifier = Modifier.then(modifier)
  ) { measurables: List<Measurable>, constraints: Constraints ->
    check(measurables.size == 5)
    val placeables = measurables.map {
      it.measure(constraints = constraints)
    }

    val mainBlock = placeables[0]

    val firstBaseline = mainBlock[FirstBaseline]
    val firstBaselineText = placeables[1]
    val firstBaselineTextY =
      firstBaseline - firstBaselineText[FirstBaseline]

    val lastBaseline = mainBlock[LastBaseline]
    val lastBaselineText = placeables[2]
    val lastBaselineTextY =
      lastBaseline - lastBaselineText[FirstBaseline]

    layout(
      width = constraints.maxWidth,
      height = constraints.maxHeight
    ) {
      // The texts that are aligned with the baselines
      firstBaselineText.placeRelative(0, firstBaselineTextY)
      lastBaselineText.placeRelative(0, lastBaselineTextY)

      // Red lines
      placeables[3].placeRelative(0, firstBaseline)
      placeables[4].placeRelative(0, lastBaseline)

      // The main text block
      mainBlock.placeRelative(
        max(firstBaselineText.width, lastBaselineText.width) + 16,
        0
      )
    }
  }
}

// Usage
TextWithBaselineIndicator(
  modifier = Modifier,
  topLine = {
    Canvas(modifier = Modifier.fillMaxWidth()) {
      val canvasWidth = size.width
      val canvasHeight = size.height
      drawLine(
        start = Offset(x = canvasWidth, y = 0f),
        end = Offset(x = 0f, y = canvasHeight),
        color = Color.Red
      )
    }
  },
  bottomLine = {
    Canvas(modifier = Modifier.fillMaxWidth()) {
      val canvasWidth = size.width
      val canvasHeight = size.height
      drawLine(
        start = Offset(x = canvasWidth, y = 0f),
        end = Offset(x = 0f, y = canvasHeight),
        color = Color.Red
      )
    }
  }
) {
  Text(
    text = "This is a really long text.\nThis is a really long text.\nThis is a really long text.\nThis is a really long text.",
    fontSize = 24.sp,
  )
}

As you can see, we extract the information about the first baseline and last baseline of the main text by calling:

val firstBaseline = mainBlock[FirstBaseline]
val lastBaseline = mainBlock[LastBaseline]

So what does that code do?

We can see that, a Placeable is also a Measured, so placeable[FirstBaseline] is equal to placeable.get(FirstBaseline), which "returns the position of an alignment line, or AlignmentLine.Unspecified if the line is not provided." (operator fun get(alignmentLine: AlignmentLine): Int). But where does the FirstBaseline come from and why placeable[FirstBaseline] returns the value we need? Reading the source code, we learn that:

• FirstBaseline is a built-in AlignmentLine.

• And a Text composable exposes that value via the layout call.

Now, go back to our original question: what is AlignmentLine and how we can use it. From the example above, we can guess that: an AlignmentLine is a value exposed by a composable so that the parent composable can use it to align the children composable accordingly. A Text composable exposes 2 alignment lines: FirstBaseline and LastBaseline by which we can build custom layouts like above. A custom AlignmentLine can be exposed by passing them to the layout(width, height, alignmentLines) callback in the custom layout implementation.

In the next part, we will learn about the AlignmentLine further, by going through the official document.

The simple Modifier.layout from sample code

Let's replicate the Modifier.firstBaselineToTop in the official document, step by step to understand how it works.

The final form:

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp
) = layout { measurable, constraints ->
    // Measure the composable
    val placeable = measurable.measure(constraints)

    // Check the composable has a first baseline
    check(placeable[FirstBaseline] != AlignmentLine.Unspecified)
    val firstBaseline = placeable[FirstBaseline]

    // Height of the composable with padding - first baseline
    val placeableY = firstBaselineToTop.roundToPx() - firstBaseline
    val height = placeable.height + placeableY
    layout(placeable.width, height) {
        // Where the composable gets placed
        placeable.placeRelative(0, placeableY)
    }
}

And its result:

Source: official document

Step 1: the do-nothing attempt

In the first step, let's just add the bare minimum code that does nothing:

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp
) = layout { _: Measurable, _: Constraints ->
    // Usually, we need to measure the composable and get the `placeable`, but in this step, we will ignore it, and pass 0 as width and height to the layout callback.
    layout(width = 0, height = 0) { /* Do nothing */ }
}

And verify the UI by using the Android Studio layout inspector. In this step, it is easy to imagine that there is nothing shown in the UI. Let's skip this step.

Step 2: measure it, lay it out, but don't place it there.

What we do is to measure the composable, pass the measured width and height to the layout callback in the lambda.:

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp
) = layout { measurable: Measurable, constraints: Constraints ->
    // Measure the composable and get the placeable, using the provided measurable and constraints
    val placeable = measurable.measure(constraints)
    layout(width = placeable.width, height = placeable.height) { /* Do nothing */ }
}

Now let's check the UI. It is still a blank space in the screen, but if we inspect it, there is something populates the space:

Adjusting the width or height above, we can conclude that: the layout callback will tell the parent to reserve a rectangle whose width and height are provided value, and its coordinate starts from (0, 0). This rectangle will be the boundary of our composable after laying out. Indeed, if we update out code to the following and check the result:

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp
) = layout { measurable: Measurable, constraints: Constraints ->
    // Measure the composable and get the placeable, using the provided measurable and constraints
    val placeable = measurable.measure(constraints)
    layout(width = placeable.width, height = placeable.height) {
        placeable.placeRelative(x = 20, y = 20)
    }
}

The layout inspector shows that: our text is placed 20 pixel from the left, and 20 pixel from the top, and it is cut at the edge of the dimension we provided above.

To be able to correctly place the composable, we need to adjust the space required by it. It is time to take the firstBaselineToTop into account.

Step 3: measure it, reserve space for it and place it

fun Modifier.firstBaselineToTop(
    firstBaselineToTop: Dp
) = layout { measurable, constraints ->
    // Measure the composable
    val placeable = measurable.measure(constraints)

    // Check the composable has a first baseline and extract it
    check(placeable[FirstBaseline] != AlignmentLine.Unspecified)
    val firstBaseline = placeable[FirstBaseline]

    // Calculate: the total height of the composable after applying the `firstBaselineToTop` value is equal to its original height plus the diff between the
`firstBaselineToTop` value and the first baseline, which is:
    val totalHeight = placeable.height + (firstBaselineToTop.roundToPx() - firstBaseline)
    // Therefore, the starting point from top by which we place the composable is:
    val placeableY = totalHeight - placeable.height
    layout(placeable.width, totalHeight) {
        // Now place it
        placeable.placeRelative(0, placeableY)
    }
}

And tada:

Exploring the layout callback

It seems that the layout callback is one of the core actor here. Let's learn more about it:

interface MeasureScope : IntrinsicMeasureScope {
    /**
     * @param alignmentLines the alignment lines defined by the layout
     * @param placementBlock block defining the children positioning of the current layout
     */
    fun layout(
        width: Int,
        height: Int,
        alignmentLines: Map<AlignmentLine, Int> = emptyMap(),
        placementBlock: Placeable.PlacementScope.() -> Unit
    ) = object : MeasureResult {
        override val width = width
        override val height = height
        override val alignmentLines = alignmentLines
        override fun placeChildren() {
            Placeable.PlacementScope.executeWithRtlMirroringValues(
                width,
                layoutDirection,
                placementBlock
            )
        }
    }
}

So beside the width, the height and the placementBlock lambda we used to place the placeable, there is alignmentLines values which is default to an empty map. Let's learn about this value in part 2.