javax.microedition.lcdui
Class Menu

java.lang.Object
  javax.microedition.lcdui.Menu

public class Menu
extends java.lang.Object

A visual container for Commands and other Menus. The Menu class is intended to be used in association with exact placement of commands to group together commands that do not fit on the given Display or should be grouped together for usability reasons.

Menu Creation and Population

A Menu object is always created empty, and later populated with commands using either the append() or insert() methods. A given Command may only be added once to a given Menu, but can be added to more than one Menu.

Versions of these methods are also provided for adding sub-menus to a menu, thereby enabling the creation of a menu tree. A menu may have multiple menus added to it as sub-menus, but a menu may be added to no more than one parent menu.

It is up to the implementation how to handle manipulation (addition/removal) of menu content when a menu is visible. The application may use the isVisible() method to find out if the Menu is presently visible on any Display.

The platform may limit the depth of sub-menus on a Display. The present depth of a menu, with the menu closest to the Displayable having depth 1, may be retrieved by the getMenuDepth() method. The device-wide maximum menu depth is returned by the getMaxMenuDepth() method; the implementation MUST support a menu depth of up to five(5) menus, but MAY support a higher menu depth.

Adding Menus to Displayables

Menus are added to a Displayable with the Displayable.setMenu method. The same Menu can be added to multiple Displayables at the same time. However, the platform MUST ensure that only the menu belonging to the Displayable currently in focus is shown. This means that the same menu button may appear on multiple Displays, but the menu itself can only be shown on one Display at a time. A Menu may generally be placed on the same exact placements as Commands. However, setMenu will throw java.lang.IllegalArgumentException when the attempted placement is not allowed. The reason for failure can be that the particular placement does not support menus. Doing additional setMenu to a Displayable with different placement will move the Menu to the new placement.

Note that a there is a difference between Displayable.setMenu(Menu) and Menu.append(Menu); A single Menu object may be added to multiple Displayables, but only be shown on one at the same time. The same Menu object may only be appended to one menu at any time.

As an example of using the Menu class, consider the following example. The developer wants to set up a menu tree consisting of a top menu with two levels of sub menus.

 Menu m, sm1, sm2;
 Command cmd1, cmd2, cmd3;
 Displayable d;

 m = new Menu("Menu", "This is the top menu", menupict.gif);
 sm1 = new Menu("sub-menu 1", "This is the middle sub-menu", menupict.gif);
 sm2 = new Menu("sub-menu 2", "This is the deepest sub-menu", menupict.gif);
 cmd1 = new Command("Command 1", "Command 1", Command.ITEM, 1);
 cmd2 = new Command("Command", "Second", Command.ITEM, 1);
 cmd3 = new Command("Third", "Third", Command.ITEM, 1);

 // Creating the menu structure
 m.append(cmd1);
 m.append(sm1);
 sm1.append(cmd2);
 sm1.append(sm2);
 sm2.append(cmd3);

 // Add the Menu to the Displayable on placement 101 (lower left corner).
 d.setMenu(m, 101);

 

The full structure of the menu above is shown in the following picture:

Visibility and Interaction

A menu is initially not visible, but is brought into view only as it is selected by the user, typically by pressing a associated soft key. The implementation must provide the ability to navigate a menu, to select a command in a menu, and to allow the user to leave the menu without selecting anything (this is required for all displays that support menus). When a Commmand is selected, it is passed to the CommandListener of the Displayable of the Display where the Menu is presently visible. It is up to the implementation to associate the correct Displayable with a particular Menu when it is to be used.When a command is selected, or the users navigates out of the menu, the menu should become invisible as soon as possible.

A Menu MUST NOT be visible on more than one Display at a time. If a Menu is visible on a Display that loses focus, then the Menu should be made invisible as soon as possible, and if the that Display should regain focus, the Menu should again start out as invisible. There MUST NOT be any interaction capability with a Menu that remains visible after its Display has lost focus.

Images

The application may add an Image to the Menu to be shown together with the labels. The device shows the image on a best effort basis, depending on what can be done on the particular display. For example, a Menu with an image is added to two different displays, one with high resolution and one with low, the implementation may decide either to show the image only on the high resolution display or ignore the image completely. Implementations may truncate or scale the icon image if it is larger than the size supported by device.

The Image may be mutable or immutable. If the Image is mutable, then a snapshot of its contents is taken before the Menu() constructor or setImage() method returns. The snapshot is used whenever the contents of the Menu are to be displayed. Even if the application subsequently draws into the Image, the snapshot is not modified until the next call to setImage(). If the Menu is visible on the display then the display SHOULD be updated with the new snapshot as soon as it is feasible for the implementation to do so.

Applications can query the implementation's Menu icon size by calling Display.getBestImageWidth(int) and Display.getBestImageHeight(int) methods using the Display.MENU image type. The style and appearance of menus are platform-dependent. If the image is changed after the Menu is first displayed, then it is up to the implementation to act on the change as soon as possible.

Since:

MIDP 3.0

Constructor Summary

Menu(java.lang.String shortLabel, java.lang.String longLabel, Image image)
Creates a new Menu object with the given labels and image.

Method Summary

int	append(Command cmd) Appends a Command to the Menu.
int	append(Menu menu) Appends a sub-menu to this Menu.
Command	getCommand(int index) Gets the command at index.
Font	getFont() Gets the application's preferred font for rendering the labels for this Menu.
Image	getImage() Gets the Image for this Menu.
java.lang.String	getLabel() Gets the label of the Menu.
java.lang.String	getLongLabel() Gets the long label of the Menu.
static int	getMaxMenuDepth() Returns the device-wide maximum menu depth.
Menu	getMenu(int index) Gets the sub-menu at index.
int	getMenuDepth() Returns this menu's depth within its menu tree.
void	insert(int index, Command cmd) Inserts a Command into the Menu just prior to the element specified.
void	insert(int index, Menu menu) Inserts a Menu into the Menu just prior to the element specified.
boolean	isCommand(int index) Checks if the element at the indicated index is a Command.
boolean	isEnabled() Gets a boolean value indicating whether the Menu is enabled or disabled.
boolean	isVisible() Gets a boolean value indicating whether the Menu is presently visible on any Display.
void	onParentEnabled(boolean enabled) Informs the menu of a change in its parent's enabled value.
void	remove(Command cmd) Removes a command from the menu.
void	remove(Menu menu) Removes a sub-menu from the menu.
void	setEnabled(boolean isEnabled) Sets the Menu into enabled or disabled mode.
void	setFont(Font font) Sets the application's preferred font for rendering the labels for this Menu.
void	setImage(Image image) Sets the Image for this Menu.
void	setLabel(java.lang.String shortLabel) Sets the short label of the Menu.
void	setLongLabel(java.lang.String longLabel) Sets the long label of the Menu.
int	size() Gets the number of Commands and sub-Menus in the Menu.

Methods inherited from class java.lang.Object

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

Constructor Detail

Menu

public Menu(java.lang.String shortLabel,
            java.lang.String longLabel,
            Image image)

Creates a new Menu object with the given labels and image.

The short label is required and must not be null. The long label is optional and may be null if the Menu is to have no long label. The labels are used like the labels on commands, they may also be used by the implementation as descriptive headers on the menu when it is being shown.

Parameters:

shortLabel - the Menu's short label

longLabel - the Menu's long label, or null if none

image - the Menu's image, or null if none

Throws:

java.lang.NullPointerException - if shortLabel is null

Method Detail

remove

public void remove(Command cmd)

Removes a command from the menu. The menu's size shrinks by one.

Throws:

java.lang.IllegalArgumentException - if cmd is not in menu

remove

public void remove(Menu menu)

Removes a sub-menu from the menu. The menu's size shrinks by one. The contents of the removed sub-menu and its sub-menus (if any) are not modified.

Parameters:

menu - the Menu to remove

Throws:

java.lang.IllegalArgumentException - if menu is not in menu

getMenuDepth

public int getMenuDepth()

Returns this menu's depth within its menu tree. The top menu is of depth 0, the menus attached to it are of depth 1, 2, etc. The top menu is the menu in the menu tree that has attached to a Displayable. The depth of a non-anchored menu will be -1.

Returns:

the depth of this menu within its menu tree

getMaxMenuDepth

public static int getMaxMenuDepth()

Returns the device-wide maximum menu depth. The maximum is at least five (5), but may be greater.

Returns:

the device-wide menu depth limit

append

public int append(Command cmd)

Appends a Command to the Menu. The added command will be the last element of the menu and the size of the Menu will grow by one. The Command cannot be already present in this menu (based on object reference comparison).

Parameters:

cmd - the command to be added

Returns:

the zero-based index of the Command in this menu

Throws:

java.lang.NullPointerException - if cmd is null

java.lang.IllegalArgumentException - if the cmd is already added to this menu.

append

public int append(Menu menu)

Appends a sub-menu to this Menu. The sub-menu will be the last element of the menu and the size of the menu will grow by one. A sub-menu can be in only one menu at a time; the application is responsible for removing the sub-menu from a previous menu, if any, before it can be appended to a new menu.

Parameters:

menu - the menu to be added

Returns:

the zero-based index of the Menu in this menu

Throws:

java.lang.NullPointerException - if menu is null

java.lang.IllegalArgumentException - if the menu already has a parent menu or if it is the top menu in this menu's tree.

java.lang.IllegalStateException - if the resulting menu depth exceeds the maximum depth supported by the implementation. The menu depth includes all of the menus above this menu, the menu being inserted, and all of its sub-menus.

isEnabled

public boolean isEnabled()

Gets a boolean value indicating whether the Menu is enabled or disabled.

Returns:

state of the Menu: true if enabled, false if disabled

isVisible

public boolean isVisible()

Gets a boolean value indicating whether the Menu is presently visible on any Display.

Note that this method does NOT indicate which Displayable that is currently shown on the Display in focus. Being visible means that the Menu or one of its sub-menus is being browsed.

Returns:

visibility: true if visible, false if invisible

setEnabled

public void setEnabled(boolean isEnabled)

Sets the Menu into enabled or disabled mode. A Menu which is disabled cannot be navigated into. If a Menu is set to disabled while it is visible, it should immediately be made invisible and focus should be taken back to the level containing this Menu.

Parameters:

isEnabled - true if enabled, false if disabled

getCommand

public Command getCommand(int index)

Gets the command at index. The index parameter must be within the range [0..size()-1], inclusive.

Returns:

the command at the given index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than or equal to size().

java.lang.IllegalArgumentException - if element at index is not a command

getMenu

public Menu getMenu(int index)

Gets the sub-menu at index. The index parameter must be within the range [0..size()-1], inclusive.

Returns:

the menu at the given index

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than or equal to size().

java.lang.IllegalArgumentException - if element at index is not a menu

getFont

public Font getFont()

Gets the application's preferred font for rendering the labels for this Menu. The value returned is the font that had been set by the application, even if that value had been disregarded by the implementation. If no font had been set by the application, or if the application explicitly set the font to null, the value is the default font chosen by the implementation.

Returns:

the preferred font to use to render the element

setFont

public void setFont(Font font)

Sets the application's preferred font for rendering the labels for this Menu. Note that the set font is for the Menu object itself, and not for the Commands and Menus it may contain. An menu's font is a hint, and the implementation may disregard the application's preferred font. Note that this method does not influence the fonts used by the contents (commands and sub-menus) of the menu, and these must be set individually using the respective setFont(Font) methods.

The font parameter must be a valid Font object or null. If the font parameter is null, the implementation must use its default font to render the element.

Parameters:

font - the preferred font to use to render the Menu's labels

insert

public void insert(int index,
                   Command cmd)

Inserts a Command into the Menu just prior to the element specified. The size of the Menu grows by one. The index parameter must be within the range [0..size()], inclusive. If the value of index equals size(), the new element is inserted immediately after the last element; in this case, the effect is identical to calling append().

Parameters:

index - the index of the element where insertion is to occur, starting from zero

cmd - the command to be inserted

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than size().

java.lang.NullPointerException - if cmd is null

java.lang.IllegalArgumentException - if the cmd is already added to this menu.

insert

public void insert(int index,
                   Menu menu)

Inserts a Menu into the Menu just prior to the element specified. The size of the Menu grows by one. The sub-menu can only be in one menu at a time. The application is responsible for removing the sub-menu from a previous menu, if any, before it can be inserted into a new menu. The index parameter must be within the range [0..size()], inclusive. If the value of index equals size(), the new element is inserted immediately after the last element; in this case, the effect is identical to calling append().

Parameters:

index - the index of the element where insertion is to occur, starting from zero

menu - the menu to be inserted

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than size().

java.lang.NullPointerException - if menu is null

java.lang.IllegalArgumentException - if the menu already has a parent menu or if it is the top menu in this menu's tree.

java.lang.IllegalStateException - if the resulting menu depth exceeds the maximum depth supported by the implementation. The menu depth includes all of the menus above this menu, the menu being inserted, and all of its sub-menus.

isCommand

public boolean isCommand(int index)

Checks if the element at the indicated index is a Command. The index parameter must be within the range [0..size()-1], inclusive. The index of the last element is size()-1

Returns:

true if element is a Command, or false if it is a Menu

Throws:

java.lang.IndexOutOfBoundsException - if index is less than zero or greater than or equal to size().

getImage

public Image getImage()

Gets the Image for this Menu.

Returns:

the Image for this Menu, or null if there is no image

setImage

public void setImage(Image image)

Sets the Image for this Menu.

Parameters:

image - the Image for this menu or null if the menu is not to have an Image

getLabel

public java.lang.String getLabel()

Gets the label of the Menu.

Returns:

the short label of the Menu

getLongLabel

public java.lang.String getLongLabel()

Gets the long label of the Menu.

Returns:

the long label of the Menu, or null if there is no long label

setLongLabel

public void setLongLabel(java.lang.String longLabel)

Sets the long label of the Menu.

Parameters:

longLabel - the long label, or null if there is no long label

setLabel

public void setLabel(java.lang.String shortLabel)

Sets the short label of the Menu. The label must be not be null.

Parameters:

shortLabel - the short label

Throws:

java.lang.NullPointerException - if label is null

size

public int size()

Gets the number of Commands and sub-Menus in the Menu.

Returns:

the number of Commands and sub-Menus in the Menu

onParentEnabled

public void onParentEnabled(boolean enabled)

Informs the menu of a change in its parent's enabled value. The application must itself decide how the Menu should handle this information. The default is to do nothing.

Since:

MIDP 3.0