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:

    • USER_SHIFT

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

    • CATEGORY_MASK

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

    • CATEGORY_SHIFT

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

    • 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:

    • FIRST

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

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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.