OnBackPressedDispatcher

Added in 1.0.0

Kotlin |Java

class OnBackPressedDispatcher

Dispatcher that can be used to register OnBackPressedCallback instances for handling the ComponentActivity.onBackPressed callback via composition.

class FormEntryFragment : Fragment() {
  override fun onAttach(context: Context) {
    super.onAttach(context)
    val callback = object : OnBackPressedCallback(
      true // default to enabled
    ) {
      override fun handleOnBackPressed() {
        showAreYouSureDialog()
      }
    }
    requireActivity().onBackPressedDispatcher.addCallback(
      this, // LifecycleOwner
      callback
    )
  }
}

When constructing an instance of this class, the fallbackOnBackPressed can be set to receive a callback if onBackPressed is called when hasEnabledCallbacks returns false.

Summary

Public constructors
`OnBackPressedDispatcher(fallbackOnBackPressed: Runnable?)`
`OnBackPressedDispatcher( fallbackOnBackPressed: Runnable?, onHasEnabledCallbacksChanged: Consumer<Boolean>? )`

Public functions
`Unit`	`@MainThread addCallback(onBackPressedCallback: OnBackPressedCallback)` Add a new `OnBackPressedCallback`.
`Unit`	`@MainThread addCallback( owner: LifecycleOwner, onBackPressedCallback: OnBackPressedCallback )` Receive callbacks to a new `OnBackPressedCallback` when the given `LifecycleOwner` is at least `started`.
`Unit`	`@VisibleForTesting @MainThread dispatchOnBackCancelled()`
`Unit`	`@VisibleForTesting @MainThread dispatchOnBackProgressed(backEvent: BackEventCompat)`
`Unit`	`@VisibleForTesting @MainThread dispatchOnBackStarted(backEvent: BackEventCompat)`
`Boolean`	`@MainThread hasEnabledCallbacks()` Returns `true` if there is at least one `enabled` callback registered with this dispatcher.
`Unit`	`@MainThread onBackPressed()` Trigger a call to the currently added `callbacks` in reverse order in which they were added.
`Unit`	`@RequiresApi(value = 33) setOnBackInvokedDispatcher(invoker: OnBackInvokedDispatcher)` Sets the `OnBackInvokedDispatcher` for handling system back for Android SDK T+.

Extension functions
`OnBackPressedCallback`	`OnBackPressedDispatcher.addCallback( owner: LifecycleOwner?, enabled: Boolean, onBackPressed: OnBackPressedCallback.() -> Unit )` Create and add a new `OnBackPressedCallback` that calls `onBackPressed` in `OnBackPressedCallback.handleOnBackPressed`.

Public constructors

OnBackPressedDispatcher

Added in 1.0.0

OnBackPressedDispatcher(fallbackOnBackPressed: Runnable? = null)

OnBackPressedDispatcher

Added in 1.8.0

OnBackPressedDispatcher(
    fallbackOnBackPressed: Runnable?,
    onHasEnabledCallbacksChanged: Consumer<Boolean>?
)

Public functions

addCallback

Added in 1.0.0

@MainThread
fun addCallback(onBackPressedCallback: OnBackPressedCallback): Unit

Add a new OnBackPressedCallback. Callbacks are invoked in the reverse order in which they are added, so this newly added OnBackPressedCallback will be the first callback to receive a callback if onBackPressed is called.

This method is not Lifecycle aware - if you'd like to ensure that you only get callbacks when at least started, use addCallback. It is expected that you call OnBackPressedCallback.remove to manually remove your callback.

Parameters
`onBackPressedCallback: OnBackPressedCallback`	The callback to add

See also
`onBackPressed`

addCallback

Added in 1.0.0

@MainThread
fun addCallback(
    owner: LifecycleOwner,
    onBackPressedCallback: OnBackPressedCallback
): Unit

Receive callbacks to a new OnBackPressedCallback when the given LifecycleOwner is at least started.

This will automatically call addCallback and remove the callback as the lifecycle state changes. As a corollary, if your lifecycle is already at least started, calling this method will result in an immediate call to addCallback.

When the LifecycleOwner is destroyed, it will automatically be removed from the list of callbacks. The only time you would need to manually call OnBackPressedCallback.remove is if you'd like to remove the callback prior to destruction of the associated lifecycle.

If the Lifecycle is already destroyed when this method is called, the callback will not be added.

Parameters
`owner: LifecycleOwner`	The LifecycleOwner which controls when the callback should be invoked
`onBackPressedCallback: OnBackPressedCallback`	The callback to add

See also
`onBackPressed`

dispatchOnBackCancelled

Added in 1.8.0

@VisibleForTesting
@MainThread
fun dispatchOnBackCancelled(): Unit

dispatchOnBackProgressed

Added in 1.8.0

@VisibleForTesting
@MainThread
fun dispatchOnBackProgressed(backEvent: BackEventCompat): Unit

dispatchOnBackStarted

Added in 1.8.0

@VisibleForTesting
@MainThread
fun dispatchOnBackStarted(backEvent: BackEventCompat): Unit

hasEnabledCallbacks

Added in 1.0.0

@MainThread
fun hasEnabledCallbacks(): Boolean

Returns true if there is at least one enabled callback registered with this dispatcher.

Returns
`Boolean`	True if there is at least one enabled callback.

onBackPressed

Added in 1.0.0

@MainThread
fun onBackPressed(): Unit

Trigger a call to the currently added callbacks in reverse order in which they were added. Only if the most recently added callback is not enabled will any previously added callback be called.

If hasEnabledCallbacks is false when this method is called, the fallbackOnBackPressed set by the constructor will be triggered.

setOnBackInvokedDispatcher

Added in 1.6.0

@RequiresApi(value = 33)
fun setOnBackInvokedDispatcher(invoker: OnBackInvokedDispatcher): Unit

Sets the OnBackInvokedDispatcher for handling system back for Android SDK T+.

Parameters
`invoker: OnBackInvokedDispatcher`	the OnBackInvokedDispatcher to be set on this dispatcher

Extension functions

addCallback

Artifact: androidx.activity:activity

View Source

fun OnBackPressedDispatcher.addCallback(
    owner: LifecycleOwner? = null,
    enabled: Boolean = true,
    onBackPressed: OnBackPressedCallback.() -> Unit
): OnBackPressedCallback

Create and add a new OnBackPressedCallback that calls onBackPressed in OnBackPressedCallback.handleOnBackPressed.

If an owner is specified, the callback will only be added when the Lifecycle is androidx.lifecycle.Lifecycle.State.STARTED.

A default enabled state can be supplied.