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
fitPrioritizingHeight(
    minWidth: Int,
    maxWidth: Int,
    minHeight: Int,
    maxHeight: Int
)

Returns Constraints that match as close as possible to the values passed.
Cmn
Constraints
fitPrioritizingWidth(
    minWidth: Int,
    maxWidth: Int,
    minHeight: Int,
    maxHeight: Int
)

Returns Constraints that match as close as possible to the values passed.
Cmn
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
restrictConstraints(
    minWidth: Int,
    maxWidth: Int,
    minHeight: Int,
    maxHeight: Int,
    prioritizeWidth: Boolean
)

This function is deprecated. Replace with fitPrioritizingWidth
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
inline Constraints

Copies the existing Constraints, setting minWidth and minHeight to 0, and preserving maxWidth and maxHeight as-is.
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

Cmn 
const val Infinity: Int

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

fitPrioritizingHeight

Cmn
Added in 1.7.0
fun fitPrioritizingHeight(
    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 height is granted as much space as it needs or caps the size to 18 bits. The width 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.

fitPrioritizingWidth

Cmn
Added in 1.7.0
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.

fixed

Cmn
Added in 1.0.0
fun fixed(width: Int, height: Int): Constraints

Creates constraints for fixed size in both dimensions.

fixedHeight

Cmn
Added in 1.0.0
fun fixedHeight(height: Int): Constraints

Creates constraints for fixed height and unspecified width.

fixedWidth

Cmn
Added in 1.0.0
fun fixedWidth(width: Int): Constraints

Creates constraints for fixed width and unspecified height.

restrictConstraints

Cmn
Added in 1.7.0
Deprecated in 1.7.0
fun restrictConstraints(
    minWidth: Int,
    maxWidth: Int,
    minHeight: Int,
    maxHeight: Int,
    prioritizeWidth: Boolean = true
): Constraints

Public constructors

Constraints

Cmn
Added in 1.2.0
Constraints(value: Long)

Public functions

copy

Cmn
Added in 1.2.0
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.

copyMaxDimensions

Cmn
Added in 1.8.0-alpha07
inline fun copyMaxDimensions(): Constraints

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

toString

Cmn 
open fun toString(): String

Public properties

hasBoundedHeight

Cmn
Added in 1.2.0
val hasBoundedHeight: Boolean

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

See also
hasBoundedWidth

hasBoundedWidth

Cmn
Added in 1.2.0
val hasBoundedWidth: Boolean

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

See also
hasBoundedHeight

hasFixedHeight

Cmn
Added in 1.2.0
val hasFixedHeight: Boolean

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

hasFixedWidth

Cmn
Added in 1.2.0
val hasFixedWidth: Boolean

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

isZero

Cmn
Added in 1.2.0
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.

maxHeight

Cmn
Added in 1.2.0
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.

maxWidth

Cmn
Added in 1.2.0
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.

minHeight

Cmn
Added in 1.2.0
val minHeight: Int

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

minWidth

Cmn
Added in 1.2.0
val minWidth: Int

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

Extension functions

constrain

Cmn 
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

Cmn 
fun Constraints.constrain(size: IntSize): IntSize

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

constrainHeight

Cmn 
fun Constraints.constrainHeight(height: Int): Int

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

constrainWidth

Cmn 
fun Constraints.constrainWidth(width: Int): Int

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

isSatisfiedBy

Cmn 
fun Constraints.isSatisfiedBy(size: IntSize): Boolean

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

offset

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

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