Package icyllis.modernui.view

# Interface Menu

All Known Subinterfaces:
  `ContextMenu`, `SubMenu`

All Known Implementing Classes:
  `ContextMenuBuilder`, `MenuBuilder`, `SubMenuBuilder`

public interface Menu
Interface for managing the items in a menu.

Different menu types support different features:

1. Context menus: Do not support item shortcuts and item icons.
2. Options menus: The icon menus do not support item check marks and only show the item's `condensed title`. The expanded menus (only available if six or more menu items are visible, reached via the 'More' item in the icon menu) do not show item icons, and item check marks are discouraged.
3. Sub menus: Do not support item icons, or nested sub menus.

### Developer Guides

For more information about creating menus, read the Menus developer guide.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `CATEGORY_ALTERNATIVE`
  Category code for the order integer for items/groups that are alternative actions on the data that is currently displayed -- or/add this with your base value.
  `static final int`
  `CATEGORY_CONTAINER`
  Category code for the order integer for items/groups that are part of a container -- or/add this with your base value.
  `static final int`
  `CATEGORY_MASK`
  This is the part of an order integer that supplies the category of the item.
  `static final int`
  `CATEGORY_SECONDARY`
  Category code for the order integer for items/groups that are user-supplied secondary (infrequently used) options -- or/add this with your base value.
  `static final int`
  `CATEGORY_SHIFT`
  Bit shift of the category portion of the order integer.
  `static final int`
  `CATEGORY_SYSTEM`
  Category code for the order integer for items/groups that are provided by the system -- or/add this with your base value.
  `static final int`
  `FIRST`
  First value for group and item identifier integers.
  `static final int`
  `FLAG_ALWAYS_PERFORM_CLOSE`
  Flag for `performShortcut(int, KeyEvent, int)`: if set, always close the menu after executing the shortcut.
  `static final int`
  `FLAG_PERFORM_NO_CLOSE`
  Flag for `performShortcut(int, icyllis.modernui.view.KeyEvent, int)`: if set, do not close the menu after executing the shortcut.
  `static final int`
  `NONE`
  Value to use for group and item identifier integers when you don't care about them.
  `static final int`
  `SUPPORTED_MODIFIERS_MASK`
  A mask of all supported modifiers for MenuItem's keyboard shortcuts
  `static final int`
  `USER_MASK`
  This is the part of an order integer that the user can provide.
  `static final int`
  `USER_SHIFT`
  Bit shift of the user portion of the order integer.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MenuItem`
  `add(int groupId, int itemId, int order, CharSequence title)`
  Add a new item to the menu.
  `MenuItem`
  `add(CharSequence title)`
  Add a new item to the menu.
  `SubMenu`
  `addSubMenu(int groupId, int itemId, int order, CharSequence title)`
  Add a new sub-menu to the menu.
  `SubMenu`
  `addSubMenu(CharSequence title)`
  Add a new sub-menu to the menu.
  `void`
  `clear()`
  Remove all existing items from the menu, leaving it empty as if it had just been created.
  `void`
  `close()`
  Closes the menu, if open.
  `MenuItem`
  `findItem(int id)`
  Return the menu item with a particular identifier.
  `MenuItem`
  `getItem(int index)`
  Gets the menu item at the given index.
  `boolean`
  `hasVisibleItems()`
  Return whether the menu currently has item items that are visible.
  `boolean`
  `isShortcutKey(int keyCode, KeyEvent event)`
  Is a keypress one of the defined shortcut keys for this window.
  `boolean`
  `performIdentifierAction(int id, int flags)`
  Execute the menu item action associated with the given menu identifier.
  `boolean`
  `performShortcut(int keyCode, KeyEvent event, int flags)`
  Execute the menu item action associated with the given shortcut character.
  `void`
  `removeGroup(int groupId)`
  Remove all items in the given group.
  `void`
  `removeItem(int id)`
  Remove the item with the given identifier.
  `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.
  `void`
  `setQwertyMode(boolean isQwerty)`
  Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).
  `int`
  `size()`
  Get the number of items in the menu.

