surface

Functions summary

Modifier	@Composable Modifier.surface(     focusable: Boolean,     shape: Shape,     color: Color,     contentColor: Color,     depthEffect: SurfaceDepthEffect?,     border: BorderStroke?,     interactionSource: MutableInteractionSource? ) A surface is a fundamental building block in Glimmer.
Modifier	@Composable Modifier.surface(     enabled: Boolean,     shape: Shape,     color: Color,     contentColor: Color,     depthEffect: SurfaceDepthEffect?,     border: BorderStroke?,     interactionSource: MutableInteractionSource?,     onClick: () -> Unit ) A surface is a fundamental building block in Glimmer.

Functions

Modifier.surface

Artifact: androidx.xr.glimmer:glimmer

View Source

Added in 1.0.0-alpha09

@Composable
fun Modifier.surface(
    focusable: Boolean = true,
    shape: Shape = GlimmerTheme.shapes.medium,
    color: Color = GlimmerTheme.colors.surface,
    contentColor: Color = calculateContentColor(color),
    depthEffect: SurfaceDepthEffect? = null,
    border: BorderStroke? = SurfaceDefaults.border(),
    interactionSource: MutableInteractionSource? = null
): Modifier

A surface is a fundamental building block in Glimmer. A surface represents a distinct visual area or 'physical' boundary for components such as buttons and cards. A surface is responsible for:

1. Clipping: a surface clips its children to the shape specified by shape

2. Border: a surface draws an inner border to emphasize the boundary of the component.

3. Background: a surface has a background color of color.

4. Depth effect: a surface can have different DepthEffect shadows for different states, as specified by depthEffect.

5. Content color: a surface provides a contentColor for text and icons inside the surface. By default this is calculated from the provided background color.

6. Interaction states: when focused, a surface displays draws a wider border with a focused highlight on top. When pressed, a surface draws a pressed overlay. This happens for interactions emitted from interactionSource, whether this surface is focusable or not.

This surface is focusable by default - set focusable to false for un-interactive / decorative surfaces. For handling clicks, use the other surface overload with an onClick parameter.

Simple usage:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

Box(Modifier.surface().padding(horizontal = 24.dp, vertical = 20.dp)) {
    Text("This is a surface")
}

For custom gesture handling, add the gesture modifier after this surface, and provide a shared MutableInteractionSource to enable this surface to handle focus / press states. You should also pass false for focusable if that modifier already includes a focus target by default. For example, to create a toggleable surface:

import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.selection.toggleable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

var checked by remember { mutableStateOf(false) }
val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.surface(
            // Disable focus on the surface, since toggleable is already focusable
            focusable = false,
            // Provide the same interaction source here and to toggleable to make sure that
            // surface appears focused and pressed when interacted with
            interactionSource = interactionSource,
        )
        .toggleable(
            value = checked,
            interactionSource = interactionSource,
            onValueChange = { checked = it },
        )
        .padding(horizontal = 24.dp, vertical = 20.dp)
) {
    Text("Checked: $checked")
}

Parameters
focusable: Boolean = true	whether this surface is focusable, true by default. Most surfaces should be focusable to allow navigation between surfaces in a screen. Unfocusable surfaces may be used for decorative only elements, such as surfaces used in a compound component with a separate focusable area.
shape: Shape = GlimmerTheme.shapes.medium	the Shape used to clip this surface, and also used to draw the background and border
color: Color = GlimmerTheme.colors.surface	the background Color for this surface
contentColor: Color = calculateContentColor(color)	the Color for content inside this surface
depthEffect: SurfaceDepthEffect? = null	the SurfaceDepthEffect for this surface, representing the DepthEffect shadows rendered in different states.
border: BorderStroke? = SurfaceDefaults.border()	an optional inner border for this surface
interactionSource: MutableInteractionSource? = null	an optional hoisted MutableInteractionSource for observing and emitting Interactions for this surface. Note that if null is provided, interactions will still happen internally.

Modifier.surface

Artifact: androidx.xr.glimmer:glimmer

View Source

Added in 1.0.0-alpha09

@Composable
fun Modifier.surface(
    enabled: Boolean = true,
    shape: Shape = GlimmerTheme.shapes.medium,
    color: Color = GlimmerTheme.colors.surface,
    contentColor: Color = calculateContentColor(color),
    depthEffect: SurfaceDepthEffect? = null,
    border: BorderStroke? = SurfaceDefaults.border(),
    interactionSource: MutableInteractionSource? = null,
    onClick: () -> Unit
): Modifier

A surface is a fundamental building block in Glimmer. A surface represents a distinct visual area or 'physical' boundary for components such as buttons and cards. A surface is responsible for:

1. Clipping: a surface clips its children to the shape specified by shape

2. Border: a surface draws an inner border to emphasize the boundary of the component. When focused, a surface draws a wider border with a focused highlight on top to indicate the focus state.

3. Background: a surface has a background color of color.

4. Depth effect: a surface can have different DepthEffect shadows for different states, as specified by depthEffect.

5. Content color: a surface provides a contentColor for text and icons inside the surface. By default this is calculated from the provided background color.

6. Interaction states: when focused, a surface displays draws a wider border with a focused highlight on top. When pressed, a surface draws a pressed overlay. This happens for interactions emitted from interactionSource, whether this surface is enabled or not.

This surface is focusable and handles clicks. For non-clickable surfaces, use the other overload of surface instead. For surfaces with custom gesture handling, refer to the sample and guidance on the other overload of surface.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.surface

Box(Modifier.surface(onClick = {}).padding(horizontal = 24.dp, vertical = 20.dp)) {
    Text("This is a clickable surface")
}

Parameters
enabled: Boolean = true	whether this surface is enabled, true by default. When false, this surface will not respond to user input, and will not be focusable.
shape: Shape = GlimmerTheme.shapes.medium	the Shape used to clip this surface, and also used to draw the background and border
color: Color = GlimmerTheme.colors.surface	the background Color for this surface
contentColor: Color = calculateContentColor(color)	the Color for content inside this surface
depthEffect: SurfaceDepthEffect? = null	the SurfaceDepthEffect for this surface, representing the DepthEffect shadows rendered in different states.
border: BorderStroke? = SurfaceDefaults.border()	an optional inner border for this surface
interactionSource: MutableInteractionSource? = null	an optional hoisted MutableInteractionSource for observing and emitting Interactions for this surface. Note that if null is provided, interactions will still happen internally.
onClick: () -> Unit	callback invoked when this surface is clicked