androidx.compose.ui.platform

@ExperimentalComposeUiApi
@Composable
fun InterceptPlatformTextInput(
    interceptor: PlatformTextInputInterceptor,
    content: @Composable () -> Unit
): Unit

Intercept all calls to PlatformTextInputSession.startInputMethod from below where this composition local is provided with the given PlatformTextInputInterceptor.

If a different interceptor instance is passed between compositions while a text input session is active, the upstream session will be torn down and restarted with the new interceptor. The downstream session (i.e. the call to PlatformTextInputSession.startInputMethod) will not be cancelled and the request will be re-used to pass to the new interceptor.

import androidx.compose.foundation.text.BasicTextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.platform.InterceptPlatformTextInput
import androidx.compose.ui.platform.PlatformTextInputMethodRequest

var text by remember { mutableStateOf("") }

InterceptPlatformTextInput(
    interceptor = { request, nextHandler ->
        // Create a new request to wrap the incoming one with some custom logic.
        val modifiedRequest =
            object : PlatformTextInputMethodRequest {
                override fun createInputConnection(outAttributes: EditorInfo): InputConnection {
                    val inputConnection = request.createInputConnection(outAttributes)
                    // After the original request finishes initializing the EditorInfo we can
                    // customize it. If we needed to we could also wrap the InputConnection
                    // before
                    // returning it.
                    updateEditorInfo(outAttributes)
                    return inputConnection
                }

                fun updateEditorInfo(outAttributes: EditorInfo) {
                    // Your code here, e.g. set some custom properties.
                }
            }

        // Send our wrapping request to the next handler, which could be the system or another
        // interceptor up the tree.
        nextHandler.startInputMethod(modifiedRequest)
    }
) {
    BasicTextField(value = text, onValueChange = { text = it })
}

import androidx.compose.runtime.Composable
import androidx.compose.ui.platform.InterceptPlatformTextInput

/**
 * A function that disables the soft keyboard for any text field within its content.
 *
 * The keyboard is re-enabled by removing this modifier or passing `disable = false`.
 */
@Composable
fun DisableSoftKeyboard(disable: Boolean = true, content: @Composable () -> Unit) {
    InterceptPlatformTextInput(
        interceptor = { request, nextHandler ->
            // If this flag is changed while an input session is active, a new lambda instance
            // that captures the new value will be passed to InterceptPlatformTextInput, which
            // will automatically cancel the session upstream and restart it with this new
            // interceptor.
            if (!disable) {
                // Forward the request to the system.
                nextHandler.startInputMethod(request)
            } else {
                // This function has to return Nothing, and since we don't have any work to do
                // in this case, we just suspend until cancelled.
                awaitCancellation()
            }
        },
        content = content
    )
}

inline fun debugInspectorInfo(crossinline definitions: InspectorInfo.() -> Unit): InspectorInfo.() -> Unit

Use this to specify modifier information for compose tooling.

This factory method allows the specified information to be stripped out by ProGuard in release builds.

import androidx.compose.foundation.background
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.debugInspectorInfo
import androidx.compose.ui.platform.inspectable
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp

/** Sample with a single parameter */
fun Modifier.simpleFrame(color: Color) =
    inspectable(
        inspectorInfo =
            debugInspectorInfo {
                name = "simpleFrame"
                value = color
            }
    ) {
        background(color, RoundedCornerShape(5.0.dp))
    }

/** Sample with multiple parameters */
fun Modifier.fancyFrame(size: Dp, color: Color) =
    inspectable(
        inspectorInfo =
            debugInspectorInfo {
                name = "fancyFrame"
                properties["size"] = size
                properties["color"] = color
            }
    ) {
        background(color, RoundedCornerShape(size))
    }

@Composable
fun rememberNestedScrollInteropConnection(hostView: View = LocalView.current): NestedScrollConnection

