surface

Functions summary

Modifier
@Composable
Modifier.surface(
    enabled: Boolean,
    shape: Shape,
    color: Color,
    contentColor: Color,
    depthEffect: SurfaceDepthEffect?,
    border: BorderStroke?,
    interactionSource: InteractionSource?
)

A surface is a fundamental building block in Glimmer.

Functions

Modifier.surface

@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: InteractionSource? = 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 implements shared visual decoration for Jetpack Compose Glimmer components:

  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.

Use surface on its own for decorative elements that cannot be interacted with by a user:

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")
}

In most cases surfaces should be interactive, to allow users to consistently move focus and navigate between components. You can use androidx.compose.foundation.focusable for focus-only surfaces, or androidx.compose.foundation.clickable and other modifiers for surfaces with actions. To ensure the surface correctly reflects the interaction states, provide the same InteractionSource to all modifiers.

For example, to create a clickable surface:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
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

val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.surface(
            // Provide the same interaction source here and to clickable to make sure that
            // surface appears focused and pressed when interacted with
            interactionSource = interactionSource
        )
        .clickable(interactionSource = interactionSource, onClick = {})
        .padding(horizontal = 24.dp, vertical = 20.dp)
) {
    Text("This is a clickable surface")
}

Similarly, to create a focusable surface:

import androidx.compose.foundation.focusable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
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

val interactionSource = remember { MutableInteractionSource() }
Box(
    Modifier.surface(
            // Provide the same interaction source here and to focusable to make sure that
            // surface appears focused when interacted with.
            interactionSource = interactionSource
        )
        .focusable(interactionSource = interactionSource)
        .padding(horizontal = 24.dp, vertical = 20.dp)
) {
    Text("This is a focusable surface")
}
Parameters
enabled: Boolean = true

controls the enabled state of this surface. When false, a disabled overlay visual will be drawn on top of the surface. Note that this only affects the visual decoration; it does not intercept input or block interaction states (such as focus or press) from the interactionSource.
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: InteractionSource? = null

the InteractionSource that emits Interactions for this surface. For interactive surfaces, the InteractionSource instance provided to this surface must be shared with the modifier responsible for emitting Interactions, such as androidx.compose.foundation.focusable or androidx.compose.foundation.clickable.