Constraints
@Immutable inline class Constraints
kotlin.Any | |
↳ | androidx.compose.ui.unit.Constraints |
Immutable constraints used for measuring child Layouts or LayoutModifiers. A parent layout can measure their children using the measure method on the corresponding Measurables, method which takes the Constraints the child has to follow. A measured child is then responsible to choose for themselves and return a size which satisfies the set of Constraints received from their parent:
- minWidth <= chosenWidth <= maxWidth
- minHeight <= chosenHeight <= maxHeight The parent can then access the child chosen size on the resulting Placeable. The parent is responsible of defining a valid positioning of the children according to their sizes, so the parent needs to measure the children with appropriate Constraints, such that whatever valid sizes children choose, they can be laid out in a way that also respects the parent's incoming Constraints. 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 | |
---|---|
Immutable constraints used for measuring child Layouts or LayoutModifiers. |
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 |
toString() |
Companion functions | |
---|---|
Constraints |
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
|
Properties | |
---|---|
Boolean |
|
Boolean |
|
Int |
The maximum height that the measurement can take. |
Int |
The maximum width that the measurement can take. |
Int |
The minimum height that the measurement can take. |
Int |
The minimum width that the measurement can take. |
Extension properties | ||||||
---|---|---|---|---|---|---|
From androidx.compose.ui.unit
|
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: Int.MAX_VALUE
Public constructors
<init>
Constraints(value: Long)
Immutable constraints used for measuring child Layouts or LayoutModifiers. A parent layout can measure their children using the measure method on the corresponding Measurables, method which takes the Constraints the child has to follow. A measured child is then responsible to choose for themselves and return a size which satisfies the set of Constraints received from their parent:
- minWidth <= chosenWidth <= maxWidth
- minHeight <= chosenHeight <= maxHeight The parent can then access the child chosen size on the resulting Placeable. The parent is responsible of defining a valid positioning of the children according to their sizes, so the parent needs to measure the children with appropriate Constraints, such that whatever valid sizes children choose, they can be laid out in a way that also respects the parent's incoming Constraints. 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.
Public methods
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
fun toString(): String
Properties
hasBoundedHeight
val hasBoundedHeight: Boolean
false
when maxHeight is Infinity and true
if maxWidth is a non-Infinity value.
See Also
hasBoundedWidth
val hasBoundedWidth: Boolean
false
when maxWidth is Infinity and true
if maxWidth is a non-Infinity value.
See Also
maxHeight
val maxHeight: Int
The maximum height that the measurement can take. This will either be a positive value greater than or equal to minHeight or Constraints.Infinity.
maxWidth
val maxWidth: Int
The maximum width that the measurement can take. This will either be a positive value greater than or equal to minWidth or Constraints.Infinity.
Companion functions
fixed
@Stable fun fixed(
width: Int,
height: Int
): Constraints
Creates constraints for fixed size in both dimensions.
fixedHeight
@Stable fun fixedHeight(height: Int): Constraints
Creates constraints for fixed height and unspecified width.
fixedWidth
@Stable fun fixedWidth(width: Int): Constraints
Creates constraints for fixed width and unspecified height.