Interface

ComposeUiHost

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

Source set: Android
public interface 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.

Properties

view

Source set: Android
public 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:

    InputMethodManager.restartInput), and accessibility callbacks for the hosted content;

  • receives input, input method (View.onCheckIsTextEditor, View.onCreateInputConnection,
  • 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.

density

Source set: Android
public 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.

layoutDirection

Source set: Android
public 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.

window

Source set: Android
public val window: Window?

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

graphicsContext

Source set: Android
public 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.

Functions

localToScreen

Source set: Android
public 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.

screenToLocal

Source set: Android
public 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.

transformToScreen

Source set: Android
public fun transformToScreen(matrix: Matrix)

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.

observeReads

Source set: Android
public fun <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.

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 }.

invalidateDraw

Source set: Android
public fun invalidateDraw()

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

invalidateMeasurement

Source set: Android
public fun invalidateMeasurement()

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

voteFrameRate

Source set: Android
public fun voteFrameRate(@FloatRange(from = 0.0, to = 360.0) frameRate: Float)

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

Source set: Android
public fun voteFrameRateCategory(category: FrameRateCategory)

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.

requestHostFocus

Source set: Android
public 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 The direction focus is moving in.
previouslyFocusedRect The bounds of the previously focused element, in the hosted content's root coordinates, or null if unknown.

Return

true if view holds or obtained framework focus.

clearHostFocus

Source set: Android
public fun clearHostFocus()

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.

addAndroidView

Source set: Android
public fun addAndroidView(view: View, semanticsId: Int, invalidateMeasurement: () -> 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 The wrapper View to add.
semanticsId The semantics id of the layout node that contains view.
invalidateMeasurement Called when view requests a layout (View.requestLayout), so that Compose measures it again.

removeAndroidView

Source set: Android
public fun removeAndroidView(view: View, semanticsId: Int)

Removes an embedded Android View previously added with addAndroidView.

Parameters

view The wrapper View to remove.
semanticsId The current semantics id of the layout node that contains view.

drawAndroidView

Source set: Android
public fun drawAndroidView(view: View, canvas: Canvas)

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

Parameters

view The wrapper View to draw.
canvas The Canvas to draw view into.

startInputMethod

Source set: Android
public 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.

onLayoutChanged

Source set: Android
public fun onLayoutChanged(node: LayoutInfo)

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.

    transform, clip, or outline.

  • Called on the UI thread during measure and layout, and when a graphicsLayer changes its
  • record node and process the batch later, for example on the next frame.

  • Can be called many times per frame, and several times for the same node. Keep it cheap:
  • Don't measure, lay out, or change the tree from this call.

onSemanticsChanged

Source set: Android
public fun onSemanticsChanged(node: LayoutInfo, previousConfig: SemanticsPropertyProvider?)

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.

    semantics modifier is added, removed, or updated, when node with semantics is attached, and when it is detached.

  • Called on the UI thread right after Compose recalculates the semantics of node: when a
  • semantics of its ancestors, which aren't reported separately.

  • Reports the unmerged semantics of node only. The change can also affect the merged
  • onChangesApplied.

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

Parameters

node the node whose semantics changed. Its semantics are empty after it is detached.
previousConfig the semantics of node before the change, or null if node had no semantics

onFocusChanged

Source set: Android
public fun onFocusChanged(previous: LayoutInfo?, current: LayoutInfo?)

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.

    can be the same node.

  • Called on the UI thread whenever Compose sets its focused node, so previous and current
  • 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.

onNodeAttached

Source set: Android
public fun onNodeAttached(node: LayoutInfo)

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.
  • 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.

  • Called on the UI thread while composition changes are applied. For content composed during
  • node isn't measured or placed yet; its size and coordinates aren't valid.
  • LayoutInfo.semanticsId identifies node until onNodeReused or onNodeDetached.

onNodeDetached

Source set: Android
public fun onNodeDetached(node: LayoutInfo)

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.

    hosted content removes every node except the root.

  • Called once for each node of a removed subtree, children before their parent. Disposing the
  • Called on the UI thread while composition changes are applied, like onNodeAttached.
  • The modifiers of node are already detached. Don't read its semantics or coordinates.
  • androidx.compose.ui.node.ObservationTarget.isObservationValid.

  • Observations of node made through observeReads are no longer needed; see
  • Not called for nodes that are only deactivated; see onNodeDeactivated.

onNodeDeactivated

Source set: Android
public fun onNodeDeactivated(node: LayoutInfo)

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.

onNodeReused

Source set: Android
public fun onNodeReused(node: LayoutInfo, previousSemanticsId: Int)

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 the reused node, with its new LayoutInfo.semanticsId
previousSemanticsId the semantics id of node before it was reused

onAutofillRequested

Source set: Android
public fun onAutofillRequested(node: LayoutInfo)

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

Source set: Android
public fun onChangesApplied()

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.

    subcomposition, such as the items of lazy lists, which apply changes during measure.

  • Called on the UI thread once per batch: for the main composition, and for each
  • Can be called several times per frame. Keep it cheap.
Jetpack Compose beyond MaterialFree components, screens and templates for apps that don’t look like Google’s. Copy them into your app, or let your coding agent add them.Browse for free

Content updated: