mosaic-runtime/com.jakewharton.mosaic.modifier/Modifier

Modifier

@Stable

An ordered, immutable collection of modifier elements that decorate or add behavior to Mosaic elements. For example, backgrounds, padding, and click event listeners decorate or add behavior to rows, text, or buttons.

Modifier implementations should offer a fluent factory extension function on Modifier for creating combined modifiers by starting from existing modifiers:

Modifier elements may be combined using then. Order is significant; modifier elements that appear first will be applied first.

Composables that accept a Modifier as a parameter to be applied to the whole component represented by the composable function should name the parameter modifier and assign the parameter a default value of Modifier. It should appear as the first optional parameter in the parameter list; after all required parameters (except for trailing lambda parameters) but before any other parameters with default values. Any default modifiers desired by a composable function should come after the modifier parameter's value in the composable function's implementation, keeping Modifier as the default parameter value.

The pattern above allows default modifiers to still be applied as part of the chain if a caller also supplies unrelated modifiers.

Composables that accept modifiers to be applied to a specific subcomponent foo should name the parameter fooModifier and follow the same guidelines above for default values and behavior. Subcomponent modifiers should be grouped together and follow the parent composable's modifier.

Inheritors

Element

Companion

CombinedModifier

Types

Companion

object Companion : Modifier

The companion object Modifier is the empty, default, or starter Modifier that contains no elements. Use it to create a new Modifier using modifier extension factory functions or as the default value for Modifier parameters.

Element

interface Element : Modifier

A single element contained within a Modifier chain.

Functions

all

abstract fun all(predicate: (Modifier.Element) -> Boolean): Boolean

Returns true if predicate returns true for all Elements in this Modifier or if this Modifier contains no Elements.

any

abstract fun any(predicate: (Modifier.Element) -> Boolean): Boolean

Returns true if predicate returns true for any Element in this Modifier.

aspectRatio

@Stable

fun Modifier.aspectRatio(ratio: Float, matchHeightConstraintsFirst: Boolean = false): Modifier

Attempts to size the content to match a specified aspect ratio by trying to match one of the incoming constraints in the following order: Constraints.maxWidth, Constraints.maxHeight, Constraints.minWidth, Constraints.minHeight if matchHeightConstraintsFirst is false (which is the default), or Constraints.maxHeight, Constraints.maxWidth, Constraints.minHeight, Constraints.minWidth if matchHeightConstraintsFirst is true. The size in the other dimension is determined by the aspect ratio. The combinations will be tried in this order until one non-empty is found to satisfy the constraints. If no valid size is obtained this way, it means that there is no non-empty size satisfying both the constraints and the aspect ratio, so the constraints will not be respected and the content will be sized such that the Constraints.maxWidth or Constraints.maxHeight is matched (depending on matchHeightConstraintsFirst).

background

@Stable

fun Modifier.background(color: Color): Modifier

defaultMinSize

@Stable

fun Modifier.defaultMinSize(minWidth: Int = Unspecified, minHeight: Int = Unspecified): Modifier

Constrain the size of the wrapped layout only when it would be otherwise unconstrained: the minWidth and minHeight constraints are only applied when the incoming corresponding constraint is 0. The modifier can be used, for example, to define a default min size of a component, while still allowing it to be overidden with smaller min sizes across usages.

drawBehind

fun Modifier.drawBehind(onDraw: DrawScope.() -> Unit): Modifier

fillMaxHeight

@Stable

fun Modifier.fillMaxHeight(fraction: Float = 1.0f): Modifier

Have the content fill (possibly only partially) the Constraints.maxHeight of the incoming measurement constraints, by setting the minimum height and the maximum height to be equal to the maximum height multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available height. If the incoming maximum height is Constraints.Infinity this modifier will have no effect.

fillMaxSize

@Stable

fun Modifier.fillMaxSize(fraction: Float = 1.0f): Modifier

Have the content fill (possibly only partially) the Constraints.maxWidth and Constraints.maxHeight of the incoming measurement constraints, by setting the minimum width and the maximum width to be equal to the maximum width multiplied by fraction, as well as the minimum height and the maximum height to be equal to the maximum height multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available space. If the incoming maximum width or height is Constraints.Infinity this modifier will have no effect in that dimension.

fillMaxWidth

@Stable

fun Modifier.fillMaxWidth(fraction: Float = 1.0f): Modifier

Have the content fill (possibly only partially) the Constraints.maxWidth of the incoming measurement constraints, by setting the minimum width and the maximum width to be equal to the maximum width multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available width. If the incoming maximum width is Constraints.Infinity this modifier will have no effect.

foldIn

abstract fun <R> foldIn(initial: R, operation: (R, Modifier.Element) -> R): R

Accumulates a value starting with initial and applying operation to the current value and each element from outside in.

foldOut

abstract fun <R> foldOut(initial: R, operation: (Modifier.Element, R) -> R): R

Accumulates a value starting with initial and applying operation to the current value and each element from inside out.

height

@Stable

fun Modifier.height(height: Int): Modifier

Declare the preferred height of the content to be exactly height. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

heightIn

@Stable

fun Modifier.heightIn(min: Int = Unspecified, max: Int = Unspecified): Modifier

Constrain the height of the content to be between min and max as permitted by the incoming measurement Constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

