ComposeUiHost


Connects a hosted Compose UI hierarchy to the Android View system.

A host supplies the platform environment that a Compose hierarchy needs (its View, density, layoutDirection, coordinate transforms, graphics, and input method), and receives callbacks from the hierarchy when it needs to be measured or drawn, when focus moves across its boundary, when embedded Android Views are added or removed, and when its layout or semantics change.

The host drives the hierarchy from the View system: it measures the hierarchy from View.onMeasure, lays it out from View.onLayout with the final size, and draws it from View.dispatchDraw. Drawing flushes any pending measure and layout first.

All members are called on the UI thread that owns view, and implementations must call into the hierarchy on that thread. This need not be the main thread.

Summary

Public functions

Unit
addAndroidView(
    view: View,
    semanticsId: Int,
    invalidateMeasurement: () -> Unit
)

Adds an embedded Android View to the host.

android
Unit

Called when Compose focus was cleared.

android
Unit
drawAndroidView(view: View, canvas: Canvas)

Draws an embedded Android View previously added with addAndroidView into canvas.

android
Unit

Called when the hosted content needs to be drawn again.

android
Unit

Called when the hosted content needs to be measured and laid out again.

android
Offset
localToScreen(relativeToLocal: Offset)

Converts relativeToLocal, a position relative to the hosted content's root, to a position relative to the device's screen.

android
Unit
<T : ObservationTarget> observeReads(
    target: T,
    onChanged: (T) -> Unit,
    block: () -> Unit
)

Executes block, observing the snapshot state it reads, and calls onChanged with target when any of that state changes.

android
Unit

Called when the content of node asks to show autofill suggestions.

android
Unit

Called after a batch of composition changes was applied to the hosted content.

android
Unit
onFocusChanged(previous: LayoutInfo?, current: LayoutInfo?)

Called when Compose focus moved from previous to current.

android
Unit

Called when the size, position, or layer of node changed.

android
Unit

Called after node joins the hosted content.

android
Unit

Called when node is deactivated: kept in the hosted content for later reuse, without content.

android
Unit

Called after node leaves the hosted content.

android
Unit
onNodeReused(node: LayoutInfo, previousSemanticsId: Int)

Called when node is reused for different content.

android
Unit
onSemanticsChanged(
    node: LayoutInfo,
    previousConfig: SemanticsPropertyProvider?
)

Called when the semantics of node changed.

android
Unit
removeAndroidView(view: View, semanticsId: Int)

Removes an embedded Android View previously added with addAndroidView.

android
Boolean
requestHostFocus(
    focusDirection: FocusDirection,
    previouslyFocusedRect: Rect?
)

Called when Compose content requests focus while view does not have framework focus.

android
Offset
screenToLocal(relativeToScreen: Offset)

Converts relativeToScreen, a position relative to the device's screen, to a position relative to the hosted content's root.

android
suspend Nothing

Starts a platform text input session for request and suspends until the session is cancelled.

android
Unit

Modifies matrix to be a transform from the hosted content's root coordinates into screen coordinates.

android
Unit
voteFrameRate(frameRate: @FloatRange(from = 0.0, to = 360.0) Float)

Votes for a preferred frame rate, in Hz, for the current frame.

android
Unit

Votes for a preferred FrameRateCategory for the current frame.

android

Public properties

Density

The current Density of the host.

android
GraphicsContext

The GraphicsContext used to create graphics layers for the hosted content.

android
LayoutDirection

The current LayoutDirection of the host.

android
View

The Android View that represents this host in the View hierarchy.

android
Window?

The Window that view is attached to, or null if it is not attached to a window.

android

Public functions

addAndroidView

fun addAndroidView(
    view: View,
    semanticsId: Int,
    invalidateMeasurement: () -> Unit
): Unit

Adds an embedded Android View to the host.

view is a wrapper created by Compose around the View supplied to AndroidView. The host adds it to its View tree under the host's View, and draws it only from drawAndroidView. When the host performs a forced layout, it lays out view again at its current bounds.

The semantics node of the embedded view is identified by semanticsId. The id can change while view is attached, when its layout node is reused; the host is then notified with onNodeReused and must re-key any state it stores by id.

Parameters
view: View

The wrapper View to add.

semanticsId: Int

The semantics id of the layout node that contains view.

invalidateMeasurement: () -> Unit

Called when view requests a layout (View.requestLayout), so that Compose measures it again.

clearHostFocus

fun clearHostFocus(): Unit

Called when Compose focus was cleared. Clear Android framework focus from view if view itself is focused. Don't clear focus held by an embedded Android View.

drawAndroidView

fun drawAndroidView(view: View, canvas: Canvas): Unit

Draws an embedded Android View previously added with addAndroidView into canvas.

Parameters
view: View

The wrapper View to draw.

canvas: Canvas

The Canvas to draw view into.

invalidateDraw

fun invalidateDraw(): Unit

Called when the hosted content needs to be drawn again. View hosts typically call View.invalidate.

