public class

MenuItem

extends Object
java.lang.Object
   ↳ com.neomades.ui.menu.MenuItem
Known Direct Subclasses

Class Overview

An item of a menu.

Menu.addItem(MenuItem) to add the item to the Menu.

A MenuItem is a graphical representation of a menu entry. Most of the time it is composed of an image and / or a text.

Cross Platform Considerations

Warning: Avoid creating static menu items in order to share them between screens.

On iOS, a MenuItem is a UIBarButtonItem. It can be displayed in the navigation bar (top of the screen setAsLeftAction() or setAsRightAction()) or in the tool bar (bottom of screen, default behavior).

Each item can have an image and a text, however, if the item is in the navigation bar, only the text or the image can be displayed (not both). In such a case, only the image will be displayed.

Images of MenuItem in the tool bar are displayed in white (a filter is automatically applied by the iOS system). Use setColoredImage() to bypass this behavior but be aware that this will remove the text of the MenuItem and its border if it has one STYLE_BORDERED.

More iOS specific options are available using setStyle(int) and setSystemItem(int).


On Android, a MenuItem is an android.view.MenuItem. It can be displayed in the action bar (top of the screen setAsLeftAction() or setAsRightAction()) or in the option menu (default behavior).

Each item can have an image and a text but be aware that in some cases, only the text or the image will be displayed (an item in the action bar to the left of the title will only have its image displayed, an item in the "more" entry of the option menu will only have its text displayed). Warning: the image of a menu item set as a left action cannot be replaced with a setImage(Image)

If the application do not use the action bar, all the menu items will be placed in the option menu, even if setAsLeftAction() or setAsRightAction() were set.


Image sizes and properties

iOS

iOS ignores all color information, so there’s no need to use more than one fill color. Allow transparency to define the shape of the icon. Here are the required icons dimensions:

  • 22x22 pixels (mdpi)
  • 44x44 pixels (xhdpi)
  • 66x66 pixels (xxhdpi)

Android

Action Bar icons should be 32-bit PNGs with an alpha channel for transparency. Here are the required icons dimensions:

  • 18x18 pixels (ldpi)
  • 24x24 pixels (mdpi)
  • 36x36 pixels (hdpi)
  • 48x48 pixels (xhdpi)

See Also

Summary

