{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

Constraints

value public final class 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:

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

Nested types

public static class Constraints.Companion

Constants

static final int

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

Public constructors

Constraints(long value)

Public methods

final @NonNull Constraints
copy(int minWidth, int maxWidth, int minHeight, int maxHeight)

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

final boolean

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

final boolean

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

final boolean

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

final boolean

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

final int

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

final int

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

final int

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

final int

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

final boolean

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

@NonNull String

Extension functions

final @NonNull Constraints
ConstraintsKt.constrain(
    @NonNull Constraints receiver,
    @NonNull Constraints otherConstraints
)

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

final @NonNull IntSize
ConstraintsKt.constrain(
    @NonNull Constraints receiver,
    @NonNull IntSize size
)

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

final int

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

final int

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

final boolean
ConstraintsKt.isSatisfiedBy(
    @NonNull Constraints receiver,
    @NonNull IntSize size
)

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

final @NonNull Constraints
ConstraintsKt.offset(
    @NonNull Constraints receiver,
    int horizontal,
    int vertical
)

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

Constants

Infinity

public static final int Infinity

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 constructors

Constraints

public Constraints(long value)

Public methods

copy

public final @NonNull Constraints copy(int minWidth, int maxWidth, int minHeight, int maxHeight)

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.

getHasBoundedHeight

public final boolean getHasBoundedHeight()

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

See also
hasBoundedWidth

getHasBoundedWidth

public final boolean getHasBoundedWidth()

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

See also
hasBoundedHeight

getHasFixedHeight

public final boolean getHasFixedHeight()

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

getHasFixedWidth

public final boolean getHasFixedWidth()

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

getMaxHeight

public final int getMaxHeight()

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.

getMaxWidth

public final int getMaxWidth()

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.

getMinHeight

public final int getMinHeight()

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

getMinWidth

public final int getMinWidth()

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

isZero

public final boolean isZero()

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.

toString

public @NonNull String toString()

Extension functions

ConstraintsKt.constrain

public final @NonNull Constraints ConstraintsKt.constrain(
    @NonNull Constraints receiver,
    @NonNull Constraints otherConstraints
)

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)

ConstraintsKt.constrain

public final @NonNull IntSize ConstraintsKt.constrain(
    @NonNull Constraints receiver,
    @NonNull IntSize size
)

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

ConstraintsKt.constrainHeight

public final int ConstraintsKt.constrainHeight(@NonNull Constraints receiver, int height)

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

ConstraintsKt.constrainWidth

public final int ConstraintsKt.constrainWidth(@NonNull Constraints receiver, int width)

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

ConstraintsKt.isSatisfiedBy

public final boolean ConstraintsKt.isSatisfiedBy(
    @NonNull Constraints receiver,
    @NonNull IntSize size
)

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

ConstraintsKt.offset

public final @NonNull Constraints ConstraintsKt.offset(
    @NonNull Constraints receiver,
    int horizontal,
    int vertical
)

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