Class Command

java.lang.Object
com.codename1.ui.Command
All Implemented Interfaces:
ActionListener<ActionEvent>
Direct Known Subclasses:
NavigationCommand, ShareService
public class Command extends Object implements ActionListener<ActionEvent>
The Command class provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.

  • Field Details

    • DESKTOP_MENU

      public static final String DESKTOP_MENU

      Client property key carrying the desktop native-menu placement hint for this command. When a desktop app bridges its commands to the native menu bar (title-bar mode native/custom), the value selects which menu the command appears under. Recognized values (case-insensitive): #DESKTOP_MENU_APP, #DESKTOP_MENU_ABOUT, #DESKTOP_MENU_PREFERENCES, #DESKTOP_MENU_QUIT, #DESKTOP_MENU_FILE, #DESKTOP_MENU_EDIT, #DESKTOP_MENU_VIEW, #DESKTOP_MENU_WINDOW, #DESKTOP_MENU_HELP. Any other value becomes a top-level menu with that literal title. Commands without the hint are grouped under a default application-commands menu.

      The value is a path: "File/Open Recent" puts the command in an "Open Recent" submenu of the File menu, created on demand, and deeper paths nest further. The first segment keeps the meaning above. Write // for a slash that is part of a title.

      See Also:

    • DESKTOP_MENU_APP

      public static final String DESKTOP_MENU_APP
      Standard desktop menu placement: the macOS application menu. Platforms without one put these commands in File.
      See Also:

    • DESKTOP_MENU_ABOUT

      public static final String DESKTOP_MENU_ABOUT
      The About standard command, read as #DESKTOP_ROLE_ABOUT: placed where each platform keeps it, see #setDesktopRole(String).
      See Also:

    • DESKTOP_MENU_PREFERENCES

      public static final String DESKTOP_MENU_PREFERENCES
      The Settings standard command, read as #DESKTOP_ROLE_SETTINGS: placed where each platform keeps it, see #setDesktopRole(String).
      See Also:

    • DESKTOP_MENU_QUIT

      public static final String DESKTOP_MENU_QUIT
      The Quit standard command, read as #DESKTOP_ROLE_QUIT: placed where each platform keeps it, see #setDesktopRole(String).
      See Also:

    • DESKTOP_MENU_FILE

      public static final String DESKTOP_MENU_FILE
      Standard desktop menu placement: the File menu.
      See Also:

    • DESKTOP_MENU_EDIT

      public static final String DESKTOP_MENU_EDIT
      Standard desktop menu placement: the Edit menu.
      See Also:

    • DESKTOP_MENU_VIEW

      public static final String DESKTOP_MENU_VIEW
      Standard desktop menu placement: the View menu.
      See Also:

    • DESKTOP_MENU_WINDOW

      public static final String DESKTOP_MENU_WINDOW
      Standard desktop menu placement: the Window menu.
      See Also:

    • DESKTOP_MENU_HELP

      public static final String DESKTOP_MENU_HELP
      Standard desktop menu placement: the Help menu.
      See Also:

    • DESKTOP_MENU_GROUP

      public static final String DESKTOP_MENU_GROUP
      Client property key carrying the separator group of this command within its desktop menu (as an Integer), see #setDesktopMenuGroup(int).
      See Also:

    • DESKTOP_SEPARATOR

      public static final String DESKTOP_SEPARATOR
      Client property key marking a command as a separator line in the desktop menu, see #createDesktopSeparator(String).
      See Also:

    • DESKTOP_CHECKED

      public static final String DESKTOP_CHECKED
      Client property key carrying the checked state of a check or radio desktop menu item (as a Boolean). Its presence makes the item checkable, see #setDesktopChecked(boolean).
      See Also:

    • DESKTOP_RADIO_GROUP

      public static final String DESKTOP_RADIO_GROUP
      Client property key carrying the name of the radio group of a desktop menu item, see #setDesktopRadioGroup(String).
      See Also:

    • DESKTOP_SHORTCUT_KEY

      public static final String DESKTOP_SHORTCUT_KEY
      Client property key carrying the upper-cased character of the desktop keyboard accelerator (as an Integer), see #setDesktopShortcut(char, int).
      See Also:

    • DESKTOP_SHORTCUT_MODIFIERS

      public static final String DESKTOP_SHORTCUT_MODIFIERS
      Client property key carrying the modifier bit-mask of the desktop keyboard accelerator (as an Integer), see #setDesktopShortcut(char, int).
      See Also:

    • DESKTOP_SHORTCUT_MODIFIER_PRIMARY

      public static final int DESKTOP_SHORTCUT_MODIFIER_PRIMARY
      Accelerator modifier flag for the platform's primary command key: Command on macOS, Control on Windows/Linux. This is the modifier used by the vast majority of menu shortcuts so it's the default.
      See Also:

    • DESKTOP_SHORTCUT_MODIFIER_SHIFT

      public static final int DESKTOP_SHORTCUT_MODIFIER_SHIFT
      Accelerator modifier flag for the Shift key.
      See Also:

    • DESKTOP_SHORTCUT_MODIFIER_ALT

      public static final int DESKTOP_SHORTCUT_MODIFIER_ALT
      Accelerator modifier flag for the Alt/Option key.
      See Also:

    • DESKTOP_ROLE

      public static final String DESKTOP_ROLE
      Client property key carrying the standard desktop role of this command, one of the DESKTOP_ROLE_* constants. See #setDesktopRole(String).
      See Also:

    • DESKTOP_ROLE_ABOUT

      public static final String DESKTOP_ROLE_ABOUT
      Standard command: shows the application's About information. In the application menu on macOS, at the foot of Help on Windows and Linux.
      See Also:

    • DESKTOP_ROLE_SETTINGS

      public static final String DESKTOP_ROLE_SETTINGS
      Standard command: opens the application's settings. "Settings" in the application menu on macOS, "Options" under Tools on Windows, "Preferences" at the foot of Edit on Linux.
      See Also:

    • DESKTOP_ROLE_QUIT

      public static final String DESKTOP_ROLE_QUIT
      Standard command: quits the application. "Quit" on macOS and Linux, "Exit" on Windows, and absent from a browser page, which cannot quit.
      See Also:

    • DESKTOP_ROLE_HIDE_APP

      public static final String DESKTOP_ROLE_HIDE_APP
      Standard command: hides the application. macOS only.
      See Also:

    • DESKTOP_ROLE_NEW

      public static final String DESKTOP_ROLE_NEW
      Standard command: creates a new document.
      See Also:

    • DESKTOP_ROLE_OPEN

      public static final String DESKTOP_ROLE_OPEN
      Standard command: opens a document.
      See Also:

    • DESKTOP_ROLE_SAVE

      public static final String DESKTOP_ROLE_SAVE
      Standard command: saves the document. Follows the document-modified state of its form or window, see Form#setDocumentModified(boolean).
      See Also:

    • DESKTOP_ROLE_SAVE_AS

      public static final String DESKTOP_ROLE_SAVE_AS
      Standard command: saves the document under a new name.
      See Also:

    • DESKTOP_ROLE_CLOSE

      public static final String DESKTOP_ROLE_CLOSE
      Standard command: closes the document or window.
      See Also:

    • DESKTOP_ROLE_PRINT

      public static final String DESKTOP_ROLE_PRINT
      Standard command: prints.
      See Also:

    • DESKTOP_ROLE_UNDO

      public static final String DESKTOP_ROLE_UNDO
      Standard command: undo.
      See Also:

    • DESKTOP_ROLE_REDO

      public static final String DESKTOP_ROLE_REDO
      Standard command: redo.
      See Also:

    • DESKTOP_ROLE_CUT

      public static final String DESKTOP_ROLE_CUT
      Standard command: cut.
      See Also:

    • DESKTOP_ROLE_COPY

      public static final String DESKTOP_ROLE_COPY
      Standard command: copy.
      See Also:

    • DESKTOP_ROLE_PASTE

      public static final String DESKTOP_ROLE_PASTE
      Standard command: paste.
      See Also:

    • DESKTOP_ROLE_SELECT_ALL

      public static final String DESKTOP_ROLE_SELECT_ALL
      Standard command: select all.
      See Also:

    • DESKTOP_ROLE_FIND

      public static final String DESKTOP_ROLE_FIND
      Standard command: find.
      See Also:

    • DESKTOP_ROLE_FULL_SCREEN

      public static final String DESKTOP_ROLE_FULL_SCREEN
      Standard command: toggles full screen.
      See Also:

    • DESKTOP_ROLE_MINIMIZE

      public static final String DESKTOP_ROLE_MINIMIZE
      Standard command: minimizes the window. Absent from a browser page.
      See Also:

    • DESKTOP_ROLE_ZOOM

      public static final String DESKTOP_ROLE_ZOOM
      Standard command: zooms (macOS) or maximizes the window. Absent from a browser page.
      See Also:

    • DESKTOP_ROLE_HELP

      public static final String DESKTOP_ROLE_HELP
      Standard command: opens the application's help.
      See Also:

    • DESKTOP_PLATFORMS

      public static final String DESKTOP_PLATFORMS
      Client property key carrying the platforms a command is published on, see #setDesktopPlatforms(String...).
      See Also:

    • DESKTOP_ENABLED_WHEN_MODIFIED

      public static final String DESKTOP_ENABLED_WHEN_MODIFIED
      Client property key that makes a command's enabled state follow the document-modified state of its form or window (as a Boolean), see #setDesktopEnabledWhenModified(boolean).
      See Also:

  • Constructor Details

    • Command

      public Command(String command)

      Creates a new instance of Command

      Parameters
      • command: the string that will be placed on the Soft buttons\Menu

    • Command

      public Command(String command, Image icon)

      Creates a new instance of Command

      Parameters

      • command: the string that will be placed on the Soft buttons\Menu

      • icon: the icon representing the command

    • Command

      public Command(String command, int id)

      Creates a new instance of Command

      Parameters

      • command: the string that will be placed on the Soft buttons\Menu

      • id: @param id user defined ID for a command simplifying switch statement code working with a command

    • Command

      public Command(String command, Image icon, int id)

      Creates a new instance of Command

      Parameters

      • command: the string that will be placed on the Soft buttons\Menu

      • icon: the icon representing the command

      • id: @param id user defined ID for a command simplifying switch statement code working with a command

  • Method Details

    • create

      public static Command create(String name, Image icon, ActionListener ev)

      Creates a new command instance that encapsulates the action listener and details, the main value of this approach is in our ability to write commands using the shorthand lambda syntax of Java 8.

      Parameters

      • name: the name/title of the command

      • icon: the icon for the command

      • ev: the even handler

      Returns

      a newly created Command instance

    • createMaterial

      public static Command createMaterial(String name, char icon, ActionListener ev)

      Creates a new command instance that encapsulates the action listener and details, the main value of this approach is in our ability to write commands using the shorthand lambda syntax of Java 8.

      Parameters

      • name: the name/title of the command

      • icon: the icon for the command

      • ev: the even handler

      Returns

      a newly created Command instance

    • getId

      public int getId()

      Return the command ID

      Returns

      the command ID

    • getCommandName

      public String getCommandName()

      gets the Command Name

      Returns

      the Command name

    • setCommandName

      public void setCommandName(String command)

      sets the Command name

      Parameters
      • command

    • getIcon

      public Image getIcon()

      Returns the icon representing the command

      Returns

      an icon representing the command

    • setIcon

      public void setIcon(Image icon)

      Sets the icon for the command

      Parameters
      • icon: the new icon

    • toString

      public String toString()

      Returns a string representation of the object

      Returns

      Returns a string representation of the object

      Overrides:
      toString in class Object

    • getPressedIcon

      public Image getPressedIcon()

      Indicates the icon that is displayed on the button when the button is in pressed state

      Returns

      icon used

    • setPressedIcon

      public void setPressedIcon(Image pressedIcon)

      Indicates the icon that is displayed on the button when the button is in pressed state

      Parameters
      • pressedIcon: icon used

    • getDisabledIcon

      public Image getDisabledIcon()

      Indicates the icon that is displayed on the button when the button is in the disabled state

      Returns

      icon used

    • setDisabledIcon

      public void setDisabledIcon(Image disabledIcon)

      Indicates the icon that is displayed on the button when the button is in the disabled state

      Parameters
      • disabledIcon: icon used

    • getRolloverIcon

      public Image getRolloverIcon()

      Indicates the icon that is displayed on the button when the button is in rolled over state

      Returns

      icon used

    • setRolloverIcon

      public void setRolloverIcon(Image rolloverIcon)

      Indicates the icon that is displayed on the button when the button is in rolled over state

      Parameters
      • rolloverIcon: icon to use

    • equals

      public boolean equals(Object obj)

      compare two commands

      Parameters
      • obj: a Command Object to compare
      Returns

      true if the obj has the same command name

      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()

      Allows storing commands in a vector/hashtable

      Returns

      unique hashcode for the command class

      Overrides:
      hashCode in class Object

    • actionPerformed

      public void actionPerformed(ActionEvent evt)

      This method is called when the soft button/Menu item is clicked

      Parameters
      • evt: the Event Object
      Specified by:
      actionPerformed in interface ActionListener<ActionEvent>

    • isDisposesDialog

      public boolean isDisposesDialog()
      Indicates whether this command causes the dialog to dispose implicitly, defaults to true

    • setDisposesDialog

      public void setDisposesDialog(boolean disposesDialog)
      Indicates whether this command causes the dialog to dispose implicitly, defaults to true

    • isEnabled

      public boolean isEnabled()

      Allows disabling/enabling the command

      Returns

      the enabled

    • setEnabled

      public void setEnabled(boolean enabled)

      Allows disabling/enabling the command

      Parameters
      • enabled: the enabled to set

    • getClientProperty

      public Object getClientProperty(String key)

      The client properties are a useful way to associate meta-data with a command without subclassing

      Parameters
      • key: an arbitrary user key
      Returns

      an arbitrary user object

    • putClientProperty

      public void putClientProperty(String key, Object value)

      The client properties are a useful way to associate meta-data with a command without sub classing

      Parameters

      • key: an arbitrary user key

      • value: an arbitrary user object, null to remove

    • setDesktopMenu

      public Command setDesktopMenu(String menu)

      Sets the desktop native-menu placement hint for this command. See #DESKTOP_MENU.

      Parameters
      • menu: one of the DESKTOP_MENU_* constants or a custom top-level menu title
      Returns

      this command, for chaining

    • getDesktopMenu

      public String getDesktopMenu()

      Returns the desktop native-menu placement hint, or null when unset. See #DESKTOP_MENU.

      Returns

      the placement hint or null

    • setDesktopMenuGroup

      public Command setDesktopMenuGroup(int group)

      Places this command in a separator group within its desktop menu. Items of one menu are ordered by group, keeping the order they were added in within a group, and the native menu draws a separator line wherever the group changes. Commands default to group 0.

      Parameters
      • group: the group number, lower groups come first
      Returns

      this command, for chaining

    • getDesktopMenuGroup

      public int getDesktopMenuGroup()

      Returns the separator group set with #setDesktopMenuGroup(int), 0 when unset.

      Returns

      the group number

    • createDesktopSeparator

      public static Command createDesktopSeparator(String menu)

      Creates a command that shows as a separator line in a desktop native menu, at the position it is added in. It has no label and never runs. Where groups already separate the items (#setDesktopMenuGroup(int)) it is not needed.

      Parameters
      • menu: the menu path the separator goes in, see #setDesktopMenu(String)
      Returns

      the separator command

    • isDesktopSeparator

      public boolean isDesktopSeparator()

      True when this command was created by #createDesktopSeparator(String).

      Returns

      true for a separator

    • setDesktopChecked

      public Command setDesktopChecked(boolean checked)

      Makes this command a check item in the desktop native menu and sets its state. When the user picks the item the state flips before the command runs, so the action reads the new value from #isDesktopChecked(). Changing the state while the command is in the native menu updates the menu.

      Parameters
      • checked: the checked state
      Returns

      this command, for chaining

    • isDesktopCheckable

      public boolean isDesktopCheckable()

      True when this command is a check or radio item, see #setDesktopChecked(boolean).

      Returns

      true when the item shows a check state

    • isDesktopChecked

      public boolean isDesktopChecked()

      The checked state of a check or radio item, false when the command is not checkable.

      Returns

      the checked state

    • setDesktopRadioGroup

      public Command setDesktopRadioGroup(String group)

      Makes this command a radio item of the named group in the desktop native menu. At most one command of a group is checked: checking one, from the menu or with #setDesktopChecked(boolean), unchecks the others. Picking the checked item again leaves it checked.

      Parameters
      • group: the radio group name, null to make this an ordinary item again
      Returns

      this command, for chaining

    • getDesktopRadioGroup

      public String getDesktopRadioGroup()

      Returns the radio group set with #setDesktopRadioGroup(String), or null.

      Returns

      the radio group name or null

    • setDesktopShortcut

      public Command setDesktopShortcut(char keyChar)

      Assigns a keyboard accelerator to this command for the desktop native menu bar using the platform's primary modifier (Command on macOS, Control elsewhere). For example setDesktopShortcut('S') produces Cmd+S / Ctrl+S next to the menu item. The hint is inert on platforms without a native menu bar, so it's safe to set unconditionally.

      Parameters
      • keyChar: the accelerator character (case-insensitive)
      Returns

      this command, for chaining

    • setDesktopShortcut

      public Command setDesktopShortcut(char keyChar, int modifiers)

      Assigns a keyboard accelerator to this command for the desktop native menu bar. See #setDesktopShortcut(char) for the common case.

      Parameters

      • keyChar: the accelerator character (case-insensitive)

      • modifiers: a bit-mask of #DESKTOP_SHORTCUT_MODIFIER_PRIMARY, #DESKTOP_SHORTCUT_MODIFIER_SHIFT and #DESKTOP_SHORTCUT_MODIFIER_ALT

      Returns

      this command, for chaining

    • getDesktopShortcutKeyChar

      public int getDesktopShortcutKeyChar()

      Returns the upper-cased accelerator character assigned via #setDesktopShortcut(char, int), or 0 when no accelerator is set.

      Returns

      the accelerator character or 0

    • getDesktopShortcutModifiers

      public int getDesktopShortcutModifiers()

      Returns the accelerator modifier bit-mask assigned via #setDesktopShortcut(char, int), or 0 when no accelerator is set.

      Returns

      the modifier bit-mask

    • setDesktopRole

      public Command setDesktopRole(String role)

      Marks this command as one of the standard commands every desktop application has, so the native menu bar puts it where the platform's own applications do: About, Settings and Quit in the application menu on macOS; About under Help, Options under Tools and Exit under File on Windows; Preferences under Edit on Linux. Each role also brings the platform's standard shortcut and its position within the menu.

      What the command sets itself wins: an explicit #setDesktopMenu(String), #setDesktopMenuGroup(int) or #setDesktopShortcut(char, int) overrides the role's. The label is the command's own name; #createDesktopRole(String, ActionListener) creates a command named the way the running platform names the role (Quit or Exit, Settings or Options or Preferences). A role the platform has no place for (Hide outside macOS, Quit in a browser) leaves the command out of that platform's menu bar.

      Parameters
      • role: one of the DESKTOP_ROLE_* constants, or null to clear it
      Returns

      this command, for chaining

    • getDesktopRole

      public String getDesktopRole()

      Returns the standard desktop role, or null when unset. See #setDesktopRole(String).

      Returns

      one of the DESKTOP_ROLE_* constants or null

    • createDesktopRole

      public static Command createDesktopRole(String role, ActionListener listener)

      Creates a command for a standard desktop role, named the way the running platform names it: "Quit" on macOS and Linux and "Exit" on Windows, "Settings", "Options" or "Preferences", "About" followed by the application name. The name can be translated through the cn1.menu.<role> resource key, for example cn1.menu.quit. See #setDesktopRole(String).

      Parameters

      • role: one of the DESKTOP_ROLE_* constants

      • listener: the action, may be null

      Returns

      the new command

    • setDesktopPlatforms

      public Command setDesktopPlatforms(String... platforms)

      Publishes this command on the native menu bar of the listed platforms only, for a command that only makes sense on some of them. The names are mac, win, linux and web (the JavaScript port's in-page menu). The command stays in the application's own menus everywhere; only the native menu bar is affected.

      Parameters
      • platforms: the platform names; none, or null, publishes it everywhere
      Returns

      this command, for chaining

    • isDesktopPlatform

      public boolean isDesktopPlatform(String platform)

      True when this command is published on the native menu bar of the named platform. See #setDesktopPlatforms(String...).

      Parameters
      • platform: mac, win, linux or web
      Returns

      true when no platform list is set or the list names this platform

    • setDesktopEnabledWhenModified

      public Command setDesktopEnabledWhenModified(boolean follow)

      Makes this command's enabled state follow the document-modified state of the form or window publishing it: enabled while the document has unsaved changes, disabled once it is saved. On by default for #DESKTOP_ROLE_SAVE. Nothing changes until the application calls Form#setDocumentModified(boolean) or Window#setDocumentModified(boolean).

      Parameters
      • follow: true to follow the modified state
      Returns

      this command, for chaining

    • isDesktopEnabledWhenModified

      public boolean isDesktopEnabledWhenModified()

      True when this command's enabled state follows the document-modified state. See #setDesktopEnabledWhenModified(boolean).

      Returns

      true when it follows the modified state

    • getMaterialIcon

      public char getMaterialIcon()
      Returns

      the materialIcon

    • setMaterialIcon

      public void setMaterialIcon(char materialIcon)
      Parameters
      • materialIcon: the materialIcon to set

    • getIconGapMM

      public float getIconGapMM()

      The gap between the text and the icon in millimeters or -1 for default

      Returns

      the iconGapMM

    • setIconGapMM

      public void setIconGapMM(float iconGapMM)

      The gap between the text and the icon in millimeters or -1 for default

      Parameters
      • iconGapMM: the iconGapMM to set

    • getMaterialIconSize

      public float getMaterialIconSize()
      Returns

      the materialIconSize

    • setMaterialIconSize

      public void setMaterialIconSize(float materialIconSize)
      Parameters
      • materialIconSize: the materialIconSize to set

    • getIconFont

      public Font getIconFont()
      Returns

      the set iconFont or null if none defined (meaning for material icons instead of the system default MaterialDesign font

    • setIconFont

      public void setIconFont(Font iconFont)
      Parameters
      • iconFont: use iconFont for material icons instead of the system default MaterialDesign font