Constants
int SHOW_AS_ACTION_ALWAYS Android: Always show this MenuItem as a button in an Android Action Bar.
int SHOW_AS_ACTION_IF_ROOM Android: Show this item as a button in an Action Bar if the system decides there is room for it.
int SHOW_AS_ACTION_NEVER Android: Never show this item as a button in an Android Action Bar.
int SHOW_AS_ACTION_WITH_TEXT Android: When this item is in the action bar, always show it with a text label even if it also has an icon specified.
int STYLE_BORDERED iOS MenuItem style with border
int STYLE_DONE iOS MenuItem style Done (border and darker background)
int STYLE_PLAIN iOS MenuItem style plain (no border)
int SYSTEM_ITEM_ACTION iOS MenuItem system Action
int SYSTEM_ITEM_ADD iOS MenuItem system Add
int SYSTEM_ITEM_BOOKMARKS iOS MenuItem system Bookmarks
int SYSTEM_ITEM_CAMERA iOS MenuItem system Camera
int SYSTEM_ITEM_CANCEL iOS MenuItem system Cancel
int SYSTEM_ITEM_COMPOSE iOS MenuItem system Compose
int SYSTEM_ITEM_DONE iOS MenuItem system Done
int SYSTEM_ITEM_EDIT iOS MenuItem system Edit
int SYSTEM_ITEM_FASTFORWARD iOS MenuItem system FastForward
int SYSTEM_ITEM_FIXEDSPACE iOS MenuItem system FixedSpace
int SYSTEM_ITEM_FLEXIBLESPACE iOS MenuItem system FlexibleSpace
int SYSTEM_ITEM_ORGANIZE iOS MenuItem system Organize
int SYSTEM_ITEM_PAGECURL iOS MenuItem system PageCurl
int SYSTEM_ITEM_PAUSE iOS MenuItem system Pause
int SYSTEM_ITEM_PLAY iOS MenuItem system Play
int SYSTEM_ITEM_REDO iOS MenuItem system Redo
int SYSTEM_ITEM_REFRESH iOS MenuItem system Refresh
int SYSTEM_ITEM_REPLY iOS MenuItem system Reply
int SYSTEM_ITEM_REWIND iOS MenuItem system Rewind
int SYSTEM_ITEM_SAVE iOS MenuItem system Save
int SYSTEM_ITEM_SEARCH iOS MenuItem system Search
int SYSTEM_ITEM_STOP iOS MenuItem system Stop
int SYSTEM_ITEM_TRASH iOS MenuItem system Trash
int SYSTEM_ITEM_UNDO iOS MenuItem system Undo
Public Constructors
MenuItem(Image img)
Constructs an item with the given image.
MenuItem(int textId)
Constructs an item with the text of the id given in parameter.
MenuItem(int textId, int imageId)
Constructs an item with the text and the image of the ids given in parameter.
MenuItem(String text)
Constructs an item with the given text.
MenuItem(String text, Image img)
Constructs an item with the given text and image.
Public Methods
int getItemId()
Returns the identifier for this menu item.
boolean isEnabled()
Returns a boolean indicating if the menu item is enabled or not.
boolean isVisible()
Returns a boolean indicating if the menu item is visible or not.
MenuItem setAsLeftAction()
Sets this menu item in the title bar as an action, at the left of the screen title.
MenuItem setAsRightAction()
Sets this menu item in the title bar as an action, at the right of the screen title.
MenuItem setColoredImage()
Enables colored image for menu items in the UIToolBar for iOS.
MenuItem setEnabled(boolean enabled)
Sets whether the menu item is enabled.
MenuItem setFullSizeImage(boolean enabled)
Enables or disables the icon in full size mode for Android devices.
void setImage(Image image)
Sets or replaces the image shown by the MenuItem.
void setImage(int imageResId)
Sets or replaces the image shown by the MenuItem.
MenuItem setItemId(int id)
Sets an integer identifier for the menu item.
MenuItem setShowAsAction(int flags)
Sets how this item should display in the presence of an Action Bar.
MenuItem setShowsAsUpEnabled(boolean enabled)
Enables or disables the left action item in the title bar as an "Up" navigation action.
MenuItem setStyle(int style)
Sets the MenuItem's iOS style.
MenuItem setSystemItem(int systemItem)
Sets to the menu item the appearance of an iOS system item.
void setText(String text)
Sets the text of this item.
void setText(int textResId)
Sets the text of this item.
MenuItem setTextColor(Color textColor)
Sets the text color of this item.
MenuItem setVisible(boolean visible)
Sets whether the menu item is visible or not.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int SHOW_AS_ACTION_ALWAYS

Android: Always show this MenuItem as a button in an Android Action Bar.

Constant Value: 2 (0x00000002)

public static final int SHOW_AS_ACTION_IF_ROOM

Android: Show this item as a button in an Action Bar if the system decides there is room for it.

Constant Value: 1 (0x00000001)

public static final int SHOW_AS_ACTION_NEVER

Android: Never show this item as a button in an Android Action Bar.

Constant Value: 0 (0x00000000)

public static final int SHOW_AS_ACTION_WITH_TEXT

Android: When this item is in the action bar, always show it with a text label even if it also has an icon specified.

Constant Value: 4 (0x00000004)

public static final int STYLE_BORDERED

iOS MenuItem style with border

Constant Value: 1 (0x00000001)

public static final int STYLE_DONE

iOS MenuItem style Done (border and darker background)

Constant Value: 2 (0x00000002)

public static final int STYLE_PLAIN

iOS MenuItem style plain (no border)

Constant Value: 0 (0x00000000)

public static final int SYSTEM_ITEM_ACTION

iOS MenuItem system Action

Constant Value: -10 (0xfffffff6)

public static final int SYSTEM_ITEM_ADD

iOS MenuItem system Add

Constant Value: -5 (0xfffffffb)

public static final int SYSTEM_ITEM_BOOKMARKS

iOS MenuItem system Bookmarks

Constant Value: -12 (0xfffffff4)

public static final int SYSTEM_ITEM_CAMERA

iOS MenuItem system Camera

Constant Value: -16 (0xfffffff0)

public static final int SYSTEM_ITEM_CANCEL

iOS MenuItem system Cancel

Constant Value: -2 (0xfffffffe)

public static final int SYSTEM_ITEM_COMPOSE

iOS MenuItem system Compose

Constant Value: -8 (0xfffffff8)

public static final int SYSTEM_ITEM_DONE

iOS MenuItem system Done

Constant Value: -1 (0xffffffff)

public static final int SYSTEM_ITEM_EDIT