invalidateMeasurement

fun invalidateMeasurement(): Unit

Called when the hosted content needs to be measured and laid out again. View hosts typically call View.requestLayout.

localToScreen

fun localToScreen(relativeToLocal: Offset): Offset

Converts relativeToLocal, a position relative to the hosted content's root, to a position relative to the device's screen.

observeReads

fun <T : ObservationTarget> observeReads(
    target: T,
    onChanged: (T) -> Unit,
    block: () -> Unit
): Unit

Executes block, observing the snapshot state it reads, and calls onChanged with target when any of that state changes.

Implementations typically delegate to a androidx.compose.runtime.snapshots.SnapshotStateObserver. Pass onChanged through unwrapped: the observer keys its scopes by callback identity, so wrapping it in a new lambda on every call defeats that and allocates.

The host owns the observer's lifecycle: start observing before the hosted content is attached and keep observing while it is attached.

Targets are never notified as valid after removal. Hosts may discard stale observations on their own schedule, for example observer.clearIf { !(it as ObservationTarget).isObservationValid }.

onAutofillRequested

fun onAutofillRequested(node: LayoutInfo): Unit

Called when the content of node asks to show autofill suggestions.

Content asks with androidx.compose.ui.node.requestAutofill, for example when the user picks the autofill action of a text field's context menu. Hosts that support autofill show the suggestions for node, for example with android.view.autofill.AutofillManager.requestAutofill and the bounds of node. Hosts without autofill ignore the call.

  • Called on the UI thread.

onChangesApplied

fun onChangesApplied(): Unit

Called after a batch of composition changes was applied to the hosted content.

Hosts use this to flush work they batched during onNodeAttached, onNodeDetached, onNodeDeactivated, onNodeReused, and onSemanticsChanged, for example to commit autofill changes or to discard observations of removed nodes.

  • Called on the UI thread once per batch: for the main composition, and for each subcomposition, such as the items of lazy lists, which apply changes during measure.

  • Can be called several times per frame. Keep it cheap.

onFocusChanged

fun onFocusChanged(previous: LayoutInfo?, current: LayoutInfo?): Unit

Called when Compose focus moved from previous to current.

Hosts use this to follow the focused node outside Compose, for example to tell autofill which field the user entered and left.

  • Called on the UI thread whenever Compose sets its focused node, so previous and current can be the same node.

  • previous and current are the layout nodes of the focus targets.

  • Either is null when no node held focus, or when focus left the hosted content.

onLayoutChanged

fun onLayoutChanged(node: LayoutInfo): Unit

Called when the size, position, or layer of node changed.

Hosts that report node bounds outside Compose use this to refresh them, for example accessibility virtual view bounds, content capture, or autofill bounds.

  • Called on the UI thread during measure and layout, and when a graphicsLayer changes its transform, clip, or outline.

  • Can be called many times per frame, and several times for the same node. Keep it cheap: record node and process the batch later, for example on the next frame.

  • Don't measure, lay out, or change the tree from this call.

onNodeAttached

fun onNodeAttached(node: LayoutInfo): Unit

Called after node joins the hosted content.

Hosts use this to start tracking nodes that they mirror outside Compose, for example to register autofillable nodes with an autofill session.

  • Called once for each node of an added subtree, children before their parent.

  • Called on the UI thread while composition changes are applied. For content composed during measure, such as the items of lazy lists, this is during the measure pass. Don't measure, lay out, or change the tree from this call; batch work until onChangesApplied.

  • node isn't measured or placed yet; its size and coordinates aren't valid.

  • LayoutInfo.semanticsId identifies node until onNodeReused or onNodeDetached.

onNodeDeactivated

fun onNodeDeactivated(node: LayoutInfo): Unit

Called when node is deactivated: kept in the hosted content for later reuse, without content.

androidx.compose.ui.layout.SubcomposeLayout, which lazy lists use, and androidx.compose.runtime.ReusableContentHost deactivate nodes instead of removing them. Treat node as removed for accessibility, autofill, and content capture, and drop state keyed by its LayoutInfo.semanticsId.

  • node stays attached, so onNodeDetached isn't called until it is discarded.

  • The modifiers of node are reset and its semantics are cleared.

  • Next, node is either reused, see onNodeReused, or detached, see onNodeDetached.

  • Called on the UI thread, often during the measure pass of a lazy layout.

onNodeDetached

fun onNodeDetached(node: LayoutInfo): Unit

Called after node leaves the hosted content.

Hosts must release everything they hold for node: state keyed by its LayoutInfo.semanticsId, accessibility or autofill records, and references to node itself, which would otherwise keep the removed content in memory.

onNodeReused

fun onNodeReused(node: LayoutInfo, previousSemanticsId: Int): Unit

Called when node is reused for different content.