- ## Field Details

  - ### USER_MASK

    static final int USER_MASK
    This is the part of an order integer that the user can provide.
    See Also:
      - Constant Field Values

  - ### USER_SHIFT

    static final int USER_SHIFT
    Bit shift of the user portion of the order integer.
    See Also:
      - Constant Field Values

  - ### CATEGORY_MASK

    static final int CATEGORY_MASK
    This is the part of an order integer that supplies the category of the item.
    See Also:
      - Constant Field Values

  - ### CATEGORY_SHIFT

    static final int CATEGORY_SHIFT
    Bit shift of the category portion of the order integer.
    See Also:
      - Constant Field Values

  - ### SUPPORTED_MODIFIERS_MASK

    static final int SUPPORTED_MODIFIERS_MASK
    A mask of all supported modifiers for MenuItem's keyboard shortcuts

  - ### NONE

    static final int NONE
    Value to use for group and item identifier integers when you don't care about them.
    See Also:
      - Constant Field Values

  - ### FIRST

    static final int FIRST
    First value for group and item identifier integers.
    See Also:
      - Constant Field Values

  - ### CATEGORY_CONTAINER

    static final int CATEGORY_CONTAINER
    Category code for the order integer for items/groups that are part of a container -- or/add this with your base value.
    See Also:
      - Constant Field Values

  - ### CATEGORY_SYSTEM

    static final int CATEGORY_SYSTEM
    Category code for the order integer for items/groups that are provided by the system -- or/add this with your base value.
    See Also:
      - Constant Field Values

  - ### CATEGORY_SECONDARY

    static final int CATEGORY_SECONDARY
    Category code for the order integer for items/groups that are user-supplied secondary (infrequently used) options -- or/add this with your base value.
    See Also:
      - Constant Field Values

  - ### CATEGORY_ALTERNATIVE

    static final int CATEGORY_ALTERNATIVE
    Category code for the order integer for items/groups that are alternative actions on the data that is currently displayed -- or/add this with your base value.
    See Also:
      - Constant Field Values

  - ### FLAG_PERFORM_NO_CLOSE

    static final int FLAG_PERFORM_NO_CLOSE
    Flag for `performShortcut(int, icyllis.modernui.view.KeyEvent, int)`: if set, do not close the menu after executing the shortcut.
    See Also:
      - Constant Field Values

  - ### FLAG_ALWAYS_PERFORM_CLOSE

    static final int FLAG_ALWAYS_PERFORM_CLOSE
    Flag for `performShortcut(int, KeyEvent, int)`: if set, always close the menu after executing the shortcut. Closing the menu also resets the prepared state.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### add

    @NonNull MenuItem add(CharSequence title)
    Add a new item to the menu. This item displays the given title for its label.
    Parameters:
      `title` - The text to display for the item.
    Returns:
      The newly added menu item.

  - ### add

    @NonNull MenuItem add(int groupId, int itemId, int order, CharSequence title)
    Add a new item to the menu. This item displays the given title for its label.
    Parameters:
      `groupId` - 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 `NONE` if an item should not be in a group.
      `itemId` - Unique item ID. Use `NONE` if you do not need a unique ID.
      `order` - The order for the item. Use `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 SubMenu addSubMenu(CharSequence title)
    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()`.
    Parameters:
      `title` - The text to display for the item.
    Returns:
      The newly added sub-menu

  - ### addSubMenu

    @NonNull SubMenu addSubMenu(int groupId, int itemId, int order, CharSequence title)
    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.

    Parameters:
      `groupId` - 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 `NONE` if an item should not be in a group.
      `itemId` - Unique item ID. Use `NONE` if you do not need a unique ID.
      `order` - The order for the item. Use `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

  - ### removeItem

    void removeItem(int id)
    Remove the item with the given identifier.
    Parameters:
      `id` - The item to be removed. If there is no item with this identifier, nothing happens.

  - ### removeGroup

    void removeGroup(int groupId)
    Remove all items in the given group.
    Parameters:
      `groupId` - The group to be removed. If there are no items in this group, nothing happens.

  - ### clear

    void clear()
    Remove all existing items from the menu, leaving it empty as if it had just been created.

  - ### setGroupCheckable

    void setGroupCheckable(int group, boolean checkable, boolean exclusive)
    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.
    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

    void setGroupVisible(int group, boolean visible)
    Show or hide all menu items that are in the given group.
    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

    void setGroupEnabled(int group, boolean enabled)
    Enable or disable all menu items that are in the given group.
    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

    boolean hasVisibleItems()
    Return whether the menu currently has item items that are visible.
    Returns:
      True if there is one or more item visible, else false.

  - ### findItem

    @Nullable MenuItem findItem(int id)
    Return the menu item with a particular identifier.
    Parameters:
      `id` - The identifier to find.
    Returns:
      The menu item object, or null if there is no item with this identifier.

  - ### size

    int size()
    Get the number of items in the menu. Note that this will change any times items are added or removed from the menu.
    Returns:
      The item count.

  - ### getItem

    @NonNull MenuItem getItem(int index)
    Gets the menu item at the given index.
    Parameters:
      `index` - The index of the menu item to return.
    Returns:
      The menu item.
    Throws:
      `IndexOutOfBoundsException` - when `index < 0 || >= size()`

  - ### close

    void close()
    Closes the menu, if open.

  - ### performShortcut

    boolean performShortcut(int keyCode, @NonNull KeyEvent event, int flags)
    Execute the menu item action associated with the given shortcut character.
    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:
      - `FLAG_PERFORM_NO_CLOSE`

  - ### isShortcutKey

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

  - ### performIdentifierAction

    boolean performIdentifierAction(int id, int flags)
    Execute the menu item action associated with the given menu identifier.
    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:
      - `FLAG_PERFORM_NO_CLOSE`

  - ### setQwertyMode

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

  - ### setGroupDividerEnabled

    void setGroupDividerEnabled(boolean groupDividerEnabled)
    Enable or disable the group dividers.