iOS MenuItem system Edit

Constant Value: -3 (0xfffffffd)

public static final int SYSTEM_ITEM_FASTFORWARD

iOS MenuItem system FastForward

Constant Value: -21 (0xffffffeb)

public static final int SYSTEM_ITEM_FIXEDSPACE

iOS MenuItem system FixedSpace

Constant Value: -7 (0xfffffff9)

public static final int SYSTEM_ITEM_FLEXIBLESPACE

iOS MenuItem system FlexibleSpace

Constant Value: -6 (0xfffffffa)

public static final int SYSTEM_ITEM_ORGANIZE

iOS MenuItem system Organize

Constant Value: -11 (0xfffffff5)

public static final int SYSTEM_ITEM_PAGECURL

iOS MenuItem system PageCurl

Constant Value: -24 (0xffffffe8)

public static final int SYSTEM_ITEM_PAUSE

iOS MenuItem system Pause

Constant Value: -19 (0xffffffed)

public static final int SYSTEM_ITEM_PLAY

iOS MenuItem system Play

Constant Value: -18 (0xffffffee)

public static final int SYSTEM_ITEM_REDO

iOS MenuItem system Redo

Constant Value: -23 (0xffffffe9)

public static final int SYSTEM_ITEM_REFRESH

iOS MenuItem system Refresh

Constant Value: -14 (0xfffffff2)

public static final int SYSTEM_ITEM_REPLY

iOS MenuItem system Reply

Constant Value: -9 (0xfffffff7)

public static final int SYSTEM_ITEM_REWIND

iOS MenuItem system Rewind

Constant Value: -20 (0xffffffec)

public static final int SYSTEM_ITEM_SAVE

iOS MenuItem system Save

Constant Value: -4 (0xfffffffc)

public static final int SYSTEM_ITEM_SEARCH

iOS MenuItem system Search

Constant Value: -13 (0xfffffff3)

public static final int SYSTEM_ITEM_STOP

iOS MenuItem system Stop

Constant Value: -15 (0xfffffff1)

public static final int SYSTEM_ITEM_TRASH

iOS MenuItem system Trash

Constant Value: -17 (0xffffffef)

public static final int SYSTEM_ITEM_UNDO

iOS MenuItem system Undo

Constant Value: -22 (0xffffffea)

Public Constructors

public MenuItem (Image img)

Constructs an item with the given image.

Cross Platform considerations

On Android, the image will not be displayed when used as a classic MenuItem. Use it as a left or right action instead.

Parameters
img the image of the item
See Also

public MenuItem (int textId)

Constructs an item with the text of the id given in parameter.

Parameters
textId the id of the text

public MenuItem (int textId, int imageId)

Constructs an item with the text and the image of the ids given in parameter.

Cross Platform considerations

On Android, the image will not be displayed when used as a classic MenuItem. Use it as a left or right action instead.

Parameters
textId the id of the text
imageId the id of the image

public MenuItem (String text)

Constructs an item with the given text.

Parameters
text the text of the item

public MenuItem (String text, Image img)

Constructs an item with the given text and image.

Cross Platform considerations

On Android, the image will not be displayed when used as a classic MenuItem. Use it as a left or right action instead.

Parameters
text the text of the item
img the image of the item

Public Methods

public int getItemId ()

Returns the identifier for this menu item. The identifier can not be changed after the menu is created.

Returns
  • the menu item identifier

public boolean isEnabled ()

Returns a boolean indicating if the menu item is enabled or not.

Returns
  • true if the menu item is enabled, false if it is disabled
See Also

public boolean isVisible ()

Returns a boolean indicating if the menu item is visible or not.

Returns
  • true if the menu item is visible, false if it is not visible
See Also

public MenuItem setAsLeftAction ()

Sets this menu item in the title bar as an action, at the left of the screen title. Note that this method may have no effect if call after addItem(MenuItem).

The first MenuItem for which this method is called will be placed in the action bar (title bar) at the left of the title. Thus, it will replace the "back" button (or "home" button depending on the platform). If several menu items are "set as left action", only the first is set as left, the others are placed at the right of the title.

Cross Platform considerations

In iOS, by default, if a MenuItem in the title bar has an image and a text, only the image will be displayed with a border. If the MenuItem has only a text, the text will be displayed. Note that if there is no title for the screen, the title bar and the menu entries are not displayed.