A node is reused after onNodeDeactivated, or when the key of androidx.compose.runtime.ReusableContent changes. Treat node as newly added content: re-key state stored by previousSemanticsId to the new LayoutInfo.semanticsId, for example embedded Views added with addAndroidView, and track it again as in onNodeAttached.

  • Called after the modifiers of node are attached again and its semantics recalculated.

  • node stays attached throughout, so onNodeAttached isn't called.

  • Called on the UI thread, often during the measure pass of a lazy layout.

Parameters
node: LayoutInfo

the reused node, with its new LayoutInfo.semanticsId

previousSemanticsId: Int

the semantics id of node before it was reused

onSemanticsChanged

fun onSemanticsChanged(
    node: LayoutInfo,
    previousConfig: SemanticsPropertyProvider?
): Unit

Called when the semantics of node changed.

Hosts that mirror semantics outside Compose use this to keep the copy current, for example to send accessibility events or report new text values to autofill. Compare previousConfig with the current semantics of node to find what changed.

  • Called on the UI thread right after Compose recalculates the semantics of node: when a semantics modifier is added, removed, or updated, when node with semantics is attached, and when it is detached.

  • Reports the unmerged semantics of node only. The change can also affect the merged semantics of its ancestors, which aren't reported separately.

  • Can be called many times per frame. Keep it cheap and batch work, for example until onChangesApplied.

Parameters
node: LayoutInfo

the node whose semantics changed. Its semantics are empty after it is detached.

previousConfig: SemanticsPropertyProvider?

the semantics of node before the change, or null if node had no semantics

removeAndroidView

fun removeAndroidView(view: View, semanticsId: Int): Unit

Removes an embedded Android View previously added with addAndroidView.

Parameters
view: View

The wrapper View to remove.

semanticsId: Int

The current semantics id of the layout node that contains view.

requestHostFocus

fun requestHostFocus(
    focusDirection: FocusDirection,
    previouslyFocusedRect: Rect?
): Boolean

Called when Compose content requests focus while view does not have framework focus.

Hosts typically call view.requestFocus(direction, previouslyFocusedRect), mapping focusDirection to the matching View.FOCUS_* direction. FocusDirection.Enter means the request is not directional.

Parameters
focusDirection: FocusDirection

The direction focus is moving in.

previouslyFocusedRect: Rect?

The bounds of the previously focused element, in the hosted content's root coordinates, or null if unknown.

Returns
Boolean

true if view holds or obtained framework focus.

screenToLocal

fun screenToLocal(relativeToScreen: Offset): Offset

Converts relativeToScreen, a position relative to the device's screen, to a position relative to the hosted content's root.

startInputMethod

suspend fun startInputMethod(request: PlatformTextInputMethodRequest): Nothing

Starts a platform text input session for request and suspends until the session is cancelled.

Hosts make request available to view's onCheckIsTextEditor and onCreateInputConnection before the first suspension point, and stop using it when the call is cancelled. There is never more than one concurrent call: the previous session is cancelled and joined before a new one starts.

transformToScreen

fun transformToScreen(matrix: Matrix): Unit

Modifies matrix to be a transform from the hosted content's root coordinates into screen coordinates.

matrix initially transforms some coordinate space into the root coordinates; on return it transforms that coordinate space into screen coordinates.

voteFrameRate

fun voteFrameRate(frameRate: @FloatRange(from = 0.0, to = 360.0) Float): Unit

Votes for a preferred frame rate, in Hz, for the current frame.

May be called multiple times per frame. Hosts keep the highest value, apply it when drawing (for example with View.setRequestedFrameRate on API 35 and above), and reset it for the next frame.

voteFrameRateCategory

fun voteFrameRateCategory(category: FrameRateCategory): Unit

Votes for a preferred FrameRateCategory for the current frame.

May be called multiple times per frame. Hosts keep the highest-priority category, where FrameRateCategory.High>FrameRateCategory.Normal>FrameRateCategory.Default, apply it when drawing, and reset it for the next frame.

See also
voteFrameRate

Public properties

density

val density: Density

The current Density of the host.

Reads are snapshot-observed. Implementations must back this with snapshot state (for example mutableStateOf) and assign a new Density when the font scale or density of view changes.

graphicsContext

val graphicsContext: GraphicsContext

The GraphicsContext used to create graphics layers for the hosted content.

Typically GraphicsContext(layerContainer) with an attached ViewGroup in the host's View tree, usually view.

layoutDirection

val layoutDirection: LayoutDirection

The current LayoutDirection of the host.

Reads are snapshot-observed. Implementations must back this with snapshot state (for example mutableStateOf) and update it from View.onRtlPropertiesChanged.

view

val view: View

The Android View that represents this host in the View hierarchy.

view must be the same instance for the lifetime of the host. It:

  • receives input, input method (View.onCheckIsTextEditor, View.onCreateInputConnection, InputMethodManager.restartInput), and accessibility callbacks for the hosted content;

  • is the ancestor that embedded Android Views are added under (see addAndroidView);

  • supplies LocalView and LocalContext to the hosted content.

view may be the host itself, or a View owned by a host that delegates to it.

window

val window: Window?

The Window that view is attached to, or null if it is not attached to a window.