Class

Placeable.PlacementScope

Receiver scope that permits explicit placement of a Placeable.

Common
@PlacementScopeMarker
    abstract class PlacementScope : Density

Receiver scope that permits explicit placement of a Placeable.

While a Placeable may be placed at any time, this explicit receiver scope is used to discourage placement outside of MeasureScope.layout positioning blocks. This permits Compose UI to perform additional layout optimizations allowing repositioning a Placeable without remeasuring its original Measurable if factors contributing to its potential measurement have not changed. The scope also allows automatic mirroring of children positions in RTL layout direction contexts using the placeRelative methods available in the scope. If the automatic mirroring is not desired, place should be used instead.

Properties

Common
open val coordinates: LayoutCoordinates?

The LayoutCoordinates of this layout, if known or null if the layout hasn't been placed yet. coordinates will be null when determining alignment lines, preventing alignment lines from depending on absolute coordinates.

When coordinates is null, there will always be a follow-up placement call in which coordinates is not-null.

If you read a position from the coordinates during the placement block the block will be automatically re-executed when the parent layout changes a position. If you don't read it the placement block execution can be skipped as an optimization.

Functions

current

open fun Ruler.current(: Float): Float

Returns the value for this Ruler or defaultValue if it wasn't provided. Ruler values are unavailable while calculating AlignmentLines.

placeRelative

fun Placeable.placeRelative(position: IntOffset, zIndex: Float = 0f) =
            placeAutoMirrored(position, zIndex, null)

Place a Placeable at position in its parent's coordinate system. If the layout direction is right-to-left, the given position will be horizontally mirrored so that the position of the Placeable implicitly reacts to RTL layout direction contexts. If this method is used outside the MeasureScope.layout positioning block, the automatic position mirroring will not happen and the Placeable will be placed at the given position, similar to the place method.

Parameters
position position in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.

placeRelative

fun Placeable.placeRelative(x: Int, y: Int, zIndex: Float = 0f) =
            placeAutoMirrored(IntOffset(x, y), zIndex, null)

Place a Placeable at x, y in its parent's coordinate system. If the layout direction is right-to-left, the given position will be horizontally mirrored so that the position of the Placeable implicitly reacts to RTL layout direction contexts. If this method is used outside the MeasureScope.layout positioning block, the automatic position mirroring will not happen and the Placeable will be placed at the given position, similar to the place method.

Parameters
x x coordinate in the parent's coordinate system.
y y coordinate in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.

place

fun Placeable.place(x: Int, y: Int, zIndex: Float = 0f) =
            placeApparentToRealOffset(IntOffset(x, y), zIndex, null)

Place a Placeable at x, y in its parent's coordinate system. Unlike placeRelative, the given position will not implicitly react in RTL layout direction contexts.

Parameters
x x coordinate in the parent's coordinate system.
y y coordinate in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.

place

fun Placeable.place(position: IntOffset, zIndex: Float = 0f) =
            placeApparentToRealOffset(position, zIndex, null)

Place a Placeable at position in its parent's coordinate system. Unlike placeRelative, the given position will not implicitly react in RTL layout direction contexts.

Parameters
position position in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.

placeRelativeWithLayer

fun Placeable.placeRelativeWithLayer(
            position: IntOffset,
            zIndex: Float = 0f,
            layerBlock: GraphicsLayerScope.() -> Unit = DefaultLayerBlock,
        ) = placeAutoMirrored(position, zIndex, layerBlock)

Place a Placeable at position in its parent's coordinate system with an introduced graphic layer. If the layout direction is right-to-left, the given position will be horizontally mirrored so that the position of the Placeable implicitly reacts to RTL layout direction contexts. If this method is used outside the MeasureScope.layout positioning block, the automatic position mirroring will not happen and the Placeable will be placed at the given position, similar to the place method.

Parameters
position position in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layerBlock You can configure any layer property available on GraphicsLayerScope via this block. If the Placeable will be placed with a new position next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeRelativeWithLayer

fun Placeable.placeRelativeWithLayer(
            x: Int,
            y: Int,
            zIndex: Float = 0f,
            layerBlock: GraphicsLayerScope.() -> Unit = DefaultLayerBlock,
        ) = placeAutoMirrored(IntOffset(x, y), zIndex, layerBlock)

Place a Placeable at x, y in its parent's coordinate system with an introduced graphic layer. If the layout direction is right-to-left, the given position will be horizontally mirrored so that the position of the Placeable implicitly reacts to RTL layout direction contexts. If this method is used outside the MeasureScope.layout positioning block, the automatic position mirroring will not happen and the Placeable will be placed at the given position, similar to the place method.

