Constraints


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.

Summary

Constants

const Int

A value that maxWidth or maxHeight will be set to when the constraint should be considered infinite.

Cmn

Public companion functions

Constraints
fixed(width: Int, height: Int)

Creates constraints for fixed size in both dimensions.

Cmn
Constraints
fixedHeight(height: Int)

Creates constraints for fixed height and unspecified width.

Cmn
Constraints
fixedWidth(width: Int)

Creates constraints for fixed width and unspecified height.

Cmn
Constraints
restrictedConstraints(
    minWidth: Int,
    maxWidth: Int,
    minHeight: Int,
    maxHeight: Int,
    prioritizeWidth: Boolean
)

Returns Constraints that match as close as possible to the values passed.

Cmn

Public constructors

Constraints(value: Long)
Cmn

Public functions

Constraints
copy(minWidth: Int, maxWidth: Int, minHeight: Int, maxHeight: Int)

Copies the existing Constraints, replacing some of minWidth, minHeight, maxWidth, or maxHeight as desired.

Cmn
open String
Cmn

Public properties

Boolean

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

Cmn
Boolean

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

Cmn
Boolean

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

Cmn
Boolean

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

Cmn
Boolean

Whether the area of a component respecting these constraints will definitely be 0.

Cmn
Int

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

Cmn
Int

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

Cmn
Int

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

Cmn
Int

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

Cmn

Extension functions

Constraints
Constraints.constrain(otherConstraints: Constraints)

Takes otherConstraints and returns the result of coercing them in the current constraints.

Cmn
IntSize

Takes a size and returns the closest size to it that satisfies the constraints.

Cmn
Int

Takes a height and returns the closest size to it that satisfies the constraints.

Cmn
Int

Takes a width and returns the closest size to it that satisfies the constraints.

Cmn
Boolean

Takes a size and returns whether it satisfies the current constraints.

Cmn
Constraints
Constraints.offset(horizontal: Int, vertical: Int)

Returns the Constraints obtained by offsetting the current instance with the given values.

Cmn

Constants

Infinity

const val InfinityInt

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.

Public companion functions

fixed

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

Creates constraints for fixed size in both dimensions.

fixedHeight

fun fixedHeight(height: Int): Constraints

Creates constraints for fixed height and unspecified width.

fixedWidth

fun fixedWidth(width: Int): Constraints

Creates constraints for fixed width and unspecified height.

restrictedConstraints

fun restrictedConstraints(
    minWidth: Int,
    maxWidth: Int,
    minHeight: Int,
    maxHeight: Int,
    prioritizeWidth: Boolean = true
): 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.

When prioritizeWidth is true, minWidth and maxWidth are given priority in what can be represented, allowing them up to 18 bits of size, if needed. If prioritizeWidth is false, minHeight and maxHeight are given priority, allowing for up to 18 bits if needed.

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.

Public constructors

Constraints

Constraints(value: Long)

Public functions

copy

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.

toString

open fun toString(): String

Public properties

hasBoundedHeight

val hasBoundedHeightBoolean

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

See also
hasBoundedWidth

hasBoundedWidth

val hasBoundedWidthBoolean

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

See also
hasBoundedHeight

hasFixedHeight

val hasFixedHeightBoolean

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

hasFixedWidth

val hasFixedWidthBoolean

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

isZero

val isZeroBoolean

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.

maxHeight

val maxHeightInt

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.

maxWidth

val maxWidthInt

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.

minHeight

val minHeightInt

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

minWidth

val minWidthInt

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

Extension functions

constrain

fun Constraints.constrain(otherConstraints: Constraints): Constraints

Takes otherConstraints and returns the result of coercing them in the current constraints. Note this means that any size satisfying the resulting constraints will satisfy the current constraints, but they might not satisfy the otherConstraints when the two set of constraints are disjoint. Examples (showing only width, height works the same): (minWidth=2, maxWidth=10).constrain(minWidth=7, maxWidth=12) -> (minWidth = 7, maxWidth = 10) (minWidth=2, maxWidth=10).constrain(minWidth=11, maxWidth=12) -> (minWidth=10, maxWidth=10) (minWidth=2, maxWidth=10).constrain(minWidth=5, maxWidth=7) -> (minWidth=5, maxWidth=7)

constrain

fun Constraints.constrain(size: IntSize): IntSize

Takes a size and returns the closest size to it that satisfies the constraints.

constrainHeight

fun Constraints.constrainHeight(height: Int): Int

Takes a height and returns the closest size to it that satisfies the constraints.

constrainWidth

fun Constraints.constrainWidth(width: Int): Int

Takes a width and returns the closest size to it that satisfies the constraints.

isSatisfiedBy

fun Constraints.isSatisfiedBy(size: IntSize): Boolean

Takes a size and returns whether it satisfies the current constraints.

fun Constraints.offset(horizontal: Int = 0, vertical: Int = 0): Constraints

Returns the Constraints obtained by offsetting the current instance with the given values.