FocusRequester

Class

Common

class FocusRequester @RememberInComposition constructor()

The FocusRequester is used in conjunction with Modifier.focusRequester to send requests to change focus.

Functions

fun requestFocus()

Use this function to request focus. If the system grants focus to a component associated with this FocusRequester, its onFocusChanged modifiers will receive a FocusState object where FocusState.isFocused is true.

fun requestFocus(focusDirection: FocusDirection = Enter): Boolean

Use this function to request focus with a specific direction. If the system grants focus to a component associated with this FocusRequester, its onFocusChanged modifiers will receive a FocusState object where FocusState.isFocused is true.

Parameters


focusDirection	The direction passed to the `FocusTargetModifierNode` to indicate the direction that the focus request comes from.

Returns


	`true` if the focus was successfully requested or `false` if the focus request was canceled.

fun captureFocus(): Boolean

Deny requests to clear focus.

Use this function to send a request to capture focus. If a component captures focus, it will send a FocusState object to its associated onFocusChanged modifiers where FocusState.isCaptured() == true.

When a component is in a Captured state, all focus requests from other components are declined.

Returns


	true if the focus was successfully captured by one of the `focus` modifiers associated with this `FocusRequester`. False otherwise.

fun freeFocus(): Boolean

Use this function to send a request to free focus when one of the components associated with this FocusRequester is in a Captured state. If a component frees focus, it will send a FocusState object to its associated onFocusChanged modifiers where FocusState.isCaptured() == false.

When a component is in a Captured state, all focus requests from other components are declined. .

Returns


	true if the captured focus was successfully released. i.e. At the end of this operation, one of the components associated with this `focusRequester` freed focus.

fun saveFocusedChild(): Boolean

Use this function to request the focus target to save a reference to the currently focused child in its saved instance state. After calling this, focus can be restored to the saved child by making a call to restoreFocusedChild.

Returns


	true if the focus target associated with this `FocusRequester` has a focused child and we successfully saved a reference to it.

fun restoreFocusedChild(): Boolean

Use this function to restore focus to one of the children of the node pointed to by this FocusRequester. This restores focus to a previously focused child that was saved by using saveFocusedChild.

Returns


	true if we successfully restored focus to one of the children of the `focusTarget` associated with this `FocusRequester`

Companion Object

Properties

Common

val Default = FocusRequester()

Default focusRequester, which when used in Modifier.focusProperties implies that we want to use the default system focus order, that is based on the position of the items on the screen.

Common

val Cancel = FocusRequester()

Cancelled focusRequester, which when used in Modifier.focusProperties implies that we want to block focus search from proceeding in the specified direction.

Methods

Common

fun createRefs():

Convenient way to create multiple FocusRequesters, which can to be used to request focus, or to specify a focus traversal order.

Code Examples

RequestFocusSample

@Composable
fun RequestFocusSample() {
    val focusRequester = remember { FocusRequester() }
    var color by remember { mutableStateOf(Black) }
    Box(
        Modifier.clickable { focusRequester.requestFocus() }
            .border(2.dp, color)
            // The focusRequester should be added BEFORE the focusable.
            .focusRequester(focusRequester)
            // The onFocusChanged should be added BEFORE the focusable that is being observed.
            .onFocusChanged { color = if (it.isFocused) Green else Black }
            .focusable()
    )
}