androidx.ui.foundation

Classes

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.

Top-level functions summary

Unit
Clickable(onClick: () -> Unit = 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 = +memo { 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
SimpleImage(image: Image, tint: Color? = null)

Unit
VerticalScroller(scrollerPosition: ScrollerPosition = +memo { 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.

Effect<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, width = Dp.Hairline), block: DrawBordersReceiver.() -> Unit)

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

Top-level functions

Clickable

@Composable fun Clickable(
    onClick: () -> Unit = 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 = +memo { 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.memo
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 = +memo { 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 = +memo { 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

SimpleImage

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

VerticalScroller

@Composable fun VerticalScroller(
    scrollerPosition: ScrollerPosition = +memo { 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.Spacing
import androidx.ui.text.TextStyle

val style = TextStyle(fontSize = 30.sp)
// Scroller will be clipped to this padding
VerticalScroller {
    Column(modifier = Spacing(20.dp)) {
        phrases.forEach { phrase ->
            Text(text = phrase, style = style)
        }
    }
}
Parameters
scrollerPosition: ScrollerPosition = +memo { 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

isSystemInDarkTheme

fun isSystemInDarkTheme(): Effect<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, width = 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.ColoredRect
import androidx.ui.foundation.drawBorders
import androidx.ui.foundation.shape.border.Border
import androidx.ui.layout.AspectRatio
import androidx.ui.layout.Padding
import androidx.ui.layout.Table

Padding(10.dp) {
    Table(columns = 8) {
        drawBorders(
            defaultBorder = Border(color = Color.Red, width = 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 = AspectRatio(1f))
                    }
                }
            }
        }
    }
}
Parameters
defaultBorder: Border = Border(color = Color.Black, width = Dp.Hairline) The default style used for borders that do not specify a style.