Create and remember the NestedScrollConnection that enables Nested Scroll Interop between a View parent that implements androidx.core.view.NestedScrollingParent3 and a Compose child. This should be used in conjunction with a androidx.compose.ui.input.nestedscroll.nestedScroll modifier. Nested Scroll is enabled by default on the compose side and you can use this connection to enable both nested scroll on the view side and to add glue logic between View and compose.

Note that this only covers the use case where a cooperating parent is used. A cooperating parent is one that implements NestedScrollingParent3, a key layout that does that is androidx.coordinatorlayout.widget.CoordinatorLayout.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.nestedscroll.nestedScroll
import androidx.compose.ui.platform.rememberNestedScrollInteropConnection
import androidx.compose.ui.unit.dp

val nestedSrollInterop = rememberNestedScrollInteropConnection()
// Add the nested scroll connection to your top level @Composable element
// using the nestedScroll modifier.
LazyColumn(modifier = Modifier.nestedScroll(nestedSrollInterop)) {
    items(20) { item ->
        Box(
            modifier =
                Modifier.padding(16.dp).height(56.dp).fillMaxWidth().background(Color.Gray),
            contentAlignment = Alignment.Center
        ) {
            Text(item.toString())
        }
    }
}

fun View.createLifecycleAwareWindowRecomposer(
    coroutineContext: CoroutineContext = EmptyCoroutineContext,
    lifecycle: Lifecycle? = null
): Recomposer

Create a Lifecycle and window attachment-aware Recomposer for this View with the same behavior as WindowRecomposerFactory.LifecycleAware.

coroutineContext will override any CoroutineContext elements from the default configuration normally used for this content view. The default CoroutineContext contains AndroidUiDispatcher.CurrentThread; this function should only be called from the UI thread of this View or its intended UI thread if it is currently detached.

If lifecycle is null or not supplied the LifecycleOwner returned by findViewTreeLifecycleOwner will be used; if a non-null lifecycle is not provided and a ViewTreeLifecycleOwner is not present an IllegalStateException will be thrown.

The returned Recomposer will be cancelled when this View is detached from a window or if its determined Lifecycle is destroyed. Recomposition and associated frame-based effects may be throttled or paused while the Lifecycle is not at least Lifecycle.State.STARTED.

suspend fun PlatformTextInputModifierNode.establishTextInputSession(
    block: suspend PlatformTextInputSessionScope.() -> Nothing
): Nothing

Starts a new text input session and suspends until the session is closed.

The block function must call PlatformTextInputSession.startInputMethod to actually show and initiate the connection with the input method. If it does not, the session will end when this function returns without showing the input method.

If this function is called while another session is active, the sessions will not overlap. The new session will interrupt the old one, which will be cancelled and allowed to finish running any cancellation tasks (e.g. finally blocks) before running the new block function.

The session will be closed when:

• The session function throws an exception.

• The requesting coroutine is cancelled.

• Another session is started via this method, either from the same modifier or a different one. The session may remain open when:

• The system closes the connection. This behavior currently only exists on Android depending on OS version. Android platform may intermittently close the active connection to immediately start it back again. In these cases the session will not be prematurely closed, so that it can serve the follow-up requests.

This function should only be called from the modifier node's coroutineScope. If it is not, the session will not automatically be closed if the modifier is detached.

import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusEventModifierNode
import androidx.compose.ui.focus.FocusState
import androidx.compose.ui.platform.PlatformTextInputMethodRequest
import androidx.compose.ui.platform.PlatformTextInputModifierNode
import androidx.compose.ui.platform.PlatformTextInputSession
import androidx.compose.ui.platform.establishTextInputSession