layout

fun Modifier.layout(measure: MeasureScope.(Measurable, Constraints) -> MeasureResult): Modifier

Creates a LayoutModifier that allows changing how the wrapped element is measured and laid out.

offset

fun Modifier.offset(offset: () -> IntOffset): Modifier

Offset the content by offset. The offsets can be positive as well as non-positive. Applying an offset only changes the position of the content, without interfering with its size measurement.

@Stable

fun Modifier.offset(x: Int = 0, y: Int = 0): Modifier

Offset the content by (x, y). The offsets can be positive as well as non-positive. Applying an offset only changes the position of the content, without interfering with its size measurement.

onKeyEvent

fun Modifier.onKeyEvent(onKeyEvent: (event: KeyEvent) -> Boolean): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept key events.

onPreviewKeyEvent

fun Modifier.onPreviewKeyEvent(onPreviewKeyEvent: (event: KeyEvent) -> Boolean): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept key events.

padding

@Stable

fun Modifier.padding(all: Int): Modifier

@Stable

fun Modifier.padding(horizontal: Int = 0, vertical: Int = 0): Modifier

@Stable

fun Modifier.padding(left: Int = 0, top: Int = 0, right: Int = 0, bottom: Int = 0): Modifier

requiredHeight

@Stable

fun Modifier.requiredHeight(height: Int): Modifier

Declare the height of the content to be exactly height. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredHeightIn

@Stable

fun Modifier.requiredHeightIn(min: Int = Unspecified, max: Int = Unspecified): Modifier

Constrain the height of the content to be between min and max. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredSize

@Stable

fun Modifier.requiredSize(size: IntSize): Modifier

Declare the size of the content to be exactly size. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

@Stable

fun Modifier.requiredSize(size: Int): Modifier

Declare the size of the content to be exactly size width and height. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

@Stable

fun Modifier.requiredSize(width: Int, height: Int): Modifier

Declare the size of the content to be exactly width and height. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredSizeIn

@Stable

fun Modifier.requiredSizeIn(minWidth: Int = Unspecified, minHeight: Int = Unspecified, maxWidth: Int = Unspecified, maxHeight: Int = Unspecified): Modifier

Constrain the width of the content to be between minWidth and maxWidth, and the height of the content to be between minHeight and maxHeight. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredWidth

@Stable

fun Modifier.requiredWidth(width: Int): Modifier

Declare the width of the content to be exactly width. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredWidthIn

@Stable

fun Modifier.requiredWidthIn(min: Int = Unspecified, max: Int = Unspecified): Modifier

Constrain the width of the content to be between min and max. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

size

@Stable

fun Modifier.size(size: IntSize): Modifier

Declare the preferred size of the content to be exactly size. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

@Stable

fun Modifier.size(size: Int): Modifier

Declare the preferred size of the content to be exactly size square. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

@Stable

fun Modifier.size(width: Int, height: Int): Modifier

Declare the preferred size of the content to be exactly width by height. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

sizeIn

@Stable

fun Modifier.sizeIn(minWidth: Int = Unspecified, minHeight: Int = Unspecified, maxWidth: Int = Unspecified, maxHeight: Int = Unspecified): Modifier

Constrain the width of the content to be between minWidth and maxWidth and the height of the content to be between minHeight and maxHeight as permitted by the incoming measurement Constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

then

open infix fun then(other: Modifier): Modifier

Concatenates this modifier with another.

width

@Stable

fun Modifier.width(width: Int): Modifier

Declare the preferred width of the content to be exactly width. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

widthIn

@Stable

fun Modifier.widthIn(min: Int = Unspecified, max: Int = Unspecified): Modifier

Constrain the width of the content to be between min and max as permitted by the incoming measurement Constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

wrapContentHeight

@Stable

fun Modifier.wrapContentHeight(align: Alignment.Vertical = Alignment.CenterVertically, unbounded: Boolean = false): Modifier

Allow the content to measure at its desired height without regard for the incoming measurement minimum height constraint, and, if unbounded is true, also without regard for the incoming measurement maximum height constraint. If the content's measured size is smaller than the minimum height constraint, align it within that minimum height space. If the content's measured size is larger than the maximum height constraint (only possible when unbounded is true), align over the maximum height space.

wrapContentSize

@Stable

fun Modifier.wrapContentSize(align: Alignment = Alignment.Center, unbounded: Boolean = false): Modifier

Allow the content to measure at its desired size without regard for the incoming measurement minimum width or minimum height constraints, and, if unbounded is true, also without regard for the incoming maximum constraints. If the content's measured size is smaller than the minimum size constraint, align it within that minimum sized space. If the content's measured size is larger than the maximum size constraint (only possible when unbounded is true), align within the maximum space.

wrapContentWidth

@Stable

fun Modifier.wrapContentWidth(align: Alignment.Horizontal = Alignment.CenterHorizontally, unbounded: Boolean = false): Modifier

Allow the content to measure at its desired width without regard for the incoming measurement minimum width constraint, and, if unbounded is true, also without regard for the incoming measurement maximum width constraint. If the content's measured size is smaller than the minimum width constraint, align it within that minimum width space. If the content's measured size is larger than the maximum width constraint (only possible when unbounded is true), align over the maximum width space.