androidx.ui.foundation

Classes

Border

DrawBordersReceiver

Collects information about the borders specified by drawBorders when its body is executed with a DrawBordersReceiver instance as argument.

ScrollerPosition

This is the state of a VerticalScroller and HorizontalScroller that allows the developer to change the scroll position by calling methods on this object.

Type-aliases

ContentGravity

ContentPadding

Top-level functions summary

Border
Border(shape: Shape, width: Dp, color: Color)

Returns a Modifier that adds border with specified shape, width and color, which will be drawn as an inner stroke

Border
Border(shape: Shape, width: Dp, brush: Brush)

Returns a Modifier that adds border with specified shape, width and brush, which will be drawn as an inner stroke

Unit
Box(modifier: Modifier = Modifier.None, padding: ContentPadding = ContentPadding(0.dp), gravity: ContentGravity = ContentGravity.TopLeft, children: () -> Unit)

A convenience composable that combines common layout and draw logic.

Unit
Clickable(onClick: () -> Unit = null, onClickLabel: String? = null, consumeDownOnStart: Boolean = false, children: () -> Unit)

Combines PressReleasedGestureDetector and Semantics for the clickable components like Button.

Unit
ColoredRect(brush: Brush, modifier: Modifier = Modifier.None, width: Dp? = null, height: Dp? = null)

Component that represents a rectangle painted with the specified Brush.

Unit
ColoredRect(color: Color, modifier: Modifier = Modifier.None, width: Dp? = null, height: Dp? = null)

Component that represents a rectangle painted with a solid color.

Unit
DeterminateProgressIndicator(progress: Float, children: () -> Unit)

Contains the Semantics required for a determinate progress indicator, that represents progress ranging from 0.

Unit
Dialog(onCloseRequest: () -> Unit, children: () -> Unit)

Opens a dialog with the given content.

Unit
DrawImage(image: Image, tint: Color? = null)

Fits an image into the parent container while maintaining the image aspect ratio.

Unit
HorizontalScroller(scrollerPosition: ScrollerPosition = ScrollerPosition(), modifier: Modifier = Modifier.None, isScrollable: Boolean = true, child: () -> Unit)

A container that composes all of its contents and lays it out, fitting the height of the child.

Unit
ProvideContentColor(color: Color, children: () -> Unit)

Sets color as the preferred content color for children.

ScrollerPosition
ScrollerPosition(initial: Float = 0f)

Create and remember the state for a VerticalScroller or HorizontalScroller based on the currently appropriate scroll configuration to allow changing scroll position or observing scroll behavior.

Unit
SimpleImage(image: Image, tint: Color? = null)

Unit
VerticalScroller(scrollerPosition: ScrollerPosition = ScrollerPosition(), modifier: Modifier = Modifier.None, isScrollable: Boolean = true, child: () -> Unit)

A container that composes all of its contents and lays it out, fitting the width of the child.

DrawModifier
background(color: Color)

Returns a DrawModifier that fills the layout rectangle with the given background color.

DrawModifier
background(brush: Brush)

Returns a DrawModifier that fills the layout rectangle with the given background brush.

DrawModifier
background(shape: Shape, color: Color)

Returns a DrawModifier that draws shape with a solid color, with the size of the layout's rectangle.

DrawModifier
background(shape: Shape, brush: Brush)

Returns a DrawModifier that draws shape with brush, with the size of the layout's rectangle.

Color

Returns the preferred content color at the call site's position in the hierarchy.

Boolean

This effect should be used to help build responsive UIs that follow the system setting, to avoid harsh contrast changes when switching between applications.

Extension functions summary

For TableChildren
Unit
TableChildren.drawBorders(defaultBorderWidth: Dp = Dp.Hairline, defaultBorderBrush: Brush = SolidColor(Color.Black), block: DrawBordersReceiver.() -> Unit)

Adds border drawing for a Table layout, when placed inside the TableChildren block.

Top-level functions

Border

@Composable fun Border(
    shape: Shape,
    width: Dp,
    color: Color
): Border

Returns a Modifier that adds border with specified shape, width and color, which will be drawn as an inner stroke

import androidx.ui.core.Text
import androidx.ui.foundation.Border
import androidx.ui.layout.LayoutPadding

Text(
    "Text with border",
    modifier = Border(shape = CircleShape, width = 2.dp, color = Color.Red) +
            LayoutPadding(10.dp)
)
()
Parameters
shape: Shape shape of the border
width: Dp width of the border. Use Dp.Hairline for a hairline border.
color: Color color of the border

Border

@Composable fun Border(
    shape: Shape,
    width: Dp,
    brush: Brush
): Border

