Package icyllis.modernui.fragment

# Class OnBackPressedDispatcher

java.lang.Object
icyllis.modernui.fragment.OnBackPressedDispatcher

public final class OnBackPressedDispatcher extends Object
Dispatcher that can be used to register `OnBackPressedCallback` instances for handling the `host.onBackPressed()` callback via composition.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `OnBackPressedDispatcher()`
  Create a new OnBackPressedDispatcher that dispatches System back button pressed events to one or more `OnBackPressedCallback` instances.
  `OnBackPressedDispatcher(Runnable fallbackOnBackPressed)`
  Create a new OnBackPressedDispatcher that dispatches System back button pressed events to one or more `OnBackPressedCallback` instances.

- ## Method Summary

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

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### 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:
      `fallbackOnBackPressed` - The Runnable that should be triggered if `onBackPressed()` is called when `hasEnabledCallbacks()` returns false.

- ## Method Details

  - ### addCallback

    @UiThread public 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 not `Lifecycle` aware - if you'd like to ensure that you only get callbacks when at least `started`, use `addCallback(LifecycleOwner, OnBackPressedCallback)`. It is expected that you call `OnBackPressedCallback.remove()` to manually remove your callback.

    Parameters:
      `onBackPressedCallback` - The callback to add
    See Also:
      - `onBackPressed()`

  - ### addCallback

    @UiThread public void addCallback(@Nonnull LifecycleOwner owner, @Nonnull OnBackPressedCallback callback)
    Receive callbacks to a new `OnBackPressedCallback` when the given `LifecycleOwner` is at least `started`.

    This will automatically call `addCallback(OnBackPressedCallback)` 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(OnBackPressedCallback)`.

    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` - The LifecycleOwner which controls when the callback should be invoked
      `callback` - The callback to add
    See Also:
      - `onBackPressed()`

  - ### hasEnabledCallbacks

    @UiThread public boolean hasEnabledCallbacks()
    Checks if there is at least one `enabled` callback registered with this dispatcher.
    Returns:
      True if there is at least one enabled callback.

  - ### onBackPressed

    @UiThread public 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.