The Developer Preview for Android 11 is now available; test it out and share your feedback.

androidx.ui.foundation

Classes

Border

Class to specify border appearance.

DrawBackground

DrawBorder

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

Unit
AdapterList(data: List<T>, modifier: Modifier = Modifier.None, itemCallback: (T) -> Unit)

A vertically scrolling list that only composes and lays out the currently visible items.

Border
Border(size: Dp, color: Color)

Create Border class with size and Color

Unit
Box(modifier: Modifier = Modifier.None, shape: Shape = RectangleShape, backgroundColor: Color = Color.Transparent, border: Border? = null, padding: Dp = border?.size ?: 0.dp, paddingLeft: Dp = Dp.Unspecified, paddingTop: Dp = Dp.Unspecified, paddingRight: Dp = Dp.Unspecified, paddingBottom: Dp = Dp.Unspecified, gravity: ContentGravity = ContentGravity.TopLeft, children: () -> Unit)

A convenience composable that combines common layout and draw logic.

Unit
Canvas(modifier: Modifier, onCanvas: CanvasScope.() -> Unit)

Component that allow you to specify an area on the screen and perform canvas drawing on this area.

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.

DrawBackground
DrawBackground(color: Color, shape: Shape = RectangleShape)

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

DrawBackground
DrawBackground(brush: Brush, shape: Shape = RectangleShape)

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

DrawBorder
DrawBorder(border: Border, shape: Shape = RectangleShape)

Returns a Modifier that adds border with appearance specified with a border and a shape

DrawBorder
DrawBorder(size: Dp, color: Color, shape: Shape = RectangleShape)

Returns a Modifier that adds border with appearance specified with size, color and a shape

DrawBorder
DrawBorder(size: Dp, brush: Brush, shape: Shape)

Returns a Modifier that adds border with appearance specified with size, brush and a shape

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.

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(defaultBorder: Border = Border(color = Color.Black, size = Dp.Hairline), block: DrawBordersReceiver.() -> Unit)

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

Top-level functions

AdapterList

@Composable fun <T> AdapterList(
    data: List<T>,
    modifier: Modifier = Modifier.None,
    itemCallback: (T) -> Unit
): Unit

A vertically scrolling list that only composes and lays out the currently visible items.

Parameters
data: List<T> the backing list of data to display
modifier: Modifier = Modifier.None the modifier to apply to this AdapterList
itemCallback: (T) -> Unit a callback that takes an item from data and emits the UI for that item. May emit any number of components, which will be stacked vertically

Border

fun Border(
    size: Dp,
    color: Color
): Border

Create Border class with size and Color

Parameters
size: Dp size of the border in Dp. Use Dp.Hairline for one-pixel border.
color: Color color to paint the border with

Box

@Composable fun Box(
    modifier: Modifier = Modifier.None,
    shape: Shape = RectangleShape,
    backgroundColor: Color = Color.Transparent,
    border: Border? = null,
    padding: Dp = border?.size ?: 0.dp,
    paddingLeft: Dp = Dp.Unspecified,
    paddingTop: Dp = Dp.Unspecified,
    paddingRight: Dp = Dp.Unspecified,
    paddingBottom: Dp = Dp.Unspecified,
    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.

import androidx.ui.core.Text
import androidx.ui.foundation.Border
import androidx.ui.foundation.Box
import androidx.ui.layout.LayoutSize

Box(
    modifier = LayoutSize(100.dp),
    backgroundColor = Color.Cyan,
    border = Border(10.dp, Color.Red),
    shape = CircleShape,
    gravity = ContentGravity.Center
) {
    Text("I'm box")
}
Parameters
modifier: Modifier = Modifier.None The modifier to be applied to the Box
shape: Shape = RectangleShape The shape of the box
backgroundColor: Color = Color.Transparent The Color for background with. If Color.Transparent, there will be no background
border: Border? = null Border object that specifies border appearance, such as size and color. If null, there will be no border
padding: Dp = border?.size ?: 0.dp The padding to be applied inside Box, along its edges. Unless otherwise specified, content will be padded by the Border.size, if border is provided
paddingLeft: Dp = Dp.Unspecified specific padding for left side. Setting this will override padding for the left side
paddingTop: Dp = Dp.Unspecified specific padding for right side. Setting this will override padding for the top side
paddingRight: Dp = Dp.Unspecified specific padding for top side. Setting this will override padding for the right side
paddingBottom: Dp = Dp.Unspecified specific padding for bottom side. Setting this will override padding for the bottom side
gravity: ContentGravity = ContentGravity.TopLeft The gravity of the content inside Box

Canvas

@Composable fun Canvas(
    modifier: Modifier,
    onCanvas: CanvasScope.() -> Unit
): Unit

Component that allow you to specify an area on the screen and perform canvas drawing on this area. You MUST specify size with modifier, whether with exact sizes via LayoutSize modifier, or relative to parent, via LayoutSize.Fill, ColumnScope.LayoutFlexible, etc. If parent wraps this child, only exact sizes must be specified.

import androidx.compose.remember
import androidx.ui.foundation.Canvas
import androidx.ui.graphics.Paint
import androidx.ui.layout.LayoutSize
import androidx.ui.unit.toRect

val paint = remember { Paint().apply { color = Color.Magenta } }
Canvas(modifier = LayoutSize(100.dp)) {
    drawRect(size.toRect(), paint)
}
Parameters
modifier: Modifier mandatory modifier to specify size strategy for this composable
onCanvas: CanvasScope.() -> Unit lambda that will be called to perform drawing. Note that this lambda will be called during draw stage, you have no access to composition scope, meaning that Composable function invocation inside it will result to runtime exception

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.

DrawBackground

@Composable fun DrawBackground(
    color: Color,
    shape: Shape = RectangleShape
): DrawBackground

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

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

Text(
    "Text with background",
    modifier = DrawBackground(color = Color.Magenta) + LayoutPadding(10.dp)
)
Parameters
color: Color color to paint background with
shape: Shape = RectangleShape desired shape of the background

DrawBackground

@Composable fun DrawBackground(
    brush: Brush,
    shape: Shape = RectangleShape
): DrawBackground

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

import androidx.ui.core.Text
import androidx.ui.foundation.DrawBackground
import androidx.ui.foundation.shape.corner.CutCornerShape
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
)
Text(
    "Text with gradient back",
    modifier = DrawBackground(shape = CutCornerShape(8.dp), brush = gradientBrush) +
            LayoutPadding(10.dp)
)
Parameters
brush: Brush brush to paint background with
shape: Shape = RectangleShape desired shape of the background