In Android, by default, if a MenuItem in the title bar has an image and a text, only the image will be displayed. If the MenuItem has only a text, the application icon will be kept but the default action will be cancelled.

Returns
  • this menu item

public MenuItem setAsRightAction ()

Sets this menu item in the title bar as an action, at the right of the screen title. Note that this method may have no effect if call after addItem(MenuItem).

Cross Platform considerations

In iOS, by default, if the MenuItem has an image and a text, only the image will be displayed with a border. If the MenuItem has only a text, the text will be displayed. Note that if there is no title for the screen, the navigation bar and the menu entries are not displayed.

Returns
  • this menu item

public MenuItem setColoredImage ()

Enables colored image for menu items in the UIToolBar for iOS. By default, the image in the UIToolBar are white (a filter is applied on the image by the system). Calling this method, images will keep their color. However, the text and the border of the item will be ignored.

Limitations

In Android, this method has no effect.

Returns
  • the current item

public MenuItem setEnabled (boolean enabled)

Sets whether the menu item is enabled. Disabling a menu item will not allow it to be invoked. The menu item will still be visible.

Parameters
enabled If true then the item will be invokable; if false it won't be invokable.
Returns
  • the current item
See Also

public MenuItem setFullSizeImage (boolean enabled)

Enables or disables the icon in full size mode for Android devices.

By default on Android, ActionBar icons are scaled inside an action area with padding.
This methods could remove this native padding.

Limitations

On iOS, this method has no effect.

Parameters
enabled true to enable the icon in full size mode
Returns
  • the current item

public void setImage (Image image)

Sets or replaces the image shown by the MenuItem. Warning: The image of the left action cannot be replaced.

public void setImage (int imageResId)

Sets or replaces the image shown by the MenuItem.

public MenuItem setItemId (int id)

Sets an integer identifier for the menu item.

Parameters
id the identifier
Returns
  • this menu item

public MenuItem setShowAsAction (int flags)

Sets how this item should display in the presence of an Action Bar. The parameter actionEnum is a flag set. One of SHOW_AS_ACTION_ALWAYS, SHOW_AS_ACTION_IF_ROOM, or SHOW_AS_ACTION_NEVER should be used, and you may optionally OR the value with SHOW_AS_ACTION_WITH_TEXT. SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, it should be shown with a text label.

Limitations

In iOS, this method has no effect.

Parameters
flags How the item should display. One of SHOW_AS_ACTION_ALWAYS, SHOW_AS_ACTION_IF_ROOM, or SHOW_AS_ACTION_NEVER. SHOW_AS_ACTION_NEVER is the default.
Returns
  • this menu item
See Also

public MenuItem setShowsAsUpEnabled (boolean enabled)

Enables or disables the left action item in the title bar as an "Up" navigation action.

Limitations

In iOS, this method has no effect.

Returns
  • the current item

public MenuItem setStyle (int style)

Sets the MenuItem's iOS style. The effect of the style is different if the item is in the tool bar or in the navigation bar.

  • STYLE_BORDERED: in the navigation bar, this style surrounds the item with a border. In the tool bar, if the item has an image, or a text and an image, it surrounds the image with a border, else it surrounds the text with a border. This style is applied by default on all menu items in iOS, except if the item is in the tool bar and has a text and an image.
  • STYLE_PLAIN: in the navigation bar, if the item has an image, it displays it without border, else, if the item has a text (and only a text), it displays it with a border. In the tool bar, it displays the item without borders.
  • STYLE_DONE: same style as STYLE_BORDERED but with an other background color (like if the action of the item was "done").

Limitations

In Android, this method has no effect.

Parameters
style the iOS Style (STYLE_BORDERED, STYLE_PLAIN, STYLE_DONE)
Returns
  • this menu item
See Also

public MenuItem setSystemItem (int systemItem)

Sets to the menu item the appearance of an iOS system item.

Limitations

In Android, this method has no effect.

Parameters
systemItem the id of the system item (only used for iOS)
Returns
  • this menu item
See Also

public void setText (String text)

Sets the text of this item.

public void setText (int textResId)

Sets the text of this item.

public MenuItem setTextColor (Color textColor)

Sets the text color of this item.

Cross Platform Considerations

On Android, this method does nothing.

Returns
  • the current item

public MenuItem setVisible (boolean visible)

Sets whether the menu item is visible or not.

Cross Platform Considerations

On Android platform, visibility cannot be changed on left item, it is always visible.

Parameters
visible If true the item will be visible
Returns
  • the current item
See Also