Android 12 Developer Preview is here! Try it out, and give us your feedback!

Constraints

@Immutable inline class Constraints
kotlin.Any
   ↳ androidx.compose.ui.unit.Constraints

Immutable constraints used for measuring layouts, usually as part of parent layouts or layout modifiers. Children layouts can be measured using the measure method on the corresponding Measurables. This method takes the Constraints, in pixels, which the child should respect. A measured child is responsible to choose and return a size which satisfies the set of Constraints received from its parent:

  • minWidth <= chosenWidth <= maxWidth
  • minHeight <= chosenHeight <= maxHeight The parent can then access the size chosen by the child on the resulting Placeable. Based on the children sizes, the parent is responsible for defining a valid positioning of the children. This means that children need to be measured with appropriate Constraints, such that whatever valid sizes children choose, they can be laid out correctly according to the parent's layout algorithm. Note that different children can be measured with different Constraints. A child is allowed to choose a size that does not satisfy its constraints. However, when this happens, the parent will not read from the placeable the real size of the child, but rather one that was coerced in the child's constraints; therefore, a parent can assume that its children will always respect the constraints in their layout algorithm. When this does not happen in reality, the position assigned to the child will be automatically offset to be centered on the space assigned by the parent under the assumption that constraints were respected. 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.

Public constructors
<init>(value: Long)

Immutable constraints used for measuring layouts, usually as part of parent layouts or layout modifiers.

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

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

String

Companion functions
Constraints
fixed(width: Int, height: Int)

Creates constraints for fixed size in both dimensions.

Constraints
fixedHeight(height: Int)

Creates constraints for fixed height and unspecified width.

Constraints
fixedWidth(width: Int)

Creates constraints for fixed width and unspecified height.

Extension functions
From androidx.compose.ui.unit
Constraints
Constraints.constrain(otherConstraints: Constraints)

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

IntSize

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

Int

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

Int

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

Boolean

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

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

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

Properties
Boolean

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

Boolean

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

Boolean

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

Boolean

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

Boolean

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

Int

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

Int

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

Int

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

Int

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

Constants

Infinity

const val Infinity: Int

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

Value: In