class PlatformTextInputModifierNodeSample :
    Modifier.Node(), FocusEventModifierNode, PlatformTextInputModifierNode {

    private var focusedJob: Job? = null

    override fun onFocusEvent(focusState: FocusState) {
        focusedJob?.cancel()
        focusedJob =
            if (focusState.isFocused) {
                // establishTextInputSession is a suspend function, so it must be called from a
                // coroutine. Launching it into this modifier node's coroutine scope ensures the
                // session will automatically be torn down when the node is detached.
                coroutineScope.launch {
                    // This will automatically cancel any currently-active session.
                    establishTextInputSession {
                        launch {
                            // TODO: Observe text field state, call into system to update it as
                            //  required by the platform.
                        }

                        // Call out to a platform-specific expect/actual function to create the
                        // platform-specific request.
                        val request: PlatformTextInputMethodRequest = createInputRequest()
                        startInputMethod(request)
                    }
                }
            } else {
                null
            }
    }

    // This would probably be an expect/actual function.
    private fun PlatformTextInputSession.createInputRequest(): PlatformTextInputMethodRequest {
        TODO("Create platform-specific request")
    }
}

fun View.findViewTreeCompositionContext(): CompositionContext?

Returns the parent CompositionContext for this point in the view hierarchy, or null if none can be found.

See compositionContext to get or set the parent CompositionContext for a specific view.

@ExperimentalComposeUiApi
fun ClipEntry.firstUriOrNull(): Uri?

Returns the first non-null Uri from the list of ClipData.Items in this ClipEntry.

ClipEntry can contain single or multiple ClipData.Items. This function is useful when you are only interested in processing just a single Uri item inside the ClipEntry.

It's advised that you consider checking all the items inside ClipEntry.clipData to thoroughly process a given ClipEntry.

inline fun Modifier.inspectable(
    noinline inspectorInfo: InspectorInfo.() -> Unit,
    factory: Modifier.() -> Modifier
): Modifier

Use this to group a common set of modifiers and provide InspectorInfo for the resulting modifier.

import androidx.compose.foundation.background
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.debugInspectorInfo
import androidx.compose.ui.platform.inspectable
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp

/** Sample with a single parameter */
fun Modifier.simpleFrame(color: Color) =
    inspectable(
        inspectorInfo =
            debugInspectorInfo {
                name = "simpleFrame"
                value = color
            }
    ) {
        background(color, RoundedCornerShape(5.0.dp))
    }

/** Sample with multiple parameters */
fun Modifier.fancyFrame(size: Dp, color: Color) =
    inspectable(
        inspectorInfo =
            debugInspectorInfo {
                name = "fancyFrame"
                properties["size"] = size
                properties["color"] = color
            }
    ) {
        background(color, RoundedCornerShape(size))
    }

fun Modifier.testTag(tag: String): Modifier

Applies a tag to allow modified element to be found in tests.

This is a convenience method for a semantics that sets SemanticsPropertyReceiver.testTag.

fun ClipData.toClipEntry(): ClipEntry

fun ClipDescription.toClipMetadata(): ClipMetadata

@ExperimentalComposeUiApi
var DisableContentCapture: Boolean

val LocalAccessibilityManager: ProvidableCompositionLocal<AccessibilityManager?>

The CompositionLocal to provide communication with platform accessibility service.

@ExperimentalComposeUiApi
val LocalAutofill: ProvidableCompositionLocal<Autofill?>

The CompositionLocal that can be used to trigger autofill actions. Eg. Autofill.requestAutofillForNode.

val LocalAutofillManager: ProvidableCompositionLocal<AutofillManager?>

The CompositionLocal that can be used to trigger autofill actions. Eg. LocalAutofillManager.commit.

val LocalAutofillTree: ProvidableCompositionLocal<AutofillTree>

The CompositionLocal that can be used to add import androidx.compose.ui.autofill.AutofillNodes to the autofill tree. The AutofillTree is a temporary data structure that will be replaced by Autofill Semantics (b/138604305).

val LocalClipboardManager: ProvidableCompositionLocal<ClipboardManager>

The CompositionLocal to provide communication with platform clipboard service.

val LocalConfiguration: ProvidableCompositionLocal<Configuration>

The Android Configuration. The Configuration is useful for determining how to organize the UI.

val LocalContext: ProvidableCompositionLocal<Context>

Provides a Context that can be used by Android applications.