Returns a Modifier that adds border with specified shape, width and brush, which will be drawn as an inner stroke

import androidx.ui.core.Text
import androidx.ui.foundation.Border
import androidx.ui.graphics.HorizontalGradient
import androidx.ui.layout.LayoutPadding

val gradientBrush = HorizontalGradient(
    colors = listOf(Color.Red, Color.Blue, Color.Green),
    startX = 0.px,
    endX = 500.px,
    tileMode = TileMode.Repeated
)
Text(
    "Text with border",
    modifier = Border(shape = CircleShape, width = 2.dp, brush = gradientBrush) +
            LayoutPadding(10.dp)
)
()
Parameters
shape: Shape shape of the border
width: Dp width of the border. Use Dp.Hairline for a hairline border.
brush: Brush brush to paint the border with

Box

@Composable fun Box(
    modifier: Modifier = Modifier.None,
    padding: ContentPadding = ContentPadding(0.dp),
    gravity: ContentGravity = ContentGravity.TopLeft,
    children: () -> Unit
): Unit

A convenience composable that combines common layout and draw logic.

In order to define the size of the Box, the androidx.ui.layout.LayoutWidth, androidx.ui.layout.LayoutHeight and androidx.ui.layout.LayoutSize modifiers can be used. The Box will try to be only as small as its content. However, if it is constrained otherwise, Box will allow its content to be smaller and will position the content inside, according to gravity.

The specified padding will be applied inside the Box. In order to apply padding outside the Box, the androidx.ui.layout.LayoutPadding modifier should be used.

Parameters
modifier: Modifier = Modifier.None The modifier to be applied to the Box
padding: ContentPadding = ContentPadding(0.dp) The padding to be applied inside Box, along its edges
gravity: ContentGravity = ContentGravity.TopLeft The gravity of the content inside Box

Clickable

@Composable fun Clickable(
    onClick: () -> Unit = null,
    onClickLabel: String? = null,
    consumeDownOnStart: Boolean = false,
    children: () -> Unit
): Unit

Combines PressReleasedGestureDetector and Semantics for the clickable components like Button.

import androidx.compose.state
import androidx.ui.core.Text
import androidx.ui.foundation.Clickable

val count = state { 0 }
Clickable(onClick = { count.value += 1 }) {
    // content that you want to make clickable
    Text(text = count.toString())
}
Parameters
onClick: () -> Unit = null will be called when user clicked on the button. The children will not be clickable when it is null.
consumeDownOnStart: Boolean = false true means PressReleasedGestureDetector should consume down events. Provide false if you have some visual feedback like Ripples, as it will consume this events instead.

ColoredRect

@Composable fun ColoredRect(
    brush: Brush,
    modifier: Modifier = Modifier.None,
    width: Dp? = null,
    height: Dp? = null
): Unit

Component that represents a rectangle painted with the specified Brush.

If width and/or height are not specified, this component will expand to the corresponding max constraints received from the parent if these are finite, or to the min constraints otherwise. Note that even if width and height are specified, these will not be satisfied if the component's incoming layout constraints do not allow that.

import androidx.ui.foundation.ColoredRect
import androidx.ui.graphics.SolidColor

ColoredRect(
    brush = SolidColor(Color.Magenta),
    width = 20.dp,
    height = 20.dp
)
Parameters
brush: Brush brush to paint rect with
width: Dp? = null width of this rect, by default it will match incoming layout constraints
height: Dp? = null height of this rect, by default it will match incoming layout constraints

ColoredRect

@Composable fun ColoredRect(
    color: Color,
    modifier: Modifier = Modifier.None,
    width: Dp? = null,
    height: Dp? = null
): Unit

Component that represents a rectangle painted with a solid color.

import androidx.ui.foundation.ColoredRect

ColoredRect(Color.Cyan, width = 20.dp, height = 20.dp)
Parameters
color: Color color to paint rect with
width: Dp? = null width of this rect, by default it will match parent's constraints
height: Dp? = null height of this rect, by default it will match parent's constraints

DeterminateProgressIndicator

@Composable fun DeterminateProgressIndicator(
    progress: Float,
    children: () -> Unit
): Unit

Contains the Semantics required for a determinate progress indicator, that represents progress ranging from 0.0 to 1.0.

import androidx.ui.foundation.ColoredRect
import androidx.ui.foundation.DeterminateProgressIndicator

val progress = 0.5f // emulate progress from some state
DeterminateProgressIndicator(progress) {
    ColoredRect(Color.Cyan, height = 4.dp, width = (progress * 100).dp)
}
Parameters
progress: Float The progress of this progress indicator, where 0.0 represents no progress and 1.0 represents full progress
children: () -> Unit The progress indicator that is drawn on screen, representing progress
Exceptions
IllegalArgumentException when the progress is not within range

Dialog

@Composable fun Dialog(
    onCloseRequest: () -> Unit,
    children: () -> Unit
): Unit

Opens a dialog with the given content.

The dialog is visible as long as it is part of the composition hierarchy. In order to let the user dismiss the Dialog, the implementation of onCloseRequest should contain a way to remove to remove the dialog from the composition hierarchy.

Example usage:

import androidx.compose.state
import androidx.ui.foundation.Dialog
import androidx.ui.foundation.shape.DrawShape
import androidx.ui.layout.Container

val openDialog = state { true }
val dialogWidth = 200.dp
val dialogHeight = 50.dp

if (openDialog.value) {
    Dialog(onCloseRequest = { openDialog.value = false }) {
        // Draw a rectangle shape with rounded corners inside the dialog
        Container(width = dialogWidth, height = dialogHeight) {
            DrawShape(CircleShape, Color.White)
        }
    }
}
Parameters
onCloseRequest: () -> Unit Executes when the user tries to dismiss the Dialog.
children: () -> Unit The content to be displayed inside the dialog.

DrawImage

@Composable fun DrawImage(
    image: Image,
    tint: Color? = null
): Unit

Fits an image into the parent container while maintaining the image aspect ratio. The image will be clipped if the aspect ratios of the image and the parent don't match.

This component has the same behavior as ImageView.ScaleType.CENTER_CROP currently.

Parameters
image: Image The image to draw.
tint: Color? = null The tint color to apply for the image.

HorizontalScroller

@Composable fun HorizontalScroller(
    scrollerPosition: ScrollerPosition = ScrollerPosition(),
    modifier: Modifier = Modifier.None,
    isScrollable: Boolean = true,
    child: () -> Unit
): Unit

A container that composes all of its contents and lays it out, fitting the height of the child. If the child's width is less than the Constraints.maxWidth, the child's width is used, or the Constraints.maxWidth otherwise. If the contents don't fit the width, the drag gesture allows scrolling its content horizontally. The contents of the HorizontalScroller are clipped to the HorizontalScroller's bounds.

import androidx.ui.foundation.HorizontalScroller
import androidx.ui.layout.Row

HorizontalScroller {
    Row {
        repeat(100) { index ->
            Square(index)
        }
    }
}
If you want to control scrolling position from the code, e.g smooth scroll to position,you must own memorized instance of ScrollerPosition and then use it to call scrollTo...functions on it. Same tactic can be applied to the VerticalScroller
import androidx.compose.state
import androidx.ui.foundation.HorizontalScroller
import androidx.ui.foundation.ScrollerPosition
import androidx.ui.layout.Column
import androidx.ui.layout.Row

// Create and own ScrollerPosition to call `smoothScrollTo` later
val position = ScrollerPosition()
val scrollable = state { true }
Column {
    HorizontalScroller(
        scrollerPosition = position,
        isScrollable = scrollable.value
    ) {
        Row {
            repeat(1000) { index ->
                Square(index)
            }
        }
    }
    // Controls that will call `smoothScrollTo`, `scrollTo` or toggle `scrollable` state
    ScrollControl(position, scrollable)
}
Parameters
scrollerPosition: ScrollerPosition = ScrollerPosition() state of this Scroller that holds current scroll position and provides user with useful methods like smooth scrolling
modifier: Modifier = Modifier.None Modifier to be applied to the Scroller content layout
isScrollable: Boolean = true param to enabled or disable touch input scrolling, default is true

ProvideContentColor

@Composable fun ProvideContentColor(
    color: Color,
    children: () -> Unit
): Unit

Sets color as the preferred content color for children. This color can then be retrieved inside children by using contentColor. Typography and iconography should use this value as their default color.

ScrollerPosition

@Composable fun ScrollerPosition(initial: Float = 0f): ScrollerPosition

Create and remember the state for a VerticalScroller or HorizontalScroller based on the currently appropriate scroll configuration to allow changing scroll position or observing scroll behavior.

SimpleImage

@Composable fun SimpleImage(
    image: Image,
    tint: Color? = null
): Unit

VerticalScroller

@Composable fun VerticalScroller(
    scrollerPosition: ScrollerPosition = ScrollerPosition(),
    modifier: Modifier = Modifier.None,
    isScrollable: Boolean = true,
    child: () -> Unit
): Unit

A container that composes all of its contents and lays it out, fitting the width of the child. If the child's height is less than the Constraints.maxHeight, the child's height is used, or the Constraints.maxHeight otherwise. If the contents don't fit the height, the drag gesture allows scrolling its content vertically. The contents of the VerticalScroller are clipped to the VerticalScroller's bounds.

import androidx.ui.core.Text
import androidx.ui.foundation.VerticalScroller
import androidx.ui.layout.Column
import androidx.ui.layout.LayoutPadding
import androidx.ui.text.TextStyle

val style = TextStyle(fontSize = 30.sp)
// Scroller will be clipped to this padding
VerticalScroller {
    Column(modifier = LayoutPadding(20.dp)) {
        phrases.forEach { phrase ->
            Text(phrase, style)
        }
    }
}
Parameters
scrollerPosition: ScrollerPosition = ScrollerPosition() state of this Scroller that holds current scroll position and provides user with useful methods like smooth scrolling
modifier: Modifier = Modifier.None Modifier to be applied to the Scroller content layout
isScrollable: Boolean = true param to enabled or disable touch input scrolling, default is true

background

fun background(color: Color): DrawModifier

Returns a DrawModifier that fills the layout rectangle with the given background color.

background

fun background(brush: Brush): DrawModifier

Returns a DrawModifier that fills the layout rectangle with the given background brush.

background

fun background(
    shape: Shape,
    color: Color
): DrawModifier

Returns a DrawModifier that draws shape with a solid color, with the size of the layout's rectangle.

background

fun background(
    shape: Shape,
    brush: Brush
): DrawModifier

Returns a DrawModifier that draws shape with brush, with the size of the layout's rectangle.

contentColor

@Composable fun contentColor(): Color

Returns the preferred content color at the call site's position in the hierarchy.

This color should be used for any typography / iconography, to ensure that the color of these adjusts when the background color changes. For example, on a dark background, text should be light, and on a light background, text should be dark.

Return
the preferred content color specified by a parent, defaulting to Color.Black if unspecified.

isSystemInDarkTheme

fun isSystemInDarkTheme(): Boolean

This effect should be used to help build responsive UIs that follow the system setting, to avoid harsh contrast changes when switching between applications. The behaviour differs depending on API:

On Build.VERSION_CODES.Q and above: returns the system-wide dark theme setting.

On Build.VERSION_CODES.P and below: returns whether the device is in power saving mode or not, which can be considered analogous to dark theme for these devices.

It is also recommended to provide user accessible overrides in your application, so users can choose to force an always-light or always-dark theme. To do this, you should provide the current theme value in an ambient or similar to components further down your hierarchy, only calling this effect once at the top level if no user override has been set. This also helps avoid multiple calls to this effect, which can be expensive as it queries system configuration.

For example, to draw a white rectangle when in dark theme, and a black rectangle when in light theme:

import androidx.ui.foundation.ColoredRect
import androidx.ui.foundation.isSystemInDarkTheme
import androidx.ui.layout.Wrap

val dark = isSystemInDarkTheme()
val color = if (dark) Color.White else Color.Black
Wrap {
    ColoredRect(color = color, width = 50.dp, height = 50.dp)
}
Return
true if the system is considered to be in 'dark theme'.

Extension functions

drawBorders

fun TableChildren.drawBorders(
    defaultBorderWidth: Dp = Dp.Hairline,
    defaultBorderBrush: Brush = SolidColor(Color.Black),
    block: DrawBordersReceiver.() -> Unit
): Unit

Adds border drawing for a Table layout, when placed inside the TableChildren block.

Example usage:

import androidx.ui.foundation.ColoredRect
import androidx.ui.foundation.drawBorders
import androidx.ui.graphics.SolidColor
import androidx.ui.layout.LayoutAspectRatio
import androidx.ui.layout.Padding
import androidx.ui.layout.Table

Padding(10.dp) {
    Table(columns = 8) {
        drawBorders(
            defaultBorderBrush = SolidColor(Color.Red),
            defaultBorderWidth = 2.dp
        ) {
            outer()
            vertical(column = 2, rows = 0 until 8)
            vertical(column = 4, rows = 0 until 8)
            vertical(column = 6, rows = 0 until 8)
            horizontal(row = 2, columns = 0 until 8)
            horizontal(row = 4, columns = 0 until 8)
            horizontal(row = 6, columns = 0 until 8)
        }
        repeat(8) {
            tableRow {
                repeat(8) {
                    Padding(2.dp) {
                        ColoredRect(color = Color.Magenta, modifier = LayoutAspectRatio(1f))
                    }
                }
            }
        }
    }
}
Parameters
defaultBorderBrush: Brush = SolidColor(Color.Black) The default brush to be used for borders that do not specify a style.
defaultBorderWidth: Dp = Dp.Hairline The default width to be used for borders that do not specify a style.