Package icyllis.modernui.view.menu

# Class MenuBuilder

java.lang.Object
icyllis.modernui.view.menu.MenuBuilder

All Implemented Interfaces:
  `Menu`

Direct Known Subclasses:
  `ContextMenuBuilder`, `SubMenuBuilder`

public class MenuBuilder extends Object implements Menu
Implementation of the `Menu` interface for creating a standard menu UI.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `MenuBuilder.Callback`
  Called by menu to notify of close and selection changes.
  `static interface`
  `MenuBuilder.ItemInvoker`
  Called by menu items to execute their associated action

- ## Field Summary

  ### Fields inherited from interface icyllis.modernui.view.Menu

  `CATEGORY_ALTERNATIVE, CATEGORY_CONTAINER, CATEGORY_MASK, CATEGORY_SECONDARY, CATEGORY_SHIFT, CATEGORY_SYSTEM, FIRST, FLAG_ALWAYS_PERFORM_CLOSE, FLAG_PERFORM_NO_CLOSE, NONE, SUPPORTED_MODIFIERS_MASK, USER_MASK, USER_SHIFT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MenuBuilder(Context context)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MenuItem`
  `add(int group, int id, int categoryOrder, CharSequence title)`
  Add a new item to the menu.
  `MenuItem`
  `add(CharSequence title)`
  Add a new item to the menu.
  `void`
  `addMenuPresenter(MenuPresenter presenter)`
  Add a presenter to this menu.
  `void`
  `addMenuPresenter(MenuPresenter presenter, Context menuContext)`
  Add a presenter to this menu that uses an alternate context for inflating menu items.
  `SubMenu`
  `addSubMenu(int group, int id, int categoryOrder, CharSequence title)`
  Add a new sub-menu to the menu.
  `SubMenu`
  `addSubMenu(CharSequence title)`
  Add a new sub-menu to the menu.
  `void`
  `changeMenuMode()`
  Dispatch a mode change event to this menu's callback.
  `void`
  `clear()`
  Remove all existing items from the menu, leaving it empty as if it had just been created.
  `void`
  `clearAll()`
  `void`
  `clearHeader()`
  `void`
  `close()`
  Closes the menu, if open.
  `final void`
  `close(boolean closeAllMenus)`
  Closes the menu.
  `boolean`
  `collapseItemActionView(MenuItemImpl item)`
  `boolean`
  `expandItemActionView(MenuItemImpl item)`
  `int`
  `findGroupIndex(int group)`
  `int`
  `findGroupIndex(int group, int start)`
  `MenuItem`
  `findItem(int id)`
  Return the menu item with a particular identifier.
  `int`
  `findItemIndex(int id)`
  `void`
  `flagActionItems()`
  This method determines which menu items get to be 'action items' that will appear in an action bar and which items should be 'overflow items' in a secondary menu.
  `ArrayList<MenuItemImpl>`
  `getActionItems()`
  `Context`
  `getContext()`
  `MenuItemImpl`
  `getExpandedItem()`
  `Drawable`
  `getHeaderIcon()`
  `CharSequence`
  `getHeaderTitle()`
  `View`
  `getHeaderView()`
  `MenuItem`
  `getItem(int index)`
  Gets the menu item at the given index.
  `ArrayList<MenuItemImpl>`
  `getNonActionItems()`
  `MenuBuilder`
  `getRootMenu()`
  Gets the root menu (if this is a submenu, find its root menu).
  `ArrayList<MenuItemImpl>`
  `getVisibleItems()`
  `boolean`
  `hasVisibleItems()`
  Return whether the menu currently has item items that are visible.
  `boolean`
  `isGroupDividerEnabled()`
  `boolean`
  `isShortcutKey(int keyCode, KeyEvent event)`
  Is a keypress one of the defined shortcut keys for this window.
  `boolean`
  `isShortcutsVisible()`
  `void`
  `onItemsChanged(boolean structureChanged)`
  Called when an item is added or removed.
  `boolean`
  `performIdentifierAction(int id, int flags)`
  Execute the menu item action associated with the given menu identifier.
  `boolean`
  `performItemAction(MenuItem item, int flags)`
  `boolean`
  `performItemAction(MenuItem item, MenuPresenter preferredPresenter, int flags)`
  `boolean`
  `performShortcut(int keyCode, KeyEvent event, int flags)`
  Execute the menu item action associated with the given shortcut character.
  `void`
  `removeGroup(int group)`
  Remove all items in the given group.
  `void`
  `removeItem(int id)`
  Remove the item with the given identifier.
  `void`
  `removeItemAt(int index)`
  `void`
  `removeMenuPresenter(MenuPresenter presenter)`
  Remove a presenter from this menu.
  `void`
  `setCallback(MenuBuilder.Callback cb)`
  `void`
  `setCurrentMenuInfo(ContextMenu.ContextMenuInfo menuInfo)`
  Sets the current menu info that is set on all items added to this menu (until this is called again with different menu info, in which case that one will be added to all subsequent item additions).
  `MenuBuilder`
  `setDefaultShowAsAction(int defaultShowAsAction)`
  `void`
  `setGroupCheckable(int group, boolean checkable, boolean exclusive)`
  Control whether a particular group of items can show a check mark.
  `void`
  `setGroupDividerEnabled(boolean groupDividerEnabled)`
  Enable or disable the group dividers.
  `void`
  `setGroupEnabled(int group, boolean enabled)`
  Enable or disable all menu items that are in the given group.
  `void`
  `setGroupVisible(int group, boolean visible)`
  Show or hide all menu items that are in the given group.
  `protected MenuBuilder`
  `setHeaderIconInt(Drawable icon)`
  Sets the header's icon.
  `protected MenuBuilder`
  `setHeaderTitleInt(CharSequence title)`
  Sets the header's title.
  `protected MenuBuilder`
  `setHeaderViewInt(View view)`
  Sets the header's view.
  `void`
  `setOptionalIconsVisible(boolean visible)`
  `void`
  `setQwertyMode(boolean isQwerty)`
  Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).
  `void`
  `setShortcutsVisible(boolean shortcutsVisible)`
  Sets whether the shortcuts should be visible on menus.
  `int`
  `size()`
  Get the number of items in the menu.
  `void`
  `startDispatchingItemsChanged()`
  `void`
  `stopDispatchingItemsChanged()`
  Stop dispatching item changed events to presenters until `startDispatchingItemsChanged()` is called.

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

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