val LocalCursorBlinkEnabled: ProvidableCompositionLocal<Boolean>

Text cursor blinking

• true normal cursor behavior (interactive blink)

• false never blink (always on)

The default of true is the user-expected system behavior for Text editing.

Typically you should not set false outside of screenshot tests without also providing a cursorBrush to BasicTextField to implement a custom design

val LocalDensity: ProvidableCompositionLocal<Density>

Provides the Density to be used to transform between density-independent pixel units (DP) and pixel units or scale-independent pixel units (SP) and pixel units. This is typically used when a DP is provided and it must be converted in the body of Layout or DrawModifier.

val LocalFocusManager: ProvidableCompositionLocal<FocusManager>

The CompositionLocal that can be used to control focus within Compose.

val LocalFontFamilyResolver: ProvidableCompositionLocal<FontFamily.Resolver>

The CompositionLocal for compose font resolution from FontFamily.

val LocalGraphicsContext: ProvidableCompositionLocal<GraphicsContext>

The CompositionLocal to provide access to a GraphicsContext instance for creation of GraphicsLayers.

Consumers that access this Local directly and call GraphicsContext.createGraphicsLayer are responsible for calling GraphicsContext.releaseGraphicsLayer.

It is recommended that consumers invoke rememberGraphicsLayer instead to ensure that a GraphicsLayer is released when the corresponding composable is disposed.

val LocalHapticFeedback: ProvidableCompositionLocal<HapticFeedback>

The CompositionLocal to provide haptic feedback to the user.

val LocalInputModeManager: ProvidableCompositionLocal<InputModeManager>

The CompositionLocal to provide an instance of InputModeManager which controls the current input mode.

val LocalInspectionMode: ProvidableCompositionLocal<Boolean>

Inspectable mode CompositionLocal. True if the composition is composed inside a Inspectable component.

val LocalLayoutDirection: ProvidableCompositionLocal<LayoutDirection>

The CompositionLocal to provide the layout direction.

val LocalLifecycleOwner: ProvidableCompositionLocal<LifecycleOwner>

The CompositionLocal containing the current LifecycleOwner.

val LocalSavedStateRegistryOwner: ProvidableCompositionLocal<SavedStateRegistryOwner>

The CompositionLocal containing the current SavedStateRegistryOwner.

val LocalScrollCaptureInProgress: CompositionLocal<Boolean>

True when the system is currently capturing the contents of a scrollable in this compose view or any parent compose view.

val LocalSoftwareKeyboardController: ProvidableCompositionLocal<SoftwareKeyboardController?>

The CompositionLocal to provide a SoftwareKeyboardController that can control the current software keyboard.

Will be null if the software keyboard cannot be controlled.

val LocalTextInputService: ProvidableCompositionLocal<TextInputService?>

The CompositionLocal to provide communication with platform text input service.

val LocalTextToolbar: ProvidableCompositionLocal<TextToolbar>

The CompositionLocal to provide text-related toolbar.

val LocalUriHandler: ProvidableCompositionLocal<UriHandler>

The CompositionLocal to provide functionality related to URL, e.g. open URI.

val LocalView: ProvidableCompositionLocal<View>

The CompositionLocal containing the current Compose View.

val LocalViewConfiguration: ProvidableCompositionLocal<ViewConfiguration>

The CompositionLocal that provides the ViewConfiguration.

val LocalWindowInfo: ProvidableCompositionLocal<WindowInfo>

The CompositionLocal that provides information about the window that hosts the current Owner.

val NoInspectorInfo: InspectorInfo.() -> Unit

An empty InspectorInfo DSL.

var isDebugInspectorInfoEnabled: Boolean

Turn on inspector debug information. Used internally during inspection.

var View.compositionContext: CompositionContext?

The CompositionContext that should be used as a parent for compositions at or below this view in the hierarchy. Set to non-null to provide a CompositionContext for compositions created by child views, or null to fall back to any CompositionContext provided by ancestor views.

See findViewTreeCompositionContext.