Constraints - Class in Compose UI Unit

Class

Common

value class Constraints(@PublishedApi internal val value: Long)

Immutable constraints for measuring layouts, used by layouts or layout modifiers to measure their layout children. The parent chooses the Constraints defining a range, in pixels, within which the measured layout should choose a size:

minWidth <= chosenWidth <= maxWidth
minHeight <= chosenHeight <= maxHeight

For more details about how layout measurement works, see androidx.compose.ui.layout.MeasurePolicy or androidx.compose.ui.layout.LayoutModifier.measure.

A set of Constraints can have infinite maxWidth and/or maxHeight. This is a trick often used by parents to ask their children for their preferred size: unbounded constraints force children whose default behavior is to fill the available space (always size to maxWidth/maxHeight) to have an opinion about their preferred size. Most commonly, when measured with unbounded Constraints, these children will fallback to size themselves to wrap their content, instead of expanding to fill the available space (this is not always true as it depends on the child layout model, but is a common behavior for core layout components).

Constraints uses a Long to represent four values, minWidth, minHeight, maxWidth, and maxHeight. The range of the values varies to allow for at most 256K in one dimension. There are four possible maximum ranges, 13 bits/18 bits, and 15 bits/16 bits for either width or height, depending on the needs. For example, a width could range up to 18 bits and the height up to 13 bits. Alternatively, the width could range up to 16 bits and the height up to 15 bits. The height and width requirements can be reversed, with a height of up to 18 bits and width of 13 bits or height of 16 bits and width of 15 bits. Any constraints exceeding this range will fail.

Properties

Common

val minWidth: Int

The minimum width that the measurement can take, in pixels.

Common

val maxWidth: Int

The maximum width that the measurement can take, in pixels. This will either be a positive value greater than or equal to minWidth or Constraints.Infinity.

Common

val minHeight: Int

The minimum height that the measurement can take, in pixels.

Common

val maxHeight: Int

The maximum height that the measurement can take, in pixels. This will either be a positive value greater than or equal to minHeight or Constraints.Infinity.

Common

val hasBoundedWidth: Boolean

false when maxWidth is Infinity and true if maxWidth is a non-Infinity value.

Common

val hasBoundedHeight: Boolean

false when maxHeight is Infinity and true if maxHeight is a non-Infinity value.

Common

val hasFixedWidth: Boolean

Whether there is exactly one width value that satisfies the constraints.

Common

val hasFixedHeight: Boolean

Whether there is exactly one height value that satisfies the constraints.

Common

val isZero: Boolean

Whether the area of a component respecting these constraints will definitely be 0. This is true when at least one of maxWidth and maxHeight are 0.

Functions

fun copy(
        minWidth: Int = this.minWidth,
        maxWidth: Int = this.maxWidth,
        minHeight: Int = this.minHeight,
        maxHeight: Int = this.maxHeight,
    ): Constraints

Copies the existing Constraints, replacing some of minWidth, minHeight, maxWidth, or maxHeight as desired. minWidth and minHeight must be positive and maxWidth and maxHeight must be greater than or equal to minWidth and minHeight, respectively, or Infinity.

inline fun copyMaxDimensions() = Constraints(value and MaxDimensionsAndFocusMask)

Copies the existing Constraints, setting minWidth and minHeight to 0, and preserving maxWidth and maxHeight as-is.

Companion Object

Properties

Common

const val Infinity = Int.MAX_VALUE

A value that maxWidth or maxHeight will be set to when the constraint should be considered infinite. hasBoundedWidth or hasBoundedHeight will be false when maxWidth or maxHeight is Infinity, respectively.

Methods

Common

fun fixed(width: Int, height: Int): Constraints

Creates constraints for fixed size in both dimensions.

Common

fun fixedWidth(width: Int): Constraints

Creates constraints for fixed width and unspecified height.

Common

fun fixedHeight(height: Int): Constraints

Creates constraints for fixed height and unspecified width.

Common

Deprecated Replace with fitPrioritizingWidth

fun restrictConstraints(
            minWidth: Int,
            maxWidth: Int,
            minHeight: Int,
            maxHeight: Int,
            prioritizeWidth: Boolean = true,
        ): Constraints

Common

fun fitPrioritizingWidth(
            minWidth: Int,
            maxWidth: Int,
            minHeight: Int,
            maxHeight: Int,
        ): Constraints

Returns Constraints that match as close as possible to the values passed. If the dimensions are outside of those that can be represented, the constraints are limited to those that can be represented.

Constraints is a value class based on a Long and 4 integers must be limited to fit within its size. The larger dimension has up to 18 bits (262,143) and the smaller as few as 13 bits (8191). The width is granted as much space as it needs or caps the size to 18 bits. The height is given the remaining space.

This can be useful when layout constraints are possible to be extremely large, but not everything is possible to display on the device. For example a text layout where an entire chapter of a book is measured in one Layout and it isn't possible to break up the content to show in a LazyColumn.

Common

fun fitPrioritizingHeight(
            minWidth: Int,
            maxWidth: Int,
            minHeight: Int,
            maxHeight: Int,
        ): Constraints

Constraints is a value class based on a Long and 4 integers must be limited to fit within its size. The larger dimension has up to 18 bits (262,143) and the smaller as few as 13 bits (8191). The height is granted as much space as it needs or caps the size to 18 bits. The width is given the remaining space.