- ## Constructor Details

  - ### MenuBuilder

    public MenuBuilder(Context context)

- ## Method Details

  - ### setDefaultShowAsAction

    public MenuBuilder setDefaultShowAsAction(int defaultShowAsAction)

  - ### addMenuPresenter

    public void addMenuPresenter(@NonNull MenuPresenter presenter)
    Add a presenter to this menu. This will only hold a WeakReference; you do not need to explicitly remove a presenter, but you can using `removeMenuPresenter(MenuPresenter)`.
    Parameters:
      `presenter` - The presenter to add

  - ### addMenuPresenter

    public void addMenuPresenter(MenuPresenter presenter, Context menuContext)
    Add a presenter to this menu that uses an alternate context for inflating menu items. This will only hold a WeakReference; you do not need to explicitly remove a presenter, but you can using `removeMenuPresenter(MenuPresenter)`.
    Parameters:
      `presenter` - The presenter to add
      `menuContext` - The context used to inflate menu items

  - ### removeMenuPresenter

    public void removeMenuPresenter(MenuPresenter presenter)
    Remove a presenter from this menu. That presenter will no longer receive notifications of updates to this menu's data.
    Parameters:
      `presenter` - The presenter to remove

  - ### setCallback

    public void setCallback(MenuBuilder.Callback cb)

  - ### add

    @NonNull public MenuItem add(@Nullable CharSequence title)
    Description copied from interface: `Menu`
    Add a new item to the menu. This item displays the given title for its label.
    Specified by:
      `add` in interface `Menu`
    Parameters:
      `title` - The text to display for the item.
    Returns:
      The newly added menu item.

  - ### add

    @NonNull public MenuItem add(int group, int id, int categoryOrder, @Nullable CharSequence title)
    Description copied from interface: `Menu`
    Add a new item to the menu. This item displays the given title for its label.
    Specified by:
      `add` in interface `Menu`
    Parameters:
      `group` - The group identifier that this item should be part of. This can be used to define groups of items for batch state changes. Normally use `Menu.NONE` if an item should not be in a group.
      `id` - Unique item ID. Use `Menu.NONE` if you do not need a unique ID.
      `categoryOrder` - The order for the item. Use `Menu.NONE` if you do not care about the order. See `MenuItem.getOrder()`.
      `title` - The text to display for the item.
    Returns:
      The newly added menu item.

  - ### addSubMenu

    @NonNull public SubMenu addSubMenu(@Nullable CharSequence title)
    Description copied from interface: `Menu`
    Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use `SubMenu.getItem()`.
    Specified by:
      `addSubMenu` in interface `Menu`
    Parameters:
      `title` - The text to display for the item.
    Returns:
      The newly added sub-menu

  - ### addSubMenu

    @NonNull public SubMenu addSubMenu(int group, int id, int categoryOrder, @Nullable CharSequence title)
    Description copied from interface: `Menu`
    Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use `SubMenu.getItem()`.

    Note that you can only have one level of sub-menus, i.e. you cannot add a subMenu to a subMenu: An `UnsupportedOperationException` will be thrown if you try.

    Specified by:
      `addSubMenu` in interface `Menu`
    Parameters:
      `group` - The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use `Menu.NONE` if an item should not be in a group.
      `id` - Unique item ID. Use `Menu.NONE` if you do not need a unique ID.
      `categoryOrder` - The order for the item. Use `Menu.NONE` if you do not care about the order. See `MenuItem.getOrder()`.
      `title` - The text to display for the item.
    Returns:
      The newly added sub-menu

  - ### setGroupDividerEnabled

    public void setGroupDividerEnabled(boolean groupDividerEnabled)
    Description copied from interface: `Menu`
    Enable or disable the group dividers.
    Specified by:
      `setGroupDividerEnabled` in interface `Menu`

  - ### isGroupDividerEnabled

    public boolean isGroupDividerEnabled()

  - ### removeItem

    public void removeItem(int id)
    Description copied from interface: `Menu`
    Remove the item with the given identifier.
    Specified by:
      `removeItem` in interface `Menu`
    Parameters:
      `id` - The item to be removed. If there is no item with this identifier, nothing happens.

  - ### removeGroup

    public void removeGroup(int group)
    Description copied from interface: `Menu`
    Remove all items in the given group.
    Specified by:
      `removeGroup` in interface `Menu`
    Parameters:
      `group` - The group to be removed. If there are no items in this group, nothing happens.

  - ### removeItemAt

    public void removeItemAt(int index)

  - ### clearAll

    public void clearAll()

  - ### clear

    public void clear()
    Description copied from interface: `Menu`
    Remove all existing items from the menu, leaving it empty as if it had just been created.
    Specified by:
      `clear` in interface `Menu`

  - ### setGroupCheckable

    public void setGroupCheckable(int group, boolean checkable, boolean exclusive)
    Description copied from interface: `Menu`
    Control whether a particular group of items can show a check mark. This is similar to calling `MenuItem.setCheckable(boolean)` on all the menu items with the given group identifier, but in addition you can control whether this group contains a mutually-exclusive set items. This should be called after the items of the group have been added to the menu.
    Specified by:
      `setGroupCheckable` in interface `Menu`
    Parameters:
      `group` - The group of items to operate on.
      `checkable` - Set to true to allow a check mark, false to disallow. The default is false.
      `exclusive` - If set to true, only one item in this group can be checked at a time; checking an item will automatically uncheck all others in the group. If set to false, each item can be checked independently of the others.
    See Also:
      - `MenuItem.setCheckable(boolean)`
      - `MenuItem.setChecked(boolean)`

  - ### setGroupVisible

    public void setGroupVisible(int group, boolean visible)
    Description copied from interface: `Menu`
    Show or hide all menu items that are in the given group.
    Specified by:
      `setGroupVisible` in interface `Menu`
    Parameters:
      `group` - The group of items to operate on.
      `visible` - If true the items are visible, else they are hidden.
    See Also:
      - `MenuItem.setVisible(boolean)`

  - ### setGroupEnabled

    public void setGroupEnabled(int group, boolean enabled)
    Description copied from interface: `Menu`
    Enable or disable all menu items that are in the given group.
    Specified by:
      `setGroupEnabled` in interface `Menu`
    Parameters:
      `group` - The group of items to operate on.
      `enabled` - If true the items will be enabled, else they will be disabled.
    See Also:
      - `MenuItem.setEnabled(boolean)`

  - ### hasVisibleItems

    public boolean hasVisibleItems()
    Description copied from interface: `Menu`
    Return whether the menu currently has item items that are visible.
    Specified by:
      `hasVisibleItems` in interface `Menu`
    Returns:
      True if there is one or more item visible, else false.

  - ### findItem

    @Nullable public MenuItem findItem(int id)
    Description copied from interface: `Menu`
    Return the menu item with a particular identifier.
    Specified by:
      `findItem` in interface `Menu`
    Parameters:
      `id` - The identifier to find.
    Returns:
      The menu item object, or null if there is no item with this identifier.

  - ### findItemIndex

    public int findItemIndex(int id)

  - ### findGroupIndex

    public int findGroupIndex(int group)

  - ### findGroupIndex

    public int findGroupIndex(int group, int start)

  - ### size

    public int size()
    Description copied from interface: `Menu`
    Get the number of items in the menu. Note that this will change any times items are added or removed from the menu.
    Specified by:
      `size` in interface `Menu`
    Returns:
      The item count.

  - ### getItem

    @NonNull public MenuItem getItem(int index)
    Gets the menu item at the given index.
    Specified by:
      `getItem` in interface `Menu`
    Parameters:
      `index` - The index of the menu item to return.
    Returns:
      The menu item.

  - ### isShortcutKey

    public boolean isShortcutKey(int keyCode, @NonNull KeyEvent event)
    Description copied from interface: `Menu`
    Is a keypress one of the defined shortcut keys for this window.
    Specified by:
      `isShortcutKey` in interface `Menu`
    Parameters:
      `keyCode` - the key code from `KeyEvent` to check.
      `event` - the `KeyEvent` to use to help check.

  - ### setQwertyMode

    public void setQwertyMode(boolean isQwerty)
    Description copied from interface: `Menu`
    Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).
    Specified by:
      `setQwertyMode` in interface `Menu`
    Parameters:
      `isQwerty` - If true the menu will use alphabetic shortcuts; else it will use numeric shortcuts.

  - ### setShortcutsVisible

    public void setShortcutsVisible(boolean shortcutsVisible)
    Sets whether the shortcuts should be visible on menus. Devices without hardware key input will never make shortcuts visible even if this method is passed 'true'.
    Parameters:
      `shortcutsVisible` - Whether shortcuts should be visible (if true and a menu item does not have a shortcut defined, that item will still NOT show a shortcut)

  - ### isShortcutsVisible

    public boolean isShortcutsVisible()
    Returns:
      Whether shortcuts should be visible on menus.

  - ### getContext

    public Context getContext()

  - ### changeMenuMode

    public void changeMenuMode()
    Dispatch a mode change event to this menu's callback.

  - ### performShortcut

    public boolean performShortcut(int keyCode, @NonNull KeyEvent event, int flags)
    Description copied from interface: `Menu`
    Execute the menu item action associated with the given shortcut character.
    Specified by:
      `performShortcut` in interface `Menu`
    Parameters:
      `keyCode` - The keycode of the shortcut key.
      `event` - Key event message.
      `flags` - Additional option flags or 0.
    Returns:
      If the given shortcut exists and is shown, returns true; else returns false.
    See Also:
      - `Menu.FLAG_PERFORM_NO_CLOSE`

  - ### performIdentifierAction

    public boolean performIdentifierAction(int id, int flags)
    Description copied from interface: `Menu`
    Execute the menu item action associated with the given menu identifier.
    Specified by:
      `performIdentifierAction` in interface `Menu`
    Parameters:
      `id` - Identifier associated with the menu item.
      `flags` - Additional option flags or 0.
    Returns:
      If the given identifier exists and is shown, returns true; else returns false.
    See Also:
      - `Menu.FLAG_PERFORM_NO_CLOSE`

  - ### performItemAction

    public boolean performItemAction(MenuItem item, int flags)

  - ### performItemAction

    public boolean performItemAction(MenuItem item, MenuPresenter preferredPresenter, int flags)

  - ### close

    public final void close(boolean closeAllMenus)
    Closes the menu.
    Parameters:
      `closeAllMenus` - `true` if all displayed menus and submenus should be completely closed (as when a menu item is selected) or `false` if only this menu should be closed

  - ### close

    public void close()
    Closes the menu, if open.
    Specified by:
      `close` in interface `Menu`

  - ### onItemsChanged

    public void onItemsChanged(boolean structureChanged)
    Called when an item is added or removed.
    Parameters:
      `structureChanged` - true if the menu structure changed, false if only item properties changed. (Visibility is a structural property since it affects layout.)

  - ### stopDispatchingItemsChanged

    public void stopDispatchingItemsChanged()
    Stop dispatching item changed events to presenters until `startDispatchingItemsChanged()` is called. Useful when many menu operations are going to be performed as a batch.

  - ### startDispatchingItemsChanged

    public void startDispatchingItemsChanged()

  - ### getVisibleItems

    @NonNull public ArrayList<MenuItemImpl> getVisibleItems()

  - ### flagActionItems

    public void flagActionItems()
    This method determines which menu items get to be 'action items' that will appear in an action bar and which items should be 'overflow items' in a secondary menu. The rules are as follows:

    Items are considered for inclusion in the order specified within the menu. There is a limit of mMaxActionItems as a total count, optionally including the overflow menu button itself. This is a soft limit; if an item shares a group ID with an item previously included as an action item, the new item will stay with its group and become an action item itself even if it breaks the max item count limit. This is done to limit the conceptual complexity of the items presented within an action bar. Only a few unrelated concepts should be presented to the user in this space, and groups are treated as a single concept.

    There is also a hard limit of consumed measurable space: mActionWidthLimit. This limit may be broken by a single item that exceeds the remaining space, but no further items may be added. If an item that is part of a group cannot fit within the remaining measured width, the entire group will be demoted to overflow. This is done to ensure room for navigation and other affordances in the action bar as well as reduce general UI clutter.

    The space freed by demoting a full group cannot be consumed by future menu items. Once items begin to overflow, all future items become overflow items as well. This is to avoid inadvertent reordering that may break the app's intended design.

  - ### getActionItems

    public ArrayList<MenuItemImpl> getActionItems()

  - ### getNonActionItems

    public ArrayList<MenuItemImpl> getNonActionItems()

  - ### clearHeader

    public void clearHeader()

  - ### setHeaderTitleInt

    protected MenuBuilder setHeaderTitleInt(CharSequence title)
    Sets the header's title. This replaces the header view. Called by the builder-style methods of subclasses.
    Parameters:
      `title` - The new title.
    Returns:
      This MenuBuilder so additional setters can be called.

  - ### setHeaderIconInt

    protected MenuBuilder setHeaderIconInt(Drawable icon)
    Sets the header's icon. This replaces the header view. Called by the builder-style methods of subclasses.
    Parameters:
      `icon` - The new icon.
    Returns:
      This MenuBuilder so additional setters can be called.

  - ### setHeaderViewInt

    protected MenuBuilder setHeaderViewInt(View view)
    Sets the header's view. This replaces the title and icon. Called by the builder-style methods of subclasses.
    Parameters:
      `view` - The new view.
    Returns:
      This MenuBuilder so additional setters can be called.

  - ### getHeaderTitle

    public CharSequence getHeaderTitle()

  - ### getHeaderIcon

    public Drawable getHeaderIcon()

  - ### getHeaderView

    public View getHeaderView()

  - ### getRootMenu

    public MenuBuilder getRootMenu()
    Gets the root menu (if this is a submenu, find its root menu).
    Returns:
      The root menu.

  - ### setCurrentMenuInfo

    public void setCurrentMenuInfo(ContextMenu.ContextMenuInfo menuInfo)
    Sets the current menu info that is set on all items added to this menu (until this is called again with different menu info, in which case that one will be added to all subsequent item additions).
    Parameters:
      `menuInfo` - The extra menu information to add.

  - ### setOptionalIconsVisible

    public void setOptionalIconsVisible(boolean visible)

  - ### expandItemActionView

    public boolean expandItemActionView(MenuItemImpl item)

  - ### collapseItemActionView

    public boolean collapseItemActionView(MenuItemImpl item)

  - ### getExpandedItem

    public MenuItemImpl getExpandedItem()