Package icyllis.modernui.view

# Class ActionProvider

java.lang.Object
icyllis.modernui.view.ActionProvider

public abstract class ActionProvider extends Object
An ActionProvider defines rich menu interaction in a single component. ActionProvider can generate action views for use in the action bar, dynamically populate submenus of a MenuItem, and handle default menu item invocations.

An ActionProvider can be optionally specified for a `MenuItem` and will be responsible for creating the action view that appears in the ActionBar in place of a simple button in the bar. When the menu item is presented in a way that does not allow custom action views, (e.g. in an overflow menu,) the ActionProvider can perform a default action.

There are two ways to use an action provider:

- Set the action provider on a `MenuItem` directly by calling `MenuItem.setActionProvider(ActionProvider)`.

See Also:
  - `MenuItem.setActionProvider(ActionProvider)`
  - `MenuItem.getActionProvider()`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `ActionProvider.SubUiVisibilityListener`
  `static interface`
  `ActionProvider.VisibilityListener`
  Listens to changes in visibility as reported by `refreshVisibility()`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ActionProvider()`
  Creates a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `hasSubMenu()`
  Determines if this ActionProvider has a submenu associated with it.
  `boolean`
  `isVisible()`
  If `overridesItemVisibility()` returns true, the return value of this method will help determine the visibility of the `MenuItem` this ActionProvider is bound to.
  `abstract View`
  `onCreateActionView(MenuItem menuItem)`
  Factory method called by the Android framework to create new action views.
  `boolean`
  `onPerformDefaultAction()`
  Performs an optional default action.
  `void`
  `onPrepareSubMenu(SubMenu subMenu)`
  Called to prepare an associated submenu for the menu item backed by this ActionProvider.
  `boolean`
  `overridesItemVisibility()`
  The result of this method determines whether or not `isVisible()` will be used by the `MenuItem` this ActionProvider is bound to help determine its visibility.
  `void`
  `refreshVisibility()`
  If this ActionProvider is associated with an item in a menu, refresh the visibility of the item based on `overridesItemVisibility()` and `isVisible()`.
  `void`
  `reset()`
  `void`
  `setSubUiVisibilityListener(ActionProvider.SubUiVisibilityListener listener)`
  `void`
  `setVisibilityListener(ActionProvider.VisibilityListener listener)`
  Set a listener to be notified when this ActionProvider's overridden visibility changes.
  `void`
  `subUiVisibilityChanged(boolean isVisible)`
  Notify the system that the visibility of an action view's sub-UI such as an anchored popup has changed.

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

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

- ## Constructor Details

  - ### ActionProvider

    public ActionProvider()
    Creates a new instance. ActionProvider classes should always implement a constructor that takes a single Context parameter for inflating from menu XML.

- ## Method Details

  - ### onCreateActionView

    public abstract View onCreateActionView(MenuItem menuItem)
    Factory method called by the Android framework to create new action views. This method returns a new action view for the given MenuItem.
    Parameters:
      `menuItem` - MenuItem to create the action view for
    Returns:
      the new action view

  - ### overridesItemVisibility

    public boolean overridesItemVisibility()
    The result of this method determines whether or not `isVisible()` will be used by the `MenuItem` this ActionProvider is bound to help determine its visibility.
    Returns:
      true if this ActionProvider overrides the visibility of the MenuItem it is bound to, false otherwise. The default implementation returns false.
    See Also:
      - `isVisible()`

  - ### isVisible

    public boolean isVisible()
    If `overridesItemVisibility()` returns true, the return value of this method will help determine the visibility of the `MenuItem` this ActionProvider is bound to.

    If the MenuItem's visibility is explicitly set to false by the application, the MenuItem will not be shown, even if this method returns true.

    Returns:
      true if the MenuItem this ActionProvider is bound to is visible, false if it is invisible. The default implementation returns true.

  - ### refreshVisibility

    public void refreshVisibility()
    If this ActionProvider is associated with an item in a menu, refresh the visibility of the item based on `overridesItemVisibility()` and `isVisible()`. If `overridesItemVisibility()` returns false, this call will have no effect.

  - ### onPerformDefaultAction

    public boolean onPerformDefaultAction()
    Performs an optional default action.

    For the case of an action provider placed in a menu item not shown as an action this method is invoked if previous callbacks for processing menu selection has handled the event.

    A menu item selection is processed in the following order:

    - Receiving a call to `MenuItem.OnMenuItemClickListener.onMenuItemClick`.
    - Receiving a call to
      invalid reference

          Fragment.onOptionsItemSelected(MenuItem)

    - Invoking this method.

    The default implementation does not perform any action and returns false.

  - ### hasSubMenu

    public boolean hasSubMenu()
    Determines if this ActionProvider has a submenu associated with it.

    Associated submenus will be shown when an action view is not. This provider instance will receive a call to `onPrepareSubMenu(SubMenu)` after the call to `onPerformDefaultAction()` and before a submenu is displayed to the user.

    Returns:
      true if the item backed by this provider should have an associated submenu

  - ### onPrepareSubMenu

    public void onPrepareSubMenu(SubMenu subMenu)
    Called to prepare an associated submenu for the menu item backed by this ActionProvider.

    if `hasSubMenu()` returns true, this method will be called when the menu item is selected to prepare the submenu for presentation to the user. Apps may use this to create or alter submenu content right before display.

    Parameters:
      `subMenu` - Submenu that will be displayed

  - ### subUiVisibilityChanged

    public void subUiVisibilityChanged(boolean isVisible)
    Notify the system that the visibility of an action view's sub-UI such as an anchored popup has changed. This will affect how other system visibility notifications occur.

  - ### setSubUiVisibilityListener

    @Internal public void setSubUiVisibilityListener(ActionProvider.SubUiVisibilityListener listener)

  - ### setVisibilityListener

    public void setVisibilityListener(ActionProvider.VisibilityListener listener)
    Set a listener to be notified when this ActionProvider's overridden visibility changes. This should only be used by MenuItem implementations.
    Parameters:
      `listener` - listener to set

  - ### reset

    @Internal public void reset()