LayoutCoordinates

@JvmDefaultWithCompatibility
interface LayoutCoordinates

A holder of the measured bounds for the Layout.

Properties

val size: IntSize

The size of this layout in the local coordinates space.

val providedAlignmentLines: Set<AlignmentLine>

The alignment lines provided for this layout, not including inherited lines.

val parentLayoutCoordinates: LayoutCoordinates?

The coordinates of the parent layout. Null if there is no parent.

val parentCoordinates: LayoutCoordinates?

The coordinates of the parent layout modifier or parent layout if there is no parent layout modifier, or null if there is no parent.

val isAttached: Boolean

Returns false if the corresponding layout was detached from the hierarchy.

val introducesMotionFrameOfReference: Boolean

Indicates whether the corresponding Layout is expected to change its Offset in small increments (such as when its parent is a Scroll).

In those situations, the corresponding placed LayoutCoordinates will have their introducesMotionFrameOfReference return true.

Custom Layouts that are expected to have similar behaviors should place their children using Placeable.PlacementScope.withMotionFrameOfReferencePlacement.

You may then use localPositionOf with includeMotionFrameOfReference = false to query a Layout's position such that it excludes all Offset introduced by those Layouts.

This is typically helpful when deciding when to animate an approachLayout using LookaheadScope coordinates. As you probably don't want to trigger animations on small positional increments.

Functions

fun screenToLocal(relativeToScreen: Offset): Offset

Converts relativeToScreen relative to the device's screen's origin into an Offset relative to this layout. Returns Offset.Unspecified if the conversion cannot be performed.

fun localToScreen(relativeToLocal: Offset): Offset

Converts relativeToLocal position within this layout into an Offset relative to the device's screen. Returns Offset.Unspecified if the conversion cannot be performed.

fun windowToLocal(relativeToWindow: Offset): Offset

Converts relativeToWindow relative to the window's origin into an Offset relative to this layout.

fun localToWindow(relativeToLocal: Offset): Offset

Converts relativeToLocal position within this layout into an Offset relative to the window's origin.

fun localToRoot(relativeToLocal: Offset): Offset

Converts a local position within this layout into an offset from the root composable.

fun localPositionOf(sourceCoordinates: LayoutCoordinates, relativeToSource: Offset): Offset

Converts an relativeToSource in sourceCoordinates space into local coordinates. sourceCoordinates may be any LayoutCoordinates that belong to the same compose layout hierarchy.

By default, includes the Offset when introducesMotionFrameOfReference is true. But you may exclude it from the calculation by using the overload that takes includeMotionFrameOfReference and passing it as false.

fun localPositionOf(
        sourceCoordinates: LayoutCoordinates,
        relativeToSource: Offset = Offset.Zero,
        includeMotionFrameOfReference: Boolean = true,
    ): Offset

Converts an relativeToSource in sourceCoordinates space into local coordinates. sourceCoordinates may be any LayoutCoordinates that belong to the same compose layout hierarchy.

Use includeMotionFrameOfReference to decide whether to include the Offset of any LayoutCoordinate that returns true in the includeMotionFrameOfReference flag.

In other words, passing includeMotionFrameOfReference as false, returns a calculation that excludes the Offset set from Layouts that place their children using Placeable.PlacementScope.withMotionFrameOfReferencePlacement.

fun localBoundingBoxOf(sourceCoordinates: LayoutCoordinates, clipBounds: Boolean = true): Rect

Returns the bounding box of sourceCoordinates in the local coordinates. If clipBounds is true, any clipping that occurs between sourceCoordinates and this layout will affect the returned bounds, and can even result in an empty rectangle if clipped regions do not overlap. If clipBounds is false, the bounding box of sourceCoordinates will be converted to local coordinates irrespective of any clipping applied between the layouts.

When rotation or scaling is applied, the bounding box of the rotated or scaled value will be computed in the local coordinates. For example, if a 40 pixels x 20 pixel layout is rotated 90 degrees, the bounding box will be 20 pixels x 40 pixels in its parent's coordinates.

fun transformFrom(sourceCoordinates: LayoutCoordinates, matrix: Matrix)

Modifies matrix to be a transform to convert a coordinate in sourceCoordinates to a coordinate in this LayoutCoordinates.

fun transformToScreen(matrix: Matrix)

Takes a matrix which transforms some coordinate system C to local coordinates, and updates the matrix to transform from C to screen coordinates instead.

operator fun get(alignmentLine: AlignmentLine): Int

Returns the position in pixels of an alignment line, or AlignmentLine.Unspecified if the line is not provided.