Package limn.components

Class MenuItem

java.lang.Object
limn.components.MenuItem
public final class MenuItem extends Object
One entry in a Menu: a command, a checkable toggle, a submenu, or a separator. Pure model (no widgets): a PopupMenu or MenuBar renders it. Build with the static factories: 

 Menu edit = new Menu()
     .add(MenuItem.of("Undo", () -> undo()).setAccelerator(Accelerator.command(Keys.Z)))
     .addSeparator()
     .add(MenuItem.check("Word wrap", true, on -> setWrap(on)).setMnemonic('W'))
     .add(MenuItem.submenu("Export", exportMenu));

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    MenuItem.Role
    What an item is to the system, beyond its label: one of the three every application has and a system may keep in a menu of its own, or one of the six editing commands.

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable Accelerator
    accelerator()
    The keyboard shortcut shown at the right of the row and dispatched while closed, or null.
    static MenuItem
    check(String label, boolean checked, Consumer<Boolean> onToggle)
    A checkable item showing a check mark for its state; choosing it flips the state and calls onToggle with the new value.
    static MenuItem
    check(I18nString label, boolean checked, Consumer<Boolean> onToggle)
    A checkable item whose label follows the UI language.
    @Nullable Icon
    icon()
     
    boolean
    isChecked()
     
    boolean
    isEnabled()
    Whether the item can be chosen; a disabled one still occupies a row.
    @Nullable String
    label()
    The label as it currently reads, or null for a separator: its text in the language in effect, an access letter's & mark taken out ("&Open" reads "Open").
    @Nullable I18nString
    labelSource()
    The localizable value behind label(); null for a separator.
    char
    mnemonic()
    The access letter, uppercased, or 0 when none is declared: the character underlined in the row and the one that chooses this item while its menu is open.
    int
    mnemonicIndex()
    Index into label() of the character to underline: the one the label marks, else the first case-insensitive occurrence of a letter given to setMnemonic(char); -1 when there is no letter, no label, or the letter does not occur in it.
    static MenuItem
    of(String label, Runnable action)
    A command that runs action when chosen.
    static MenuItem
    of(MenuItem.Role role)
    The item of an editing role, whole: the command's name in the application's language, the chord the platform gives it, and no action, the role being the action.
    static MenuItem
    of(I18nString label, Runnable action)
    A command whose label follows the UI language; see I18nString.
    MenuItem.Role
    role()
     
    static MenuItem
    separator()
    A non-interactive divider line between groups of items.
    MenuItem
    setAccelerator(@Nullable Accelerator value)
    Declares the keyboard shortcut that runs this item while the menu is closed, and the hint drawn right-aligned in its row.
    MenuItem
    setChecked(boolean value)
    Sets a check item's state (does not fire onToggle).
    MenuItem
    setEnabled(boolean value)
    Enables or disables the item.
    MenuItem
    setIcon(@Nullable Icon value)
    Sets a picture shown before the label, in a menu the toolkit draws and in one the system draws, a tray's among them.
    MenuItem
    setMnemonic(char value)
    Declares the access letter: it is underlined in the row, and pressing it while this item's menu is open chooses the item (opens it, for a submenu).
    MenuItem
    setRole(MenuItem.Role value)
    Says what the item is to the system; see MenuItem.Role.
    static MenuItem
    submenu(String label, Menu submenu)
    An item that opens a nested submenu on hover / right-arrow.
    static MenuItem
    submenu(I18nString label, Menu submenu)
    A submenu item whose label follows the UI language.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • of

      public static MenuItem of(String label, Runnable action)
      A command that runs action when chosen.

    • of

      public static MenuItem of(I18nString label, Runnable action)
      A command whose label follows the UI language; see I18nString. UI thread.

    • of

      public static MenuItem of(MenuItem.Role role)
      The item of an editing role, whole: the command's name in the application's language, the chord the platform gives it, and no action, the role being the action. The label and the accelerator may be changed after.

      Redo is on Shift and the command key with Z on macOS and on Control with Y elsewhere, where each platform's users look for it; a text field takes both everywhere.

      Parameters:
      role - one of the six editing roles
      Throws:
      IllegalArgumentException - for a role that is not an editing command, whose item needs a label and an action: of(String, Runnable) and setRole(limn.components.MenuItem.Role)

    • check

      public static MenuItem check(String label, boolean checked, Consumer<Boolean> onToggle)
      A checkable item showing a check mark for its state; choosing it flips the state and calls onToggle with the new value.

    • check

      public static MenuItem check(I18nString label, boolean checked, Consumer<Boolean> onToggle)
      A checkable item whose label follows the UI language. UI thread.

    • separator

      public static MenuItem separator()
      A non-interactive divider line between groups of items.

    • label

      public @Nullable String label()
      The label as it currently reads, or null for a separator: its text in the language in effect, an access letter's & mark taken out ("&Open" reads "Open").

    • labelSource

      public @Nullable I18nString labelSource()
      The localizable value behind label(); null for a separator.

    • isEnabled

      public boolean isEnabled()
      Whether the item can be chosen; a disabled one still occupies a row.

    • role

      public MenuItem.Role role()
      Returns:
      what the item is to the system; MenuItem.Role.NONE unless setRole(limn.components.MenuItem.Role) said

    • setRole

      public MenuItem setRole(MenuItem.Role value)
      Says what the item is to the system; see MenuItem.Role.
      Throws:
      IllegalStateException - on a separator, a submenu or an item that checks, none of which the system has a place for; and for an editing role on an item made with an action, the role being the action: make it with of(Role)

    • icon

      public @Nullable Icon icon()
      Returns:
      the picture shown before the label, or null

    • setIcon

      public MenuItem setIcon(@Nullable Icon value)
      Sets a picture shown before the label, in a menu the toolkit draws and in one the system draws, a tray's among them. A menu with an icon on any item keeps the same room on every item, so the labels stay in line. A tintable icon takes the label's colour.
      Parameters:
      value - the icon, or null for none
      Returns:
      this item

    • setEnabled

      public MenuItem setEnabled(boolean value)
      Enables or disables the item.

    • isChecked

      public boolean isChecked()
      Returns:
      whether a check(java.lang.String, boolean, java.util.function.Consumer<java.lang.Boolean>) item is currently checked

    • setChecked

      public MenuItem setChecked(boolean value)
      Sets a check item's state (does not fire onToggle). UI thread when displayed.

    • accelerator

      public @Nullable Accelerator accelerator()
      The keyboard shortcut shown at the right of the row and dispatched while closed, or null.

    • setAccelerator

      public MenuItem setAccelerator(@Nullable Accelerator value)
      Declares the keyboard shortcut that runs this item while the menu is closed, and the hint drawn right-aligned in its row. null removes it. Set it before the menu is shown: an open cascade measured its rows against the hint it had then, and a change is not picked up until it is rebuilt.
      Throws:
      IllegalStateException - on a submenu item or a separator. No platform gives a submenu a shortcut, because a shortcut runs a command and opening a submenu is not one; a shortcut on the items inside it is what was meant.

    • mnemonic

      public char mnemonic()
      The access letter, uppercased, or 0 when none is declared: the character underlined in the row and the one that chooses this item while its menu is open. A letter the label marks with & ("&Open") wins over one given to setMnemonic(char), the translation being the one that knows the word.

    • setMnemonic

      public MenuItem setMnemonic(char value)
      Declares the access letter: it is underlined in the row, and pressing it while this item's menu is open chooses the item (opens it, for a submenu). Matched case-insensitively, and only against an enabled item: a disabled row is not reachable by its letter any more than by its arrow keys.

      The letter does not have to occur in the label; when it does not, nothing is underlined and the key still works.

      Parameters:
      value - a letter or digit; 0 removes the mnemonic
      Throws:
      IllegalArgumentException - for any other character (there is nothing to underline and no key code to match)
      IllegalStateException - on a separator

    • mnemonicIndex

      public int mnemonicIndex()
      Index into label() of the character to underline: the one the label marks, else the first case-insensitive occurrence of a letter given to setMnemonic(char); -1 when there is no letter, no label, or the letter does not occur in it. Recomputed from the current label, so it follows a label that changed with the UI language.