Parameters
x x coordinate in the parent's coordinate system.
y y coordinate in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layerBlock You can configure any layer property available on GraphicsLayerScope via this block. If the Placeable will be placed with a new x or y next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeWithLayer

fun Placeable.placeWithLayer(
            x: Int,
            y: Int,
            zIndex: Float = 0f,
            layerBlock: GraphicsLayerScope.() -> Unit = DefaultLayerBlock,
        ) = placeApparentToRealOffset(IntOffset(x, y), zIndex, layerBlock)

Place a Placeable at x, y in its parent's coordinate system with an introduced graphic layer. Unlike placeRelative, the given position will not implicitly react in RTL layout direction contexts.

Parameters
x x coordinate in the parent's coordinate system.
y y coordinate in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layerBlock You can configure any layer property available on GraphicsLayerScope via this block. If the Placeable will be placed with a new x or y next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeWithLayer

fun Placeable.placeWithLayer(
            position: IntOffset,
            zIndex: Float = 0f,
            layerBlock: GraphicsLayerScope.() -> Unit = DefaultLayerBlock,
        ) = placeApparentToRealOffset(position, zIndex, layerBlock)

Place a Placeable at position in its parent's coordinate system with an introduced graphic layer. Unlike placeRelative, the given position will not implicitly react in RTL layout direction contexts.

Parameters
position position in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layerBlock You can configure any layer property available on GraphicsLayerScope via this block. If the Placeable will be placed with a new position next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeWithLayer

fun Placeable.placeWithLayer(x: Int, y: Int, layer: GraphicsLayer, zIndex: Float = 0f) =
            placeApparentToRealOffset(IntOffset(x, y), zIndex, layer)

Place a Placeable at x, y in its parent's coordinate system with an introduced graphic layer. Unlike placeRelative, the given position will not implicitly react in RTL layout direction contexts.

Parameters
x x coordinate in the parent's coordinate system.
y y coordinate in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layer GraphicsLayer to place this placeable with. If the Placeable will be placed with a new x or y next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeWithLayer

fun Placeable.placeWithLayer(
            position: IntOffset,
            layer: GraphicsLayer,
            zIndex: Float = 0f,
        ) = placeApparentToRealOffset(position, zIndex, layer)

Place a Placeable at position in its parent's coordinate system with an introduced graphic layer. Unlike placeRelative, the given position will not implicitly react in RTL layout direction contexts.

Parameters
position position in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layer GraphicsLayer to place this placeable with. If the Placeable will be placed with a new position next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeRelativeWithLayer

fun Placeable.placeRelativeWithLayer(
            x: Int,
            y: Int,
            layer: GraphicsLayer,
            zIndex: Float = 0f,
        ) = placeAutoMirrored(IntOffset(x, y), zIndex, layer)

Place a Placeable at x, y in its parent's coordinate system with an introduced graphic layer. If the layout direction is right-to-left, the given position will be horizontally mirrored so that the position of the Placeable implicitly reacts to RTL layout direction contexts. If this method is used outside the MeasureScope.layout positioning block, the automatic position mirroring will not happen and the Placeable will be placed at the given position, similar to the place method.

Parameters
x x coordinate in the parent's coordinate system.
y y coordinate in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layer GraphicsLayer to place this placeable with. If the Placeable will be placed with a new x or y next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

placeRelativeWithLayer

fun Placeable.placeRelativeWithLayer(
            position: IntOffset,
            layer: GraphicsLayer,
            zIndex: Float = 0f,
        ) = placeAutoMirrored(position, zIndex, layer)

Place a Placeable at position in its parent's coordinate system with an introduced graphic layer. If the layout direction is right-to-left, the given position will be horizontally mirrored so that the position of the Placeable implicitly reacts to RTL layout direction contexts. If this method is used outside the MeasureScope.layout positioning block, the automatic position mirroring will not happen and the Placeable will be placed at the given position, similar to the place method.

Parameters
position position in the parent's coordinate system.
zIndex controls the drawing order for the Placeable. A Placeable with larger zIndex will be drawn on top of all the children with smaller zIndex. When children have the same zIndex the order in which the items were placed is used.
layer GraphicsLayer to place this placeable with. If the Placeable will be placed with a new position next time only the graphic layer will be moved without requiring to redrawn the Placeable content.

withMotionFrameOfReferencePlacement

fun withMotionFrameOfReferencePlacement(block: PlacementScope.() -> Unit)

Placement done under block, will have their Placeable placed on the same frame of reference as the current layout.

In LayoutCoordinates, this means that the offset introduced under block may be excluded when calculating positions by passing includeMotionFrameOfReference = false in LayoutCoordinates.localPositionOf.

Excluding the position set by certain layouts can be helpful to trigger lookahead based animation when intended. The typical case are layouts that change frequently due to a provided value, like scroll.