OnBackPressedDispatcher

Kotlin |Java

public final class OnBackPressedDispatcher

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

public class FormEntryFragment extends Fragment {
    {@literal @}Override
    public void onAttach({@literal @}NonNull Context context) {
        super.onAttach(context);
        OnBackPressedCallback callback = new OnBackPressedCallback(
            true // default to enabled
        ) {
            {@literal @}Override
            public void handleOnBackPressed() {
                showAreYouSureDialog();
            }
        };
        requireActivity().getOnBackPressedDispatcher().addCallback(
            this, // LifecycleOwner
            callback);
    }
}

Summary

Public constructors
`OnBackPressedDispatcher()` Create a new OnBackPressedDispatcher that dispatches System back button pressed events to one or more `OnBackPressedCallback` instances.
`OnBackPressedDispatcher(@Nullable Runnable fallbackOnBackPressed)` Create a new OnBackPressedDispatcher that dispatches System back button pressed events to one or more `OnBackPressedCallback` instances.

Public methods
`@MainThread @NonNull void`	`addCallback(@NonNull OnBackPressedCallback onBackPressedCallback)` Add a new `OnBackPressedCallback`.
`@MainThread @NonNull void`	`addCallback( @NonNull LifecycleOwner owner, @NonNull OnBackPressedCallback onBackPressedCallback )` Receive callbacks to a new `OnBackPressedCallback` when the given `LifecycleOwner` is at least `started`.
`@MainThread @NonNull boolean`	`hasEnabledCallbacks()` Checks if there is at least one `enabled` callback registered with this dispatcher.
`@MainThread @NonNull void`	`onBackPressed()` Trigger a call to the currently added `callbacks` in reverse order in which they were added.

Extension functions
`final @NonNull OnBackPressedCallback`	`OnBackPressedDispatcherKt.addCallback( @NonNull OnBackPressedDispatcher receiver, @Nullable LifecycleOwner owner, boolean enabled, @NonNull Function1<@NonNull OnBackPressedCallback, Unit> onBackPressed )` Create and add a new `OnBackPressedCallback` that calls `onBackPressed` in `OnBackPressedCallback.handleOnBackPressed`.

Public constructors

OnBackPressedDispatcher

public OnBackPressedDispatcher()

Create a new OnBackPressedDispatcher that dispatches System back button pressed events to one or more OnBackPressedCallback instances.

OnBackPressedDispatcher

public OnBackPressedDispatcher(@Nullable Runnable fallbackOnBackPressed)

Create a new OnBackPressedDispatcher that dispatches System back button pressed events to one or more OnBackPressedCallback instances.

Parameters
`@Nullable Runnable fallbackOnBackPressed`	The Runnable that should be triggered if `onBackPressed` is called when `hasEnabledCallbacks` returns false.

Public methods

addCallback

@MainThread
@NonNull
public @MainThread void addCallback(@NonNull OnBackPressedCallback onBackPressedCallback)

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 notLifecycle aware - if you'd like to ensure that you only get callbacks when at least started, use addCallback. It is expected that you call remove to manually remove your callback.

Parameters
`@NonNull OnBackPressedCallback onBackPressedCallback`	The callback to add

See also
`onBackPressed`	#onBackPressed()

addCallback

@MainThread
@NonNull
public @MainThread void addCallback(
    @NonNull LifecycleOwner owner,
    @NonNull OnBackPressedCallback onBackPressedCallback
)

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 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
`@NonNull LifecycleOwner owner`	The LifecycleOwner which controls when the callback should be invoked
`@NonNull OnBackPressedCallback onBackPressedCallback`	The callback to add

See also
`onBackPressed`	#onBackPressed()

hasEnabledCallbacks

@MainThread
@NonNull
public @MainThread boolean hasEnabledCallbacks()

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

Returns
`@MainThread boolean`	True if there is at least one enabled callback.

onBackPressed

@MainThread
@NonNull
public @MainThread void onBackPressed()

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 fallback Runnable set by the constructor will be triggered.

Extension functions

OnBackPressedDispatcherKt.addCallback

@NonNull
public final OnBackPressedCallback OnBackPressedDispatcherKt.addCallback(
    @NonNull OnBackPressedDispatcher receiver,
    @Nullable LifecycleOwner owner,
    boolean enabled,
    @NonNull Function1<@NonNull OnBackPressedCallback, Unit> onBackPressed
)

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.