DrawBorder

@Composable fun DrawBorder(
    border: Border,
    shape: Shape = RectangleShape
): DrawBorder

Returns a Modifier that adds border with appearance specified with a border and a shape

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

Text(
    "Text with  square border",
    modifier = DrawBorder(color = Color.Magenta, size = 4.dp) +
            LayoutPadding(10.dp)
)
()
Parameters
border: Border Border class that specifies border appearance, such as size and color
shape: Shape = RectangleShape shape of the border

DrawBorder

@Composable fun DrawBorder(
    size: Dp,
    color: Color,
    shape: Shape = RectangleShape
): DrawBorder

Returns a Modifier that adds border with appearance specified with size, color and a shape

import androidx.ui.core.Text
import androidx.ui.foundation.Border
import androidx.ui.foundation.DrawBorder
import androidx.ui.foundation.shape.corner.CutCornerShape
import androidx.ui.layout.LayoutPadding

Text(
    "Text with gradient border",
    modifier = DrawBorder(shape = CutCornerShape(8.dp), border = Border(2.dp, Color.Blue)) +
            LayoutPadding(10.dp)
)
()
Parameters
size: Dp width of the border. Use Dp.Hairline for a hairline border.
color: Color color to paint the border with
shape: Shape = RectangleShape shape of the border

DrawBorder

@Composable fun DrawBorder(
    size: Dp,
    brush: Brush,
    shape: Shape
): DrawBorder

Returns a Modifier that adds border with appearance specified with size, brush and a shape

import androidx.ui.core.Text
import androidx.ui.foundation.DrawBorder
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 gradient border",
    modifier = DrawBorder(size = 2.dp, brush = gradientBrush, shape = CircleShape) +
            LayoutPadding(10.dp)
)
()
Parameters
size: Dp width of the border. Use Dp.Hairline for a hairline border.
brush: Brush brush to paint the border with
shape: Shape shape of the border

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.

Parameters
initial: Float = 0f initial scroller position to start with

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

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

@Composable 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(
    defaultBorder: Border = Border(color = Color.Black, size = Dp.Hairline),
    block: DrawBordersReceiver.() -> Unit
): Unit

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

Example usage:

import androidx.ui.foundation.Border
import androidx.ui.foundation.ColoredRect
import androidx.ui.foundation.drawBorders
import androidx.ui.layout.LayoutAspectRatio
import androidx.ui.layout.LayoutPadding
import androidx.ui.layout.Table

Table(columns = 8) {
    drawBorders(
        defaultBorder = Border(color = Color.Red, size = 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) {
                ColoredRect(
                    color = Color.Magenta,
                    modifier = LayoutPadding(2.dp) + LayoutAspectRatio(1f)
                )
            }
        }
    }
}
Parameters
defaultBorder: Border = Border(color = Color.Black, size = Dp.Hairline) The default Border appearance to be used for borders that do not specify a style.