| name | android-compose-components |
| description | Complete catalog of Android Jetpack Compose and Material Design 3 components.
Covers M3 Expressive (2025), gesture system, graphics/drawing, navigation patterns,
theming, and mapping guidance for Crystal cross-platform UI integration via JNI.
|
| user-invocable | true |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch |
| version | 1.0.0 |
Android Jetpack Compose / Material 3 Components Reference
This document is the authoritative reference for Android Jetpack Compose and Material
Design 3 UI components as of 2025 (compose-material3 1.4.0 stable, 1.5.x alpha series).
It covers Material 3 Expressive, the full gesture system, Canvas/graphics APIs, adaptive
navigation, theming tokens, and platform-specific Android APIs. It provides implementation
priority guidance for the asset_pipeline Crystal library's Android::Renderer (JNI bridge).
The asset_pipeline maps Crystal UI::View types to native Android elements at compile
time. The Android::Renderer (in src/ui/renderers/android_renderer.cr) calls through
the JNI bridge (jni_bridge.c) to Kotlin/Java, which creates the actual View or Composable
objects. The JNI collection bridge (src/ui/native/jni_collections.cr) provides typed
wrappers for JNI references, ViewGroup batch operations, and string marshaling.
1. Overview
Material Design 3 and M3 Expressive
Material Design 3 (M3) is the current Google design system, launched alongside Android 12
(Material You). As of 2025 the system has evolved into M3 Expressive, announced at
Google I/O 2025, which adds:
- Five new component families: ButtonGroup, SplitButtonLayout, FloatingActionButtonMenu,
LoadingIndicator/WavyProgressIndicator, and Floating Toolbars
- 35 new shape definitions and shape-morphing animations
- A physics-based spring motion system replacing fixed easing curves
- Enhanced typography expressiveness
- Research backed by 46 studies and 18,000+ participants
The Jetpack Compose implementation ships in androidx.compose.material3 (latest stable
1.4.0, released September 24 2025). Experimental and expressive APIs continue in the
1.5.x alpha series.
Jetpack Compose vs Traditional Android Views
| Aspect | Jetpack Compose | Traditional Android Views |
|---|
| Paradigm | Declarative (describe what, not how) | Imperative (XML + Java/Kotlin mutations) |
| State | State<T>, MutableState<T>, remember {} | ViewModel + LiveData/StateFlow observers |
| Layout | Compose layout pass (intrinsics-based) | Measure/layout/draw pass on View hierarchy |
| Thread | Main thread, coroutines for side effects | Main thread for UI; background via Handler |
| Styling | Modifier chains, MaterialTheme | XML attributes, style resources, themes |
| Crystal JNI | Lower priority — hard to drive from native | Higher priority — jobject ViewGroup refs |
Crystal Integration: JNI Bridge Pattern
Crystal UI::View tree
|
v
Android::Renderer (src/ui/renderers/android_renderer.cr)
visit(label) / visit(button) / ...
|
v [Crystal -> C via @[Link] fun declarations]
jni_bridge.c (C wrapper functions)
|
v [C -> JVM via JNIEnv* calls]
Kotlin/Java Activity or Fragment
- Inflates Views or creates Composables
- Returns jobject back to C
|
v [back to Crystal]
NativeHandle (UI::JNI.global(env, local_ref))
stored in NativeView node
The JNI collection bridge (src/ui/native/jni_collections.cr) provides:
UI::JNI::JString — Crystal String <-> jstring marshalingUI::JNI::ObjectArray — Crystal Array <-> jobjectArrayUI::JNI::ArrayList — Crystal Array <-> java.util.ArrayListUI::JNI.viewgroup_add_views(env, parent, children) — batch addView()UI::JNI.local_frame(env, capacity) — scoped local reference tables
Critical JNI rule: Local refs are only valid within the current native method call.
Use UI::JNI.global(env, local_ref) to promote any View reference that Crystal must
hold past the return boundary, then NativeHandle tracks the lifetime.
API Level Requirements Summary
| Feature | Min API |
|---|
| All Compose basics | 21 (Android 5.0) |
| Dynamic Color (Material You) | 31 (Android 12) |
| RenderEffect / blur | 31 (Android 12) |
| RuntimeShader / AGSL | 33 (Android 13) |
| Predictive back gesture | 34 (Android 14) |
| Compose BOM 2024+ | 21 |
| WideNavigationRail | 21 (M3 Expressive, lib-based) |
| FloatingActionButtonMenu | 21 (M3 Expressive, lib-based) |
| WavyLinearProgressIndicator | 21 (M3 Expressive, lib-based) |
| Picture-in-Picture | 26 (Android 8.0) |
| Glance Widgets | 23 (Android 6.0) |
2. Material 3 Components by Category
All components require:
implementation("androidx.compose.material3:material3:1.4.0")
Experimental APIs require @OptIn(ExperimentalMaterial3Api::class).
Expressive APIs (1.5.x alpha) additionally require @OptIn(ExperimentalMaterial3ExpressiveApi::class).
2.1 Buttons and FABs
Standard Buttons
| Compose Function | Emphasis | Traditional View | Crystal UI::View Equiv. | Priority |
|---|
Button | High — filled, primary color | MaterialButton | UI::Button (maps here) | P0 (done) |
FilledButton | High — alias for Button | MaterialButton | Same as Button | P0 |
ElevatedButton | Medium — elevated surface | MaterialButton (elevation style) | — | P1 |
FilledTonalButton | Medium — secondary container fill | MaterialButton (tonal style) | — | P1 |
OutlinedButton | Low — bordered, transparent fill | MaterialButton (outlined style) | — | P1 |
TextButton | Lowest — text only | MaterialButton (text style) | — | P2 |
All button parameters:
Button(
onClick: () -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
shape: Shape = ButtonDefaults.shape, // RoundedCornerShape(50%) by default
colors: ButtonColors = ButtonDefaults.buttonColors(),
elevation: ButtonElevation? = ButtonDefaults.buttonElevation(),
border: BorderStroke? = null,
contentPadding: PaddingValues = ButtonDefaults.ContentPadding,
interactionSource: MutableInteractionSource? = null,
content: @Composable RowScope.() -> Unit
)
Icon Buttons
| Compose Function | Traditional View | Priority |
|---|
IconButton | ImageButton | P1 |
FilledIconButton | MaterialButton (icon, filled) | P2 |
FilledTonalIconButton | MaterialButton (icon, tonal) | P2 |
OutlinedIconButton | MaterialButton (icon, outlined) | P2 |
IconToggleButton | ImageButton + toggle state | P2 |
Floating Action Buttons (FABs)
| Compose Function | Size | Traditional View | Priority |
|---|
FloatingActionButton | Standard (56dp) | FloatingActionButton | P1 |
SmallFloatingActionButton | Small (40dp) | FloatingActionButton (mini) | P2 |
LargeFloatingActionButton | Large (96dp) | FloatingActionButton (large) | P2 |
ExtendedFloatingActionButton | Pill with text | ExtendedFloatingActionButton | P2 |
FAB parameters:
FloatingActionButton(
onClick: () -> Unit,
modifier: Modifier = Modifier,
shape: Shape = FloatingActionButtonDefaults.shape,
containerColor: Color = FloatingActionButtonDefaults.containerColor,
contentColor: Color = contentColorFor(containerColor),
elevation: FloatingActionButtonElevation = FloatingActionButtonDefaults.elevation(),
interactionSource: MutableInteractionSource? = null,
content: @Composable () -> Unit
)
NEW: M3 Expressive Button Components (1.4.x / 1.5.x-alpha)
| Compose Function | Description | Traditional View Equiv. | Priority |
|---|
ButtonGroup | Horizontal or vertical group of semantically related buttons with connected styling | LinearLayout of MaterialButton | P2 |
SplitButtonLayout | Two-zone button: action zone + dropdown trigger zone | Custom compound MaterialButton | P2 |
FloatingActionButtonMenu | FAB that expands into a menu of secondary actions | Custom CoordinatorLayout pattern | P2 |
ToggleFloatingActionButton | FAB with toggled (expanded/collapsed) state, used as anchor for FABMenu | FloatingActionButton | P2 |
FloatingActionButtonMenuItem | Individual item inside a FABMenu | MaterialButton in overlay | P2 |
// ButtonGroup usage (M3 Expressive)
ButtonGroup(
modifier: Modifier = Modifier,
horizontalArrangement: Arrangement.Horizontal = ButtonGroupDefaults.horizontalArrangement,
verticalAlignment: Alignment.Vertical = Alignment.CenterVertically,
content: @Composable ButtonGroupScope.() -> Unit
)
// Inside ButtonGroupScope, use Modifier.align() per-button
// FloatingActionButtonMenu usage
FloatingActionButtonMenu(
expanded: Boolean,
button: @Composable () -> Unit, // Typically a ToggleFloatingActionButton
modifier: Modifier = Modifier,
content: @Composable FloatingActionButtonMenuScope.() -> Unit
) {
FloatingActionButtonMenuItem(
onClick = { /* action */ },
icon = { Icon(Icons.Default.Share, contentDescription = null) },
text = { Text("Share") }
)
}
2.2 Selection Controls
Checkbox
| Compose Function | Traditional View | Parameters | Priority |
|---|
Checkbox | CheckBox | checked, onCheckedChange, enabled, colors | P1 |
TriStateCheckbox | CheckBox (partial state) | state: ToggleableState, onClick, enabled, colors | P2 |
Checkbox(
checked: Boolean,
onCheckedChange: ((Boolean) -> Unit)?,
modifier: Modifier = Modifier,
enabled: Boolean = true,
colors: CheckboxColors = CheckboxDefaults.colors(),
interactionSource: MutableInteractionSource? = null
)
RadioButton
| Compose Function | Traditional View | Priority |
|---|
RadioButton | RadioButton | P1 |
RadioButton has no built-in group; you track selection state in the parent composable.
Traditional equivalent for a group: RadioGroup containing RadioButton views.
RadioButton(
selected: Boolean,
onClick: (() -> Unit)?,
modifier: Modifier = Modifier,
enabled: Boolean = true,
colors: RadioButtonColors = RadioButtonDefaults.colors()
)
Switch
| Compose Function | Traditional View | Crystal UI::View Equiv. | Priority |
|---|
Switch | SwitchCompat / MaterialSwitch | — | P1 |
Switch(
checked: Boolean,
onCheckedChange: ((Boolean) -> Unit)?,
modifier: Modifier = Modifier,
thumbContent: (@Composable () -> Unit)? = null, // Icon inside thumb
enabled: Boolean = true,
colors: SwitchColors = SwitchDefaults.colors(),
interactionSource: MutableInteractionSource? = null
)
Chips
All chips require @OptIn(ExperimentalMaterial3Api::class).
| Compose Function | Use Case | Traditional View | Priority |
|---|
AssistChip | Suggest actions (non-selectable) | Chip (action chip style) | P2 |
FilterChip | Toggle-able filter selection | Chip (filter chip style) | P2 |
InputChip | Represent user input (tags, tokens) | Chip (entry chip style) | P2 |
SuggestionChip | Auto-complete suggestions | Chip (suggestion style) | P3 |
ElevatedAssistChip | Elevated variant of AssistChip | Chip elevated | P3 |
ElevatedFilterChip | Elevated variant of FilterChip | Chip elevated | P3 |
ElevatedSuggestionChip | Elevated variant | Chip elevated | P3 |
FilterChip(
selected: Boolean,
onClick: () -> Unit,
label: @Composable () -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
leadingIcon: (@Composable () -> Unit)? = null,
trailingIcon: (@Composable () -> Unit)? = null,
shape: Shape = FilterChipDefaults.shape,
colors: SelectableChipColors = FilterChipDefaults.filterChipColors(),
elevation: SelectableChipElevation? = FilterChipDefaults.filterChipElevation(),
border: BorderStroke? = FilterChipDefaults.filterChipBorder(enabled, selected)
)
SegmentedButton
| Compose Function | Traditional View | Priority |
|---|
SingleChoiceSegmentedButtonRow | Custom MaterialButton group | P2 |
MultiChoiceSegmentedButtonRow | Custom MaterialButton group | P2 |
SegmentedButton | Individual segment within row | MaterialButton |
SingleChoiceSegmentedButtonRow {
options.forEachIndexed { index, label ->
SegmentedButton(
shape = SegmentedButtonDefaults.itemShape(index = index, count = options.size),
onClick = { selectedIndex = index },
selected = index == selectedIndex,
label = { Text(label) }
)
}
}
2.3 Text Input
TextField and OutlinedTextField
| Compose Function | Traditional View | Crystal UI::View Equiv. | Priority |
|---|
TextField | TextInputEditText (filled style) | UI::TextField (maps here) | P0 (done) |
OutlinedTextField | TextInputEditText (outlined style) | — | P1 |
BasicTextField | EditText (no Material decoration) | — | P1 |
SecureTextField (1.4.0) | TextInputEditText (password) | — | P2 |
OutlinedSecureTextField (1.4.0) | TextInputEditText (password, outlined) | — | P2 |
TextField(
value: String,
onValueChange: (String) -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
readOnly: Boolean = false,
textStyle: TextStyle = LocalTextStyle.current,
label: (@Composable () -> Unit)? = null,
placeholder: (@Composable () -> Unit)? = null,
leadingIcon: (@Composable () -> Unit)? = null,
trailingIcon: (@Composable () -> Unit)? = null,
prefix: (@Composable () -> Unit)? = null,
suffix: (@Composable () -> Unit)? = null,
supportingText: (@Composable () -> Unit)? = null,
isError: Boolean = false,
visualTransformation: VisualTransformation = VisualTransformation.None,
keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
keyboardActions: KeyboardActions = KeyboardActions.Default,
singleLine: Boolean = false,
maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
minLines: Int = 1,
interactionSource: MutableInteractionSource? = null,
shape: Shape = TextFieldDefaults.shape,
colors: TextFieldColors = TextFieldDefaults.colors()
)
// SecureTextField (1.4.0) — password-only, single line only
SecureTextField(
state: TextFieldState,
modifier: Modifier = Modifier,
enabled: Boolean = true,
textObfuscationMode: TextObfuscationMode = TextObfuscationMode.RevealLastTyped,
textObfuscationCharacter: Char = '\u2022', // bullet
keyboardOptions: KeyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
onKeyboardAction: KeyboardActionHandler? = null,
shape: Shape = TextFieldDefaults.shape,
colors: TextFieldColors = TextFieldDefaults.colors(),
interactionSource: MutableInteractionSource? = null
)
SearchBar
| Compose Function | Description | Traditional View | Priority |
|---|
SearchBar | Compact search input bar | SearchView | P2 |
DockedSearchBar | Search bar anchored to top of screen | SearchView | P2 |
ExpandedFullScreenSearchBar (1.4.0) | Full-screen search overlay | SearchView full-screen | P3 |
ExpandedDockedSearchBar (1.4.0) | Docked expanded search view | SearchView | P3 |
SearchBar(
inputField: @Composable SearchBarScope.() -> Unit,
expanded: Boolean,
onExpandedChange: (Boolean) -> Unit,
modifier: Modifier = Modifier,
shape: Shape = SearchBarDefaults.inputFieldShape,
colors: SearchBarColors = SearchBarDefaults.colors(),
tonalElevation: Dp = SearchBarDefaults.TonalElevation,
shadowElevation: Dp = SearchBarDefaults.ShadowElevation,
windowInsets: WindowInsets = SearchBarDefaults.windowInsets,
content: @Composable ColumnScope.() -> Unit
)
2.4 Progress Indicators
| Compose Function | Indeterminate | Traditional View | Crystal UI::View Equiv. | Priority |
|---|
LinearProgressIndicator | Yes (no value param) | LinearProgressIndicator | — | P1 |
CircularProgressIndicator | Yes (no value param) | CircularProgressIndicator | — | P1 |
WavyLinearProgressIndicator (M3 Exp.) | Yes | Custom animated view | — | P2 |
WavyCircularProgressIndicator (M3 Exp.) | Yes | Custom animated view | — | P2 |
LoadingIndicator (M3 Exp.) | Always indeterminate | Custom animated view | — | P2 |
// Determinate (0.0 to 1.0)
LinearProgressIndicator(
progress: () -> Float,
modifier: Modifier = Modifier,
color: Color = LinearProgressIndicatorDefaults.indicatorColor,
trackColor: Color = LinearProgressIndicatorDefaults.trackColor,
strokeCap: StrokeCap = LinearProgressIndicatorDefaults.LinearStrokeCap,
gapSize: Dp = LinearProgressIndicatorDefaults.LinearIndicatorTrackGapSize,
drawStopIndicator: DrawScope.() -> Unit = { ... }
)
// Indeterminate (no progress param)
CircularProgressIndicator(
modifier: Modifier = Modifier,
color: Color = CircularProgressIndicatorDefaults.indicatorColor,
strokeWidth: Dp = CircularProgressIndicatorDefaults.StrokeWidth,
trackColor: Color = CircularProgressIndicatorDefaults.trackColor,
strokeCap: StrokeCap = CircularProgressIndicatorDefaults.IndeterminateCircularStrokeCap
)
// Wavy variants (M3 Expressive)
WavyLinearProgressIndicator(
progress: () -> Float, // or no param for indeterminate
modifier: Modifier = Modifier,
color: Color = WavyProgressIndicatorDefaults.indicatorColor,
trackColor: Color = WavyProgressIndicatorDefaults.trackColor,
amplitude: Dp = WavyProgressIndicatorDefaults.amplitude,
wavelength: Dp = WavyProgressIndicatorDefaults.wavelength,
waveSpeed: Dp = WavyProgressIndicatorDefaults.waveSpeed
)
Badge
| Compose Function | Traditional View | Priority |
|---|
Badge | Custom drawable / overlay | P2 |
BadgedBox | Custom ViewGroup with badge overlay | P2 |
BadgedBox(
badge: @Composable BoxScope.() -> Unit, // Badge() goes here
modifier: Modifier = Modifier,
content: @Composable BoxScope.() -> Unit
)
Badge(
modifier: Modifier = Modifier,
containerColor: Color = BadgeDefaults.containerColor,
contentColor: Color = contentColorFor(containerColor),
content: (@Composable RowScope.() -> Unit)? = null // null = dot badge; text = count badge
)
2.5 Dialogs and Sheets
Dialogs
| Compose Function | Traditional View | Priority |
|---|
AlertDialog | MaterialAlertDialog | P1 |
BasicAlertDialog | AlertDialog.Builder | P2 |
AlertDialog(
onDismissRequest: () -> Unit,
confirmButton: @Composable () -> Unit,
modifier: Modifier = Modifier,
dismissButton: (@Composable () -> Unit)? = null,
icon: (@Composable () -> Unit)? = null,
title: (@Composable () -> Unit)? = null,
text: (@Composable () -> Unit)? = null,
shape: Shape = AlertDialogDefaults.shape,
containerColor: Color = AlertDialogDefaults.containerColor,
iconContentColor: Color = AlertDialogDefaults.iconContentColor,
titleContentColor: Color = AlertDialogDefaults.titleContentColor,
textContentColor: Color = AlertDialogDefaults.textContentColor,
tonalElevation: Dp = AlertDialogDefaults.TonalElevation,
properties: DialogProperties = DialogProperties()
)
Bottom Sheets
| Compose Function | Traditional View | Priority |
|---|
ModalBottomSheet | BottomSheetDialog | P1 |
BottomSheetScaffold | CoordinatorLayout + BottomSheetBehavior | P2 |
ModalBottomSheet(
onDismissRequest: () -> Unit,
modifier: Modifier = Modifier,
sheetState: SheetState = rememberModalBottomSheetState(),
sheetMaxWidth: Dp = BottomSheetDefaults.SheetMaxWidth,
shape: Shape = BottomSheetDefaults.ExpandedShape,
containerColor: Color = BottomSheetDefaults.ContainerColor,
contentColor: Color = contentColorFor(containerColor),
tonalElevation: Dp = BottomSheetDefaults.Elevation,
scrimColor: Color = BottomSheetDefaults.ScrimColor,
dragHandle: (@Composable () -> Unit)? = { BottomSheetDefaults.DragHandle() },
contentWindowInsets: @Composable () -> WindowInsets = { ... },
properties: ModalBottomSheetProperties = ModalBottomSheetDefaults.properties,
content: @Composable ColumnScope.() -> Unit
)
// VerticalDragHandle (1.4.0) — visual drag indicator for bottom sheets
VerticalDragHandle(modifier: Modifier = Modifier)
2.6 Date and Time Pickers
All picker APIs require @OptIn(ExperimentalMaterial3Api::class).
| Compose Function | Traditional View | Priority |
|---|
DatePicker | MaterialDatePicker | P2 |
DateRangePicker | MaterialDateRangePicker | P2 |
DatePickerDialog | MaterialDatePicker in Dialog | P2 |
TimePicker | MaterialTimePicker (clock face) | P2 |
TimeInput | MaterialTimePicker (text input) | P2 |
TimePickerDialog (1.4.0) | MaterialTimePicker wrapper | P2 |
val datePickerState = rememberDatePickerState()
DatePickerDialog(
onDismissRequest = { },
confirmButton = { Button(onClick = { }) { Text("OK") } },
dismissButton = { TextButton(onClick = { }) { Text("Cancel") } }
) {
DatePicker(state = datePickerState)
}
// DatePickerState
// datePickerState.selectedDateMillis -> Long? (UTC epoch ms)
// datePickerState.displayedMonthMillis -> Long
val timePickerState = rememberTimePickerState(initialHour = 12, initialMinute = 0)
TimePickerDialog(
onDismissRequest = { },
onConfirm = { hour, minute -> } // TimePickerDialog is 1.4.0+
) {
TimePicker(state = timePickerState)
// or TimeInput(state = timePickerState) for keyboard input
}
2.7 Navigation Components
Bottom Navigation Bar
| Compose Function | Traditional View | Priority |
|---|
NavigationBar | BottomNavigationView | P1 |
NavigationBarItem | Menu item within BottomNavigationView | P1 |
NavigationBar(
modifier: Modifier = Modifier,
containerColor: Color = NavigationBarDefaults.containerColor,
contentColor: Color = MaterialTheme.colorScheme.contentColorFor(containerColor),
tonalElevation: Dp = NavigationBarDefaults.Elevation,
windowInsets: WindowInsets = NavigationBarDefaults.windowInsets,
content: @Composable RowScope.() -> Unit
) {
NavigationBarItem(
selected: Boolean,
onClick: () -> Unit,
icon: @Composable () -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
label: (@Composable () -> Unit)? = null,
alwaysShowLabel: Boolean = true,
colors: NavigationBarItemColors = NavigationBarItemDefaults.colors(),
interactionSource: MutableInteractionSource? = null
)
}
Navigation Rail
| Compose Function | Traditional View | Priority |
|---|
NavigationRail | NavigationRailView | P2 |
NavigationRailItem | Menu item within NavigationRailView | P2 |
WideNavigationRail (M3 Exp.) | Custom side panel | P2 |
WideNavigationRailItem (M3 Exp.) | Item within WideNavigationRail | P2 |
NavigationRail is for medium/expanded screens (tablets, landscape phones).
WideNavigationRail (M3 Expressive) is a wider modal drawer-style rail with optional header.
NavigationRail(
modifier: Modifier = Modifier,
containerColor: Color = NavigationRailDefaults.ContainerColor,
contentColor: Color = contentColorFor(containerColor),
header: (@Composable ColumnScope.() -> Unit)? = null,
windowInsets: WindowInsets = NavigationRailDefaults.windowInsets,
content: @Composable ColumnScope.() -> Unit
)
Navigation Drawers
| Compose Function | Traditional View | Priority |
|---|
ModalNavigationDrawer | DrawerLayout + NavigationView | P2 |
PermanentNavigationDrawer | Permanent side NavigationView | P3 |
DismissibleNavigationDrawer | Dismissible side NavigationView | P3 |
NavigationDrawerItem | Item within drawer | P2 |
val drawerState = rememberDrawerState(initialValue = DrawerValue.Closed)
ModalNavigationDrawer(
drawerContent = {
ModalDrawerSheet {
NavigationDrawerItem(
label = { Text("Home") },
selected = currentRoute == "home",
onClick = { /* navigate */ },
icon = { Icon(Icons.Default.Home, contentDescription = null) }
)
}
},
drawerState = drawerState,
content = { /* main content */ }
)
Adaptive Navigation (NavigationSuiteScaffold)
Requires additional dependency:
implementation("androidx.compose.material3:material3-adaptive-navigation-suite:1.5.0-alpha14")
| Compose Function | Behavior | Priority |
|---|
NavigationSuiteScaffold | Auto-selects NavigationBar/Rail/Drawer based on WindowSizeClass | P2 |
NavigationSuiteScaffold(
navigationSuiteItems = {
destinations.forEach { dest ->
item(
icon = { Icon(dest.icon, contentDescription = null) },
label = { Text(dest.label) },
selected = currentDest == dest,
onClick = { currentDest = dest }
)
}
},
content = { /* screen content */ }
)
// On compact: shows NavigationBar (bottom)
// On medium/expanded: shows NavigationRail (side)
NEW: ShortNavigationBar (M3 Expressive, 1.5.x)
A condensed navigation bar with icon-only items (no label), suitable for tight spaces.
Traditional equivalent: custom BottomNavigationView with icon-only items.
Tabs
| Compose Function | Traditional View | Priority |
|---|
TabRow | TabLayout (fixed) | P2 |
ScrollableTabRow | TabLayout (scrollable) | P2 |
Tab | Tab within TabLayout | P2 |
LeadingIconTab | Tab with leading icon | P2 |
SecondaryTabRow | Secondary-style tabs (M3 indicator style) | P3 |
TabRow(selectedTabIndex = selectedTab) {
tabs.forEachIndexed { index, title ->
Tab(
selected = selectedTab == index,
onClick = { selectedTab = index },
text = { Text(title) }
)
}
}
2.8 Top App Bars
All top app bar APIs require @OptIn(ExperimentalMaterial3Api::class).
| Compose Function | Collapse | Traditional View | Priority |
|---|
TopAppBar | No | MaterialToolbar | P1 |
CenterAlignedTopAppBar | No | MaterialToolbar (centered) | P2 |
MediumTopAppBar | Yes (title collapses to small) | CollapsingToolbarLayout (medium) | P2 |
LargeTopAppBar | Yes (large title collapses) | CollapsingToolbarLayout (large) | P2 |
TopAppBar(
title: @Composable () -> Unit,
modifier: Modifier = Modifier,
navigationIcon: @Composable () -> Unit = {},
actions: @Composable RowScope.() -> Unit = {},
expandedHeight: Dp = TopAppBarDefaults.TopAppBarExpandedHeight,
windowInsets: WindowInsets = TopAppBarDefaults.windowInsets,
colors: TopAppBarColors = TopAppBarDefaults.topAppBarColors(),
scrollBehavior: TopAppBarScrollBehavior? = null
)
// Collapsing toolbar usage
val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
LargeTopAppBar(
title = { Text("Screen Title") },
scrollBehavior = scrollBehavior
)
// + Modifier.nestedScroll(scrollBehavior.nestedScrollConnection) on the body
NEW: Floating Toolbars (M3 Expressive)
| Compose Function | Description | Traditional View | Priority |
|---|
HorizontalFloatingToolbar | Floating pill-shaped toolbar (horizontal) | Custom overlay view | P2 |
VerticalFloatingToolbar | Floating pill-shaped toolbar (vertical) | Custom overlay view | P2 |
FlexibleBottomAppBar | Bottom bar with flexible layout | BottomAppBar | P2 |
HorizontalFloatingToolbar(
expanded: Boolean,
modifier: Modifier = Modifier,
floatingActionButton: (@Composable () -> Unit)? = null, // Attached FAB
colors: FloatingToolbarColors = FloatingToolbarDefaults.standardFloatingToolbarColors(),
content: @Composable RowScope.() -> Unit
)
2.9 Cards
| Compose Function | Elevation Style | Traditional View | Crystal UI::View Equiv. | Priority |
|---|
Card | Filled (no elevation by default) | MaterialCardView | — | P2 |
ElevatedCard | Elevated (with shadow) | MaterialCardView (elevated style) | — | P2 |
OutlinedCard | Outlined border | MaterialCardView (outlined style) | — | P2 |
Card(
modifier: Modifier = Modifier,
shape: Shape = CardDefaults.shape,
colors: CardColors = CardDefaults.cardColors(),
elevation: CardElevation = CardDefaults.cardElevation(),
border: BorderStroke? = null,
content: @Composable ColumnScope.() -> Unit
)
// Clickable card — wrap with onClick
Card(onClick = { /* action */ }, ...) { ... }
2.10 Lists and Lazy Collections
ListItem
| Compose Function | Traditional View | Priority |
|---|
ListItem | MaterialListItem / custom layout | P1 |
ListItem(
headlineContent: @Composable () -> Unit,
modifier: Modifier = Modifier,
overlineContent: (@Composable () -> Unit)? = null,
supportingContent: (@Composable () -> Unit)? = null, // makes it 2-line
leadingContent: (@Composable () -> Unit)? = null,
trailingContent: (@Composable () -> Unit)? = null,
colors: ListItemColors = ListItemDefaults.colors(),
tonalElevation: Dp = ListItemDefaults.Elevation,
shadowElevation: Dp = ListItemDefaults.Elevation
)
Lazy Collections (foundation, not material3)
| Compose Function | Traditional View | Priority |
|---|
LazyColumn | RecyclerView (vertical) | P1 |
LazyRow | RecyclerView (horizontal) | P1 |
LazyVerticalGrid | RecyclerView (GridLayoutManager) | P2 |
LazyHorizontalGrid | RecyclerView (horizontal grid) | P2 |
LazyVerticalStaggeredGrid | RecyclerView (StaggeredGridLayoutManager) | P2 |
LazyHorizontalStaggeredGrid | RecyclerView (horizontal staggered) | P3 |
LazyColumn(
modifier: Modifier = Modifier,
state: LazyListState = rememberLazyListState(),
contentPadding: PaddingValues = PaddingValues(0.dp),
reverseLayout: Boolean = false,
verticalArrangement: Arrangement.Vertical = Arrangement.Top,
horizontalAlignment: Alignment.Horizontal = Alignment.Start,
flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
userScrollEnabled: Boolean = true
) {
items(itemsList) { item -> ItemComposable(item) }
item { HeaderComposable() }
itemsIndexed(list) { index, item -> IndexedItem(index, item) }
}
Carousel (material3-carousel)
Requires:
implementation("androidx.compose.material3:material3:1.4.0") // carousel included
| Compose Function | Style | Priority |
|---|
HorizontalMultiBrowseCarousel | Multiple partially-visible items | P2 |
HorizontalUncontainedCarousel | Full-width scrolling items | P2 |
HorizontalCenteredHeroCarousel (1.4.0) | Hero item centered with peeking items | P2 |
2.11 Menus and Dropdowns
| Compose Function | Traditional View | Priority |
|---|
DropdownMenu | PopupMenu | P2 |
DropdownMenuItem | MenuItem in PopupMenu | P2 |
ExposedDropdownMenuBox | AutoCompleteTextView with TextInputLayout | P2 |
var expanded by remember { mutableStateOf(false) }
ExposedDropdownMenuBox(
expanded = expanded,
onExpandedChange = { expanded = it }
) {
TextField(
value = selectedOption,
onValueChange = {},
readOnly = true,
trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
modifier = Modifier.menuAnchor()
)
ExposedDropdownMenu(
expanded = expanded,
onDismissRequest = { expanded = false }
) {
options.forEach { option ->
DropdownMenuItem(
text = { Text(option) },
onClick = { selectedOption = option; expanded = false }
)
}
}
}
NEW: Expressive Menu Components (1.5.x alpha)
M3 Expressive adds toggleable menu items, selectable menu items with supporting text,
menu groups, and menu popups as distinct first-class components (previously ad-hoc).
2.12 Sliders
| Compose Function | Traditional View | Crystal UI::View Equiv. | Priority |
|---|
Slider | Slider (from Material) | — | P1 |
RangeSlider | Custom dual-thumb Slider | — | P2 |
Slider(
value: Float,
onValueChange: (Float) -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
onValueChangeFinished: (() -> Unit)? = null,
colors: SliderColors = SliderDefaults.colors(),
interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
steps: Int = 0, // 0 = continuous; N = N+1 discrete positions
thumb: @Composable (SliderState) -> Unit = { SliderDefaults.Thumb(...) },
track: @Composable (SliderState) -> Unit = { SliderDefaults.Track(...) },
valueRange: ClosedFloatingPointRange<Float> = 0f..1f
)
2.13 Snackbars and Tooltips
Snackbar
| Compose Function | Traditional View | Priority |
|---|
Snackbar | Snackbar (from Material) | P2 |
SnackbarHost | Manages Snackbar queue + positioning | P2 |
val snackbarHostState = remember { SnackbarHostState() }
Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) { padding ->
// Launch from coroutine
LaunchedEffect(Unit) {
snackbarHostState.showSnackbar(
message = "Item deleted",
actionLabel = "Undo",
withDismissAction = true,
duration = SnackbarDuration.Long
)
}
}
Tooltips
| Compose Function | Traditional View | Priority |
|---|
PlainTooltip | Custom popup | P3 |
RichTooltip | Custom popup with title + text | P3 |
TooltipBox | Wrapper that triggers tooltip | P3 |
2.14 Dividers
| Compose Function | Traditional View | Priority |
|---|
HorizontalDivider | View with height=1dp | P2 |
VerticalDivider | View with width=1dp | P2 |
2.15 Scaffolding
Scaffold
The primary layout container for Material 3 screens.
Scaffold(
modifier: Modifier = Modifier,
topBar: @Composable () -> Unit = {},
bottomBar: @Composable () -> Unit = {},
snackbarHost: @Composable () -> Unit = {},
floatingActionButton: @Composable () -> Unit = {},
floatingActionButtonPosition: FabPosition = FabPosition.End,
containerColor: Color = MaterialTheme.colorScheme.background,
contentColor: Color = contentColorFor(containerColor),
contentWindowInsets: WindowInsets = ScaffoldDefaults.contentWindowInsets,
content: @Composable (PaddingValues) -> Unit // PaddingValues accounts for bars
)
Traditional View: CoordinatorLayout + AppBarLayout + BottomAppBar + FloatingActionButton.
Surface
The fundamental building block for Material 3 elevated/colored containers.
Surface(
modifier: Modifier = Modifier,
shape: Shape = RectangleShape,
color: Color = MaterialTheme.colorScheme.surface,
contentColor: Color = contentColorFor(color),
tonalElevation: Dp = 0.dp,
shadowElevation: Dp = 0.dp,
border: BorderStroke? = null,
content: @Composable () -> Unit
)
// Clickable Surface variant adds onClick + role params
Pull to Refresh
| Compose Function | Description | Traditional View | Priority |
|---|
PullToRefreshBox | Box with pull-to-refresh gesture | SwipeRefreshLayout | P2 |
Modifier.pullToRefresh | Low-level PTR modifier | SwipeRefreshLayout behavior | P2 |
PullToRefreshBox(
isRefreshing: Boolean,
onRefresh: () -> Unit,
modifier: Modifier = Modifier,
state: PullToRefreshState = rememberPullToRefreshState(),
contentAlignment: Alignment = Alignment.TopStart,
indicator: @Composable BoxScope.() -> Unit = {
PullToRefreshDefaults.Indicator(state, isRefreshing)
},
content: @Composable BoxScope.() -> Unit
)
3. Foundation Components
Requires: implementation("androidx.compose.foundation:foundation:$compose_version")
3.1 Layout Containers
| Composable | Description | Traditional View |
|---|
Box | Stack/overlay layout, like FrameLayout | FrameLayout |
Column | Vertical linear layout | LinearLayout(VERTICAL) |
Row | Horizontal linear layout | LinearLayout(HORIZONTAL) |
Spacer | Flexible space | View with weight |
FlowRow | Wrapping horizontal layout | FlexboxLayout (horizontal) |
FlowColumn | Wrapping vertical layout | FlexboxLayout (vertical) |
ContextualFlowRow | FlowRow with maxLines + overflow | FlexboxLayout with clipping |
ContextualFlowColumn | FlowColumn with maxLines + overflow | FlexboxLayout with clipping |
// FlowRow — wrap items onto next line when row fills
FlowRow(
modifier: Modifier = Modifier,
horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
verticalArrangement: Arrangement.Vertical = Arrangement.Top,
maxItemsInEachRow: Int = Int.MAX_VALUE,
maxLines: Int = Int.MAX_VALUE,
overflow: FlowRowOverflow = FlowRowOverflow.Clip,
content: @Composable FlowRowScope.() -> Unit
)
3.2 Text and Image
| Composable | Description | Traditional View |
|---|
BasicText | Low-level text (no Material styling) | TextView |
SelectionContainer | Makes text inside selectable | TextView with setTextIsSelectable(true) |
BasicTextField | Low-level editable text | EditText |
Image | Bitmap/vector image display | ImageView |
Icon | Material icon from painter/vector | ImageView |
Canvas | Custom 2D drawing | Custom View.onDraw() |
AndroidView | Embed traditional Android View in Compose | — |
AndroidViewBinding | Embed ViewBinding layout in Compose | — |
3.3 Interaction Modifiers
| Modifier | Description |
|---|
Modifier.clickable | Add tap interaction with ripple |
Modifier.combinedClickable | Tap + double-tap + long-press |
Modifier.selectable | Selectable state (radio group pattern) |
Modifier.toggleable | Toggleable state (checkbox pattern) |
Modifier.triStateToggleable | Three-state toggle |
Modifier.focusable | Keyboard/d-pad focus |
Modifier.indication | Custom press/hover indication |
4. Layout System
4.1 Modifier Chain
Modifiers are the primary way to configure layout, drawing, interaction, and animation
on any composable. Order matters — modifiers are applied inside-out.
Modifier
.fillMaxSize() // size
.padding(16.dp) // spacing (outside)
.background(Color.White) // drawing
.clip(RoundedCornerShape(8.dp)) // clipping
.border(1.dp, Color.Gray, RoundedCornerShape(8.dp)) // border
.padding(8.dp) // inner spacing
.clickable { } // interaction
Common size modifiers:
fillMaxSize(), fillMaxWidth(), fillMaxHeight()fillMaxSize(fraction), fillMaxWidth(fraction) — fractional fillsize(dp), size(width, height), wrapContentSize()requiredSize(dp) — override parent constraintsaspectRatio(ratio)weight(fraction) — only within Row/Column scope
4.2 Arrangement and Alignment
// Column vertical arrangement
Arrangement.Top, Arrangement.Bottom, Arrangement.Center
Arrangement.SpaceEvenly, Arrangement.SpaceBetween, Arrangement.SpaceAround
Arrangement.spacedBy(8.dp)
// Row horizontal arrangement
Arrangement.Start, Arrangement.End, Arrangement.Center
Arrangement.SpaceEvenly, Arrangement.SpaceBetween, Arrangement.SpaceAround
Arrangement.spacedBy(8.dp)
// Alignment (cross-axis)
Alignment.Start, Alignment.End, Alignment.CenterHorizontally // Column horizontal
Alignment.Top, Alignment.Bottom, Alignment.CenterVertically // Row vertical
Alignment.Center, Alignment.TopStart, Alignment.BottomEnd // Box
4.3 ConstraintLayout
Requires additional dependency:
implementation("androidx.constraintlayout:constraintlayout-compose:1.1.0")
ConstraintLayout(modifier = Modifier.fillMaxSize()) {
val (button, text) = createRefs()
Button(
onClick = {},
modifier = Modifier.constrainAs(button) {
top.linkTo(parent.top, margin = 16.dp)
start.linkTo(parent.start)
end.linkTo(parent.end)
}
) { Text("Click me") }
Text(
text = "Label",
modifier = Modifier.constrainAs(text) {
top.linkTo(button.bottom, margin = 8.dp)
centerHorizontallyTo(parent)
}
)
}
5. Gesture System
All gesture APIs live in androidx.compose.foundation and androidx.compose.ui.input.pointer.
5.1 High-Level Gesture Detectors
Applied via Modifier.pointerInput(key):
Modifier.pointerInput(Unit) {
// Each detectX function is a suspend function that loops forever
detectTapGestures(
onTap = { offset -> /* single tap */ },
onDoubleTap = { offset -> /* double tap */ },
onLongPress = { offset -> /* long press */ },
onPress = { offset ->
// Receives PointerInputChange; call tryAwaitRelease() inside
tryAwaitRelease() // suspend until finger lifts
}
)
}
Important: Multiple detectX calls cannot coexist in one pointerInput block.
Use separate Modifier.pointerInput(key) instances on the same composable.
Available Detectors
| Detector Function | Description | Traditional Equivalent |
|---|
detectTapGestures | Tap, double-tap, long-press, press | GestureDetector.OnGestureListener |
detectDragGestures | Generic drag in any direction | GestureDetector.OnGestureListener.onScroll |
detectDragGesturesAfterLongPress | Drag initiated by long-press | Custom touch handling |
detectHorizontalDragGestures | Constrained to horizontal axis | GestureDetector + custom |
detectVerticalDragGestures | Constrained to vertical axis | GestureDetector + custom |
detectTransformGestures | Pan + zoom + rotation simultaneously | ScaleGestureDetector + RotationGestureDetector |
Modifier.pointerInput(Unit) {
detectDragGestures(
onDragStart = { startOffset -> },
onDrag = { change, dragAmount ->
change.consume() // mark event as consumed
// dragAmount: Offset(dx, dy)
},
onDragEnd = { },
onDragCancel = { }
)
}
Modifier.pointerInput(Unit) {
detectTransformGestures(
panZoomLock = false,
onGesture = { centroid, pan, zoom, rotation ->
scale *= zoom
angle += rotation
offset += pan
}
)
}
5.2 Modifier-Level Gestures
| Modifier | Description | Traditional Equivalent |
|---|
Modifier.clickable | Tap with ripple + semantics | View.setOnClickListener |
Modifier.combinedClickable | Tap + double-tap + long-press | Custom GestureDetector |
Modifier.draggable | Single-axis drag (H or V) | Custom onTouchEvent |
Modifier.scrollable | Scrollable with fling support | ScrollView behavior |
Modifier.transformable | Pan/zoom/rotate via TransformableState | ScaleGestureDetector |
Modifier.swipeable (deprecated) | Swipe between anchors | Custom onTouchEvent |
Modifier.anchoredDraggable | Replaces swipeable | BottomSheetBehavior pattern |
Modifier.nestedScroll | Participate in nested scroll chain | NestedScrollingChild/Parent |
// Modifier.draggable — single axis
var offsetX by remember { mutableStateOf(0f) }
Modifier.draggable(
orientation = Orientation.Horizontal,
state = rememberDraggableState { delta -> offsetX += delta },
onDragStarted = { startedPosition -> },
onDragStopped = { velocity -> }
)
// Modifier.transformable — combined pan/zoom/rotate
var scale by remember { mutableStateOf(1f) }
var rotation by remember { mutableStateOf(0f) }
var offset by remember { mutableStateOf(Offset.Zero) }
val transformState = rememberTransformableState { zoomChange, offsetChange, rotationChange ->
scale *= zoomChange
rotation += rotationChange
offset += offsetChange
}
Modifier.transformable(state = transformState)
5.3 Low-Level Pointer Input API
For fully custom gesture logic:
Modifier.pointerInput(Unit) {
// awaitEachGesture loops, calling block for each gesture sequence
awaitEachGesture {
// Wait for first pointer down
val down = awaitFirstDown()
down.consume()
// Wait for events until all pointers are up
do {
val event = awaitPointerEvent()
event.changes.forEach { change ->
if (change.positionChanged()) {
change.consume()
}
}
} while (event.changes.any { it.pressed })
}
}
Key low-level APIs in PointerInputScope:
awaitPointerEvent(pass: PointerEventPass) — receive raw eventsawaitFirstDown(requireUnconsumed: Boolean) — wait for pressawaitTouchSlopOrCancellation(pointerId, onTouchSlopReached) — scroll slop detectionawaitDragOrCancellation(pointerId) — detect drag start
PointerEventPass controls dispatch order:
PointerEventPass.Initial — parent intercepts before childrenPointerEventPass.Main — normal; children receive before parent (default)PointerEventPass.Final — parent observes after children
5.4 VelocityTracker
Used for fling calculations in custom gesture handlers:
val velocityTracker = VelocityTracker()
Modifier.pointerInput(Unit) {
detectDragGestures(
onDrag = { change, _ ->
velocityTracker.addPointerInputChange(change)
},
onDragEnd = {
val velocity = velocityTracker.calculateVelocity()
// velocity.x, velocity.y in px/s
}
)
}
6. Graphics and Drawing
6.1 Canvas Composable
Canvas(modifier = Modifier.fillMaxSize()) {
// 'this' is DrawScope
val canvasWidth = size.width
val canvasHeight = size.height
drawLine(
color = Color.Blue,
start = Offset(0f, 0f),
end = Offset(canvasWidth, canvasHeight),
strokeWidth = 4f,
cap = StrokeCap.Round
)
}
6.2 DrawScope API
All draw operations available in DrawScope (Canvas, drawBehind, drawWithContent):
| Function | Description |
|---|
drawLine(color/brush, start, end, strokeWidth, cap, pathEffect) | Line segment |
drawRect(color/brush, topLeft, size, alpha, style) | Rectangle (fill or stroke) |
drawRoundRect(color/brush, topLeft, size, cornerRadius, style) | Rounded rectangle |
drawCircle(color/brush, radius, center, alpha, style) | Circle |
drawOval(color/brush, topLeft, size, alpha, style) | Ellipse |
drawArc(color/brush, startAngle, sweepAngle, useCenter, topLeft, size, style) | Arc |
drawPath(path, color/brush, alpha, style) | Custom path |
drawImage(image, topLeft, srcOffset, srcSize, dstOffset, dstSize, alpha, style, colorFilter, blendMode) | Bitmap |
drawText(textLayoutResult, color, topLeft, alpha) | Pre-measured text |
drawText(textMeasurer, text, topLeft, style, maxLines) | Text with inline measurement |
drawPoints(points, pointMode, color/brush, strokeWidth, cap, pathEffect, alpha, colorFilter, blendMode) | Points/lines |
inset(horizontal, vertical) { } | Translate + clip sub-scope |
rotate(degrees, pivot) { } | Rotation sub-scope |
scale(sx, sy, pivot) { } | Scale sub-scope |
translate(left, top) { } | Translation sub-scope |
clipRect(left, top, right, bottom, clipOp) { } | Clip sub-scope |
clipPath(path, clipOp) { } | Path clip sub-scope |
withTransform(block) { } | Combined transforms |
Drawing style:
// Fill (default)
style = Fill
// Stroke
style = Stroke(
width = 4f,
cap = StrokeCap.Round, // Butt, Round, Square
join = StrokeJoin.Round, // Miter, Round, Bevel
miter = 4f,
pathEffect = PathEffect.dashPathEffect(floatArrayOf(10f, 5f))
)
6.3 Brush Types
// Solid color
SolidColor(Color.Blue)
// Linear gradient
Brush.linearGradient(
colors = listOf(Color.Red, Color.Blue),
start = Offset.Zero,
end = Offset(Float.POSITIVE_INFINITY, 0f), // left-to-right
tileMode = TileMode.Clamp
)
// Radial gradient
Brush.radialGradient(
colors = listOf(Color.Yellow, Color.Red),
center = Offset(100f, 100f),
radius = 100f,
tileMode = TileMode.Clamp
)
// Sweep gradient (conic)
Brush.sweepGradient(
colors = listOf(Color.Red, Color.Green, Color.Blue),
center = Offset(100f, 100f)
)
// Colorstop variants
Brush.linearGradient(
0.0f to Color.Transparent,
0.5f to Color.Blue,
1.0f to Color.Transparent,
start = Offset.Zero,
end = Offset(Float.POSITIVE_INFINITY, 0f)
)
6.4 Path and PathEffect
val path = Path().apply {
moveTo(0f, 0f)
lineTo(100f, 0f)
quadraticBezierTo(100f, 100f, 0f, 100f)
cubicTo(50f, 150f, -50f, 150f, 0f, 0f)
close()
}
// PathEffects
PathEffect.dashPathEffect(intervals = floatArrayOf(10f, 5f), phase = 0f)
PathEffect.cornerPathEffect(radius = 10f)
PathEffect.chainPathEffect(outer = dashEffect, inner = cornerEffect)
PathEffect.stampedPathEffect(shape = stampPath, advance = 20f, phase = 0f, style = StampedPathEffectStyle.Morph)
6.5 graphicsLayer Modifier
Applies GPU-accelerated rendering effects without recomposition:
Modifier.graphicsLayer {
// Transform
scaleX = 1.2f
scaleY = 1.2f
rotationZ = 15f // degrees, around Z axis
rotationX = 0f // perspective tilt
rotationY = 0f
translationX = 0f
translationY = 0f
transformOrigin = TransformOrigin(0.5f, 0.5f) // pivot point (0..1)
// Appearance
alpha = 0.8f
shadowElevation = 8f
shape = RoundedCornerShape(16.dp)
clip = true
// Blend
compositingStrategy = CompositingStrategy.Auto
// CompositingStrategy.Offscreen — renders to offscreen buffer first (for alpha blending)
// CompositingStrategy.ModulateAlpha — multiply alpha without offscreen buffer
// RenderEffect (API 31+ / Android 12+)
renderEffect = BlurEffect(
radiusX = 8f,
radiusY = 8f,
edgeTreatment = TileMode.Decal
)
// Chain effects:
renderEffect = BlurEffect(8f, 8f).asComposeRenderEffect()
}
6.6 RenderEffect (API 31+)
// Blur
RenderEffect.createBlurEffect(radiusX, radiusY, Shader.TileMode.DECAL)
// Chain (blur then color matrix)
RenderEffect.createChainEffect(
outer = RenderEffect.createBlurEffect(8f, 8f, Shader.TileMode.CLAMP),
inner = RenderEffect.createColorFilterEffect(colorMatrix)
)
// RuntimeShader (AGSL) effect — API 33+
val agslShader = RuntimeShader(agslSource)
RenderEffect.createRuntimeShaderEffect(agslShader, "inputShader")
6.7 RuntimeShader / AGSL (API 33+ / Android 13+)
AGSL (Android Graphics Shading Language) is a subset of GLSL ES 1.0 that runs on the GPU:
// Requires API 33+
@RequiresApi(33)
fun createRippleEffect(): RuntimeShader {
val agslSource = """
uniform float2 resolution;
uniform float time;
uniform shader inputShader; // bound to the composable's rendered content
half4 main(float2 fragCoord) {
float2 uv = fragCoord / resolution;
float wave = sin(uv.x * 20.0 + time) * 0.01;
return inputShader.eval(fragCoord + float2(0.0, wave * resolution.y));
}
"""
return RuntimeShader(agslSource)
}
// Apply in graphicsLayer
val shader = remember { createRippleEffect() }
Modifier.graphicsLayer {
renderEffect = RenderEffect
.createRuntimeShaderEffect(shader, "inputShader")
.asComposeRenderEffect()
}
// Update uniforms in drawing phase:
shader.setFloatUniform("time", System.currentTimeMillis() / 1000f)
shader.setFloatUniform("resolution", width.toFloat(), height.toFloat())
Also usable as a Brush inside DrawScope:
val paint = Paint().apply {
shader = RuntimeShader(agslSource).also {
it.setFloatUniform("time", animatedTime)
}
}
drawIntoCanvas { canvas ->
canvas.drawRect(Rect(Offset.Zero, size), paint)
}
6.8 BlendMode
Used in drawBehind, drawWithContent, graphicsLayer.blendMode:
BlendMode.Clear // Erase destination
BlendMode.Src // Source only
BlendMode.Dst // Destination only
BlendMode.SrcOver // Default — source over destination
BlendMode.DstOver // Destination over source
BlendMode.SrcIn // Source where destination is opaque
BlendMode.DstIn // Destination where source is opaque
BlendMode.SrcOut // Source where destination is transparent
BlendMode.Xor // XOR of source and destination
BlendMode.Plus // Additive blend
BlendMode.Multiply // Multiply
BlendMode.Screen // Screen
BlendMode.Overlay // Overlay
BlendMode.Darken // Darken
BlendMode.Lighten // Lighten
BlendMode.ColorDodge // Color dodge
BlendMode.ColorBurn // Color burn
BlendMode.Hardlight // Hard light
BlendMode.Softlight // Soft light
BlendMode.Difference // Difference
BlendMode.Exclusion // Exclusion
BlendMode.Hue, BlendMode.Saturation, BlendMode.Color, BlendMode.Luminosity
Drawing modifiers:
Modifier.drawBehind {
// DrawScope — draw behind composable content
}
Modifier.drawWithContent {
drawContent() // draw the composable itself
// then draw on top
drawCircle(Color.Red)
}
Modifier.drawWithCache {
val path = Path() // build expensive objects once, cache across recompositions
onDrawBehind { drawPath(path, Color.Blue) }
// or onDrawWithContent { ... }
}
7. Theming System
7.1 MaterialTheme
MaterialTheme(
colorScheme: ColorScheme = MaterialTheme.colorScheme,
shapes: Shapes = MaterialTheme.shapes,
typography: Typography = MaterialTheme.typography,
content: @Composable () -> Unit
)
// Access tokens anywhere inside:
val primary = MaterialTheme.colorScheme.primary
val bodyLarge = MaterialTheme.typography.bodyLarge
val mediumShape = MaterialTheme.shapes.medium
7.2 Color Scheme — 26 Semantic Roles
M3 colors come in groups: primary, secondary, tertiary, error, neutral, and neutral-variant.
Each key color generates color, onColor, colorContainer, and onColorContainer variants.
| Token | Description |
|---|
primary | Main brand/action color |
onPrimary | Text/icons ON primary |
primaryContainer | Background for primary elements |
onPrimaryContainer | Text/icons ON primaryContainer |
inversePrimary | Primary in dark-on-light contexts |
secondary | Supporting brand color |
onSecondary | Text/icons ON secondary |
secondaryContainer | Background for secondary elements |
onSecondaryContainer | Text/icons ON secondaryContainer |
tertiary | Accent color, complementary to primary/secondary |
onTertiary | Text/icons ON tertiary |
tertiaryContainer | Background for tertiary elements |
onTertiaryContainer | Text/icons ON tertiaryContainer |
background | Default background |
onBackground | Text/icons ON background |
surface | Component surfaces (cards, sheets) |
onSurface | Text/icons ON surface |
surfaceVariant | Alternate surface (input fields) |
onSurfaceVariant | Text/icons ON surfaceVariant |
surfaceTint | Color used for tonal elevation |
inverseSurface | Background for inverted surfaces (Snackbar) |
inverseOnSurface | Text ON inverseSurface |
error | Error/destructive color |
onError | Text/icons ON error |
errorContainer | Container for error state |
onErrorContainer | Text/icons ON errorContainer |
outline | Borders, dividers |
outlineVariant | Subtle borders |
scrim | Modal scrim overlay |
Dynamic Color (API 31+)
// In your Theme composable:
@Composable
fun AppTheme(
darkTheme: Boolean = isSystemInDarkTheme(),
dynamicColor: Boolean = true, // wallpaper-based color
content: @Composable () -> Unit
) {
val colorScheme = when {
dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
val context = LocalContext.current
if (darkTheme) dynamicDarkColorScheme(context)
else dynamicLightColorScheme(context)
}
darkTheme -> DarkColorScheme
else -> LightColorScheme
}
MaterialTheme(colorScheme = colorScheme, ...) { content() }
}
7.3 Typography — 15 Styles
M3 type scale groups: display, headline, title, body, label.
Each group has Large, Medium, Small variants = 15 total styles.
| Token | Default Size | Usage |
|---|
displayLarge | 57sp, regular | Hero text, very large displays |
displayMedium | 45sp, regular | Large hero text |
displaySmall | 36sp, regular | Large decorative text |
headlineLarge | 32sp, regular | Page/section headings |
headlineMedium | 28sp, regular | Sub-section headings |
headlineSmall | 24sp, regular | Card headings |
titleLarge | 22sp, regular | App bar title, dialog title |
titleMedium | 16sp, medium (500) | List item primary text |
titleSmall | 14sp, medium (500) | List item supporting |
bodyLarge | 16sp, regular | Body copy, primary reading |
bodyMedium | 14sp, regular | Secondary body |
bodySmall | 12sp, regular | Caption, help text |
labelLarge | 14sp, medium (500) | Button labels |
labelMedium | 12sp, medium (500) | Chip labels, tab labels |
labelSmall | 11sp, medium (500) | Badge labels, overlines |
Typography(
displayLarge = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 57.sp,
lineHeight = 64.sp,
letterSpacing = (-0.25).sp
),
// ... define remaining 14 styles
)
7.4 Shape System
M3 shapes map to CornerBasedShape or RoundedCornerShape:
| Token | Default | Typical Use |
|---|
extraSmall | RoundedCornerShape(4.dp) | Chip, tooltip, menu item |
small | RoundedCornerShape(8.dp) | Button, text field |
medium | RoundedCornerShape(12.dp) | Card, dialog |
large | RoundedCornerShape(16.dp) | Bottom sheet, navigation drawer |
extraLarge | RoundedCornerShape(28.dp) | FAB (standard) |
full | CircleShape (50%) | FAB (small/large), badge |
M3 Expressive adds 35 additional shape definitions and shape morphing:
// Shape morphing between two shapes using Morph (from androidx.graphics.shapes)
val morph = Morph(startShape, endShape)
val morphedPath = morph.toPath(progress = animatedProgress)
drawPath(morphedPath, color)
7.5 Motion Tokens (M3 Expressive — MotionScheme)
M3 1.4.0 introduces MotionScheme accessed via MaterialTheme.motionScheme:
val motionScheme = MaterialTheme.motionScheme
// Standard — enters/exits the screen
motionScheme.standardEffects() // easing: StandardDecelerateInterpolator
// Emphasized — spatially moving elements, high attention
motionScheme.emphasizedEffects() // spring-based in M3 Expressive
// Fast — quick micro-interactions
motionScheme.fastEffects()
// Slow — deliberate, large transitions
motionScheme.slowEffects()
M3 Expressive replaces duration+easing motion with physics-based spring animations:
// Classic easing tokens (M3 pre-Expressive)
FastOutSlowInEasing // Standard decelerate (most common)
LinearOutSlowInEasing // Decelerate (incoming elements)
FastOutLinearInEasing // Accelerate (outgoing elements)
LinearEasing // Constant speed
// M3 Expressive spring specs (approximate token values)
spring(dampingRatio = 0.8f, stiffness = 380f) // Emphasized
spring(dampingRatio = 0.9f, stiffness = 700f) // Standard
spring(dampingRatio = 1.0f, stiffness = 1400f) // Fast (overdamped)
7.6 Elevation and Tonal Elevation
M3 uses tonal elevation (color tint) instead of shadow elevation for surface hierarchy:
| Elevation Level | Tonal Opacity | Surface Typical Use |
|---|
| Level 0 | 0% | Background |
| Level 1 | 5% | Surface tint (cards at rest) |
| Level 2 | 8% | Hovered state |
| Level 3 | 11% | Navigation drawer |
| Level 4 | 12% | App bars |
| Level 5 | 14% | Bottom sheets |
Surface(tonalElevation = 2.dp) { ... } // adds primary color tint at 8% opacity
8. Platform-Specific Android APIs
These APIs exist outside Jetpack Compose but are called from Kotlin/Java code
that Crystal bridges via JNI. They are not exposed as Composables.
8.1 Notifications
Min API: 23 (for NotificationCompat)
// NotificationCompat (recommended — handles API differences automatically)
val notification = NotificationCompat.Builder(context, CHANNEL_ID)
.setSmallIcon(R.drawable.ic_notification)
.setContentTitle("Title")
.setContentText("Body text")
.setPriority(NotificationCompat.PRIORITY_DEFAULT)
.setAutoCancel(true)
.addAction(R.drawable.ic_action, "Action Label", pendingIntent)
.setStyle(NotificationCompat.BigTextStyle().bigText("Long text..."))
.build()
// Notification channels — required on API 26+
val channel = NotificationChannel(
CHANNEL_ID,
"Channel Name",
NotificationManager.IMPORTANCE_DEFAULT
).apply {
description = "Channel description"
}
val notificationManager = context.getSystemService(NotificationManager::class.java)
notificationManager.createNotificationChannel(channel)
// Show
NotificationManagerCompat.from(context).notify(NOTIFICATION_ID, notification)
JNI bridge pattern for notifications:
- Crystal calls
notify_user(title, body) exported C function
- C function calls back via JNI to
com/pkg/CrystalLib.showNotification(String, String)
- Kotlin creates the
NotificationCompat.Builder and calls notify()
8.2 Glance Widgets
Min API: 23. Requires:
implementation("androidx.glance:glance-appwidget:1.1.0")
// Widget definition
class MyWidget : GlanceAppWidget() {
override suspend fun provideGlance(context: Context, id: GlanceId) {
provideContent {
GlanceTheme {
MyWidgetContent()
}
}
}
}
@Composable
private fun MyWidgetContent() {
// Glance composables — NOT the same as Jetpack Compose composables!
// Available: Box, Row, Column, Text, Button, Image, LazyColumn, Spacer
Column(
modifier = GlanceModifier.fillMaxSize().background(Color.White)
) {
Text(text = "Widget Title", style = TextStyle(fontSize = 18.sp))
Button(text = "Tap me", onClick = actionRunCallback<MyAction>())
}
}
// Widget receiver (registered in AndroidManifest.xml)
class MyWidgetReceiver : GlanceAppWidgetReceiver() {
override val glanceAppWidget = MyWidget()
}
// Update from outside
GlanceAppWidgetManager(context).getGlanceIds(MyWidget::class.java).forEach { id ->
MyWidget().update(context, id)
}
Important for Crystal JNI: Glance does NOT use regular Views or Compose composables.
It translates to RemoteViews internally. Crystal cannot directly drive Glance widgets
via JNI in the normal view-creation pattern. Instead, trigger updates by calling
GlanceAppWidget.update() from Kotlin and passing data via GlanceStateDefinition.
8.3 Quick Settings Tiles
Min API: 24 (API 24+ for TileService)
class MyTileService : TileService() {
override fun onTileAdded() { /* tile first added to Quick Settings */ }
override fun onTileRemoved() { /* tile removed */ }
override fun onStartListening() {
// Update tile state
qsTile.state = Tile.STATE_ACTIVE
qsTile.label = "My Feature"
qsTile.icon = Icon.createWithResource(this, R.drawable.ic_tile)
qsTile.updateTile()
}
override fun onClick() {
// Handle tile tap
qsTile.state = if (isEnabled) Tile.STATE_INACTIVE else Tile.STATE_ACTIVE
qsTile.updateTile()
}
}
// Registered in AndroidManifest with:
// <service android:name=".MyTileService"
// android:exported="true"
// android:icon="@drawable/ic_tile"
// android:label="Tile Label"
// android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
// <intent-filter>
// <action android:name="android.service.quicksettings.action.QS_TILE" />
// </intent-filter>
// </service>
8.4 Picture-in-Picture (PiP)
Min API: 26 (Android 8.0)
// Enter PiP mode
val pipParams = PictureInPictureParams.Builder()
.setAspectRatio(Rational(16, 9))
.setActions(listOf(
RemoteAction(
Icon.createWithResource(context, R.drawable.ic_play),
"Play",
"Play/Pause",
PendingIntent.getBroadcast(context, 0, Intent("com.pkg.PIP_PLAY"), PendingIntent.FLAG_IMMUTABLE)
)
))
.setAutoEnterEnabled(true) // API 31+ — auto-enter on home gesture
.setSeamlessResizeEnabled(true)
.build()
activity.enterPictureInPictureMode(pipParams)
// React to PiP mode changes in Activity
override fun onPictureInPictureModeChanged(
isInPictureInPictureMode: Boolean,
newConfig: Configuration
) {
if (isInPictureInPictureMode) {
// Simplify UI, hide chrome
} else {
// Restore full UI
}
}
In Compose, observe PiP state:
val pipMode by rememberUpdatedState(newValue = isInPictureInPictureMode())
// or use LocalPipMode from accompanist-pip
8.5 Foreground Services
Min API: 26 (for foreground service); API 34+: requires foregroundServiceType.
class MyForegroundService : Service() {
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
val notification = buildNotification()
// API 34+: must specify type matching manifest declaration
ServiceCompat.startForeground(
this,
NOTIFICATION_ID,
notification,
ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC // or MEDIA_PLAYBACK, CAMERA, etc.
)
return START_NOT_STICKY
}
override fun onBind(intent: Intent?) = null
}
// AndroidManifest.xml:
// <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
// <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" /> // API 34+
// <service android:name=".MyForegroundService"
// android:foregroundServiceType="dataSync" />
8.6 MediaSession / Media Controls
Uses androidx.media3 (preferred) or android.media.session.MediaSession.
// Recommended: androidx.media3
implementation("androidx.media3:media3-session:1.5.0")
implementation("androidx.media3:media3-exoplayer:1.5.0")
// In your Service:
val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player)
.setId("MyMediaSession")
.setCallback(object : MediaSession.Callback { /* handle transport controls */ })
.build()
// MediaSessionService auto-creates a MediaStyle notification
class MyPlaybackService : MediaSessionService() {
private var mediaSession: MediaSession? = null
override fun onCreate() {
super.onCreate()
val player = ExoPlayer.Builder(this).build()
mediaSession = MediaSession.Builder(this, player).build()
}
override fun onGetSession(controllerInfo: MediaSession.ControllerInfo) = mediaSession
override fun onDestroy() {
mediaSession?.run { player.release(); release(); mediaSession = null }
super.onDestroy()
}
}
9. Crystal Integration Priority Matrix
Mapping between Crystal UI::View, proposed new view types, Compose function,
traditional Android View, and web/HTML equivalent.
| Priority | Compose Component | Proposed Crystal UI::View | Traditional Android View | Web Equivalent |
|---|
| P0 (Done) | Text / BasicText | UI::Label | TextView | <span> |
| P0 (Done) | Button (filled) | UI::Button | MaterialButton | <button> |
| P0 (Done) | Column | UI::VStack | LinearLayout(VERTICAL) | flex-direction:column |
| P0 (Done) | Row | UI::HStack | LinearLayout(HORIZONTAL) | flex-direction:row |
| P0 (Done) | Box | UI::ZStack | FrameLayout | position:relative |
| P0 (Done) | Image | UI::Image | ImageView | <img> |
| P0 (Done) | TextField (filled) | UI::TextField | TextInputEditText | <input type="text"> |
| P0 (Done) | LazyColumn (wrapping) | UI::ScrollView | ScrollView | overflow-y:auto |
| P0 (Done) | Spacer | UI::Spacer | View with weight | flex:1 |
| — | — | — | — | — |
| P1 | Switch | UI::Toggle | SwitchCompat | <input type="checkbox"> |
| P1 | Slider | UI::Slider | Slider | <input type="range"> |
| P1 | LazyColumn | UI::List | RecyclerView | <ul> / virtual scroll |
| P1 | NavigationBar | UI::TabBar | BottomNavigationView | <nav> bottom |
| P1 | LinearProgressIndicator | UI::ProgressBar | LinearProgressIndicator | <progress> |
| P1 | CircularProgressIndicator | UI::ActivityIndicator | CircularProgressIndicator | CSS spinner |
| P1 | Scaffold | UI::Screen | CoordinatorLayout | <main> / layout |
| P1 | TopAppBar | UI::NavigationBar | MaterialToolbar | <header> |
| P1 | AlertDialog | UI::Alert | MaterialAlertDialog | <dialog> |
| P1 | ModalBottomSheet | UI::Sheet | BottomSheetDialog | CSS slide-up panel |
| P1 | Checkbox | UI::Checkbox | CheckBox | <input type="checkbox"> |
| P1 | RadioButton | UI::RadioButton | RadioButton | <input type="radio"> |
| — | — | — | — | — |
| P2 | OutlinedTextField | — | TextInputEditText (outlined) | <input> styled |
| P2 | DatePicker | UI::DatePicker | MaterialDatePicker | <input type="date"> |
| P2 | TimePicker | UI::TimePicker | MaterialTimePicker | <input type="time"> |
| P2 | ExposedDropdownMenuBox | UI::Picker | AutoCompleteTextView | <select> |
| P2 | SingleChoiceSegmentedButtonRow | UI::SegmentedControl | Custom button group | <input type="radio"> styled |
| P2 | SearchBar | UI::SearchField | SearchView | <input type="search"> |
| P2 | Snackbar + SnackbarHost | UI::Toast | Snackbar | CSS toast |
| P2 | NavigationRail | UI::SideBar | NavigationRailView | <nav> side |
| P2 | TabRow | UI::TabView | TabLayout | <div role="tablist"> |
| P2 | Card | UI::Card | MaterialCardView | <article> / <div> |
| P2 | FloatingActionButton | UI::FAB | FloatingActionButton | CSS fixed button |
| P2 | RangeSlider | UI::RangeSlider | Custom dual Slider | <input> dual-range |
| P2 | FilterChip / AssistChip | UI::Chip | Chip | <button> pill |
| P2 | HorizontalDivider | UI::Divider | View 1dp line | <hr> |
| P2 | ButtonGroup (M3 Exp.) | UI::ButtonGroup | LinearLayout of buttons | <div role="group"> |
| — | — | — | — | — |
| P3 | Canvas | UI::Canvas | Custom View.onDraw | <canvas> |
| P3 | PlainTooltip | — | Custom popup | CSS tooltip |
| P3 | MapView (external) | UI::Map | MapView (Google Maps) | <div id="map"> |
| P3 | VideoPlayer (external) | UI::VideoPlayer | VideoView / ExoPlayer | <video> |
| P3 | WideNavigationRail (M3 Exp.) | — | Custom side panel | CSS sidebar |
| P3 | FloatingActionButtonMenu (M3 Exp.) | — | Custom overlay | CSS menu |
| P3 | HorizontalMultiBrowseCarousel | — | RecyclerView (carousel) | CSS scroll snap |
| P3 | DateRangePicker | — | MaterialDateRangePicker | Custom date range UI |
| P3 | RichTooltip | — | Custom popup | CSS popover |
| P3 | NavigationSuiteScaffold | UI::AdaptiveLayout | Adaptive layout pattern | CSS media queries |
10. JNI Bridge Patterns for Crystal
10.1 Architecture Recap
Crystal (android_renderer.cr)
|
| Crystal -> C via @[Link] lib declarations
v
jni_bridge.c (C function wrappers)
|
| JNIEnv->CallVoidMethod / CallObjectMethod / etc.
v
Kotlin (CrystalViewFactory.kt or Activity)
|
v
Android View / Compose (actual UI objects)
10.2 Basic View Creation via JNI
The JNI bridge follows a consistent pattern:
Crystal side (android_renderer.cr):
{% if flag?(:android) %}
lib LibAndroidBridge
# C functions that the bridge exposes to Crystal
fun create_text_view(env : Void*, context : Void*, text : UInt8*) : Void*
fun create_material_button(env : Void*, context : Void*, text : UInt8*) : Void*
fun create_linear_layout(env : Void*, context : Void*, orientation : Int32) : Void*
fun view_set_on_click(env : Void*, view : Void*, callback_id : UInt64) : Void
fun viewgroup_add_child(env : Void*, parent : Void*, child : Void*) : Void
end
class Android::Renderer < PlatformVisitor
def initialize(@env : Void*, @context : Void*)
end
def visit(button : UI::Button) : NativeView
label_jstr = UI::JNI::JString.from_string(@env, button.label)
view_ptr = LibAndroidBridge.create_material_button(@env, @context, label_jstr.ptr)
handle = UI::JNI.global(@env, view_ptr) # promote local -> global
label_jstr.delete_local
if cb = button.on_tap
id = UI::CallbackRegistry.register(cb)
LibAndroidBridge.view_set_on_click(@env, handle.ptr, id)
end
NativeView.new(handle)
end
end
{% end %}
C bridge (jni_bridge.c):
#include <jni.h>
#include <string.h>
// Helper: get the CrystalViewFactory singleton
static jobject get_factory(JNIEnv *env) {
jclass cls = (*env)->FindClass(env, "com/pkg/CrystalViewFactory");
jmethodID get = (*env)->GetStaticMethodID(env, cls, "getInstance", "()Lcom/pkg/CrystalViewFactory;");
return (*env)->CallStaticObjectMethod(env, cls, get);
}
jobject create_material_button(JNIEnv *env, jobject context, const char *text) {
jobject factory = get_factory(env);
jclass cls = (*env)->GetObjectClass(env, factory);
jmethodID mid = (*env)->GetMethodID(env, cls, "createButton",
"(Landroid/content/Context;Ljava/lang/String;)Landroid/widget/Button;");
jstring jtext = (*env)->NewStringUTF(env, text);
jobject button = (*env)->CallObjectMethod(env, factory, mid, context, jtext);
(*env)->DeleteLocalRef(env, jtext);
return button; // local ref — caller must promote to global if stored
}
void view_set_on_click(JNIEnv *env, jobject view, uint64_t callback_id) {
jclass cls = (*env)->FindClass(env, "com/pkg/CrystalCallbackDispatcher");
jmethodID mid = (*env)->GetStaticMethodID(env, cls, "setOnClick",
"(Landroid/view/View;J)V");
(*env)->CallStaticVoidMethod(env, cls, mid, view, (jlong)callback_id);
}
Kotlin side (CrystalViewFactory.kt):
object CrystalViewFactory {
fun getInstance() = this
fun createButton(context: Context, text: String): MaterialButton {
return MaterialButton(context).apply {
this.text = text
}
}
fun createLinearLayout(context: Context, orientation: Int): LinearLayout {
return LinearLayout(context).apply {
this.orientation = orientation // LinearLayout.VERTICAL or HORIZONTAL
layoutParams = LinearLayout.LayoutParams(
LinearLayout.LayoutParams.MATCH_PARENT,
LinearLayout.LayoutParams.WRAP_CONTENT
)
}
}
fun createTextView(context: Context, text: String): TextView {
return TextView(context).apply {
this.text = text
setTextAppearance(com.google.android.material.R.style.TextAppearance_Material3_BodyLarge)
}
}
}
Callback dispatcher (CrystalCallbackDispatcher.kt):
object CrystalCallbackDispatcher {
// Called from JNI when a view event fires
@JvmStatic
external fun crystalInvokeCallback(callbackId: Long) // implemented in C
@JvmStatic
fun setOnClick(view: View, callbackId: Long) {
view.setOnClickListener { crystalInvokeCallback(callbackId) }
}
@JvmStatic
fun setOnCheckedChange(view: CompoundButton, callbackId: Long) {
view.setOnCheckedChangeListener { _, isChecked ->
// Pass boolean state through — crystalInvokeCallback needs extension
crystalInvokeCallbackBool(callbackId, isChecked)
}
}
}
10.3 Composable-Based Views via AndroidView
For Compose components not available as traditional Views (e.g., DatePicker),
embed them via ComposeView when called from Crystal:
Kotlin:
fun createDatePickerComposable(context: Context, onDateSelected: (Long) -> Unit): ComposeView {
return ComposeView(context).apply {
setContent {
MaterialTheme {
val state = rememberDatePickerState()
Column {
DatePicker(state = state)
Button(onClick = {
state.selectedDateMillis?.let { onDateSelected(it) }
}) { Text("OK") }
}
}
}
}
}
C bridge:
typedef void (*DateCallback)(long millis);
jobject create_date_picker(JNIEnv *env, jobject context, DateCallback cb) {
// Store cb in a wrapper, pass id to Kotlin
// Kotlin calls back via JNI when date confirmed
}
10.4 Property Setting Patterns
Standard JNI patterns for setting View properties:
// setText (String)
void set_text_view_text(JNIEnv *env, jobject view, const char *text) {
jclass cls = (*env)->FindClass(env, "android/widget/TextView");
jmethodID mid = (*env)->GetMethodID(env, cls, "setText", "(Ljava/lang/CharSequence;)V");
jstring jtext = (*env)->NewStringUTF(env, text);
