net.rim.device.api.ui.component
Class Menu

java.lang.Object
  |
  +--net.rim.device.api.ui.component.Menu

public class Menu

extends Object

Screen to provide a menu.

Behaviour
Displays a menu in the top right corner of the screen. A menu is a vertically arranged list of items. The currently selected menu item is marked by inverting its rectangle.

To choose the selected menu item, one can either click the trackwheel or press ENTER. To dismiss the menu without choosing an item, one can press ESCAPE.

Menus also support prefix searching; if one presses a letter key, the next menu item that starts with that character gets selected.

Inner Class Summary

Field Summary

static int	CANCELLED Value returned from show() when the menu is cancelled.
static long	SORTED Style that sorts the menu.
static int	UNDEFINED Value of an undefined item ID.

Constructor Summary

Menu()
Constructs a new Menu.

Menu(long style)
Constructs a new Menu with the given style.

Method Summary

void	add(ContextMenu contextMenu) Adds a list of menu items to this menu.
void	add(ContextMenu contextMenu, boolean addSeparator) Adds a list of menu items to this menu.
void	add(MenuItem item) Adds a menu item to this menu.
void	add(String text, Object cookie, int id) Adds text item to this menu with the given cookie and ID.
int	addSeparator() Adds separator item to this menu.
void	deleteAll() Removes all items from this menu.
void	deleteItem(int position) Deletes an item from this menu.
Object	getItemCookie(int position) Retrieves the cookie for menu item at provided position.
int	getItemId(int position) Retrieves the ID for menu item at provided position.
Object	getSelectedCookie() Retreives cookie for the selected menu item.
int	getSelectedId() Retrieves the ID of the selected menu item.
int	getSize() Retrieves the number of items in this menu.
boolean	isDisplayed() Determines if this menu is currently visible.
void	setDefault(int position) Sets this menu's default item.
void	setDefault(MenuItem item) Sets this menu's default item.
void	setItemHighlight(int position, boolean highlight) Controls highlighting of a menu item.
int	show() Shows the menu to the user.

Methods inherited from class java.lang.Object

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

Field Detail

CANCELLED

public static final int CANCELLED

Value returned from show() when the menu is cancelled.

Has the value -1.

UNDEFINED

public static final int UNDEFINED

Value of an undefined item ID.

Defined as -1.

SORTED

public static final long SORTED

Style that sorts the menu.

Since:

JDE 3.6.0

Constructor Detail

Menu

public Menu()

Constructs a new Menu.

Menu

public Menu(long style)

Constructs a new Menu with the given style.

Parameters:

style - Combination of style flags from Screen or Manager.

Method Detail

add

public void add(ContextMenu contextMenu)

Adds a list of menu items to this menu.

This method simply invokes add(MenuItem) for each item in your provided array. Does not add a separator.

Parameters:

items - Array of menu items to add to this menu.

Throws:

NullPointerException - if contextMenu is null

Since:

JDE 3.7.0

add

public void add(ContextMenu contextMenu,
                boolean addSeparator)

Adds a list of menu items to this menu.

This method simply invokes add(MenuItem) for each item in your provided array.

Parameters:

items - Array of menu items to add to this menu.

addSeparator - add a separator if the context menu is non empty

Throws:

NullPointerException - if contextMenu is null

Since:

JDE 3.7.0

add

public void add(MenuItem item)

Adds a menu item to this menu. If item is null, this call is a nop.

When the user selects this menu item, the system invokes its Runnable.run() method.

Parameters:

item - Menu item to add.

Since:

JDE 3.7.0

add

public void add(String text,
                Object cookie,
                int id)

Adds text item to this menu with the given cookie and ID.

Parameters:

text - Text to display for the new item.

cookie - Cookie to associate with the new item.

id - ID to associate with the new item.

Throws:

NullPointerException - if text is null

Since:

JDE 3.7.0

addSeparator

public int addSeparator()

Adds separator item to this menu. The separator is added after the last MenuItem.

Returns:

Position for the separator in this menu.

deleteAll

public void deleteAll()

Removes all items from this menu.

Notice that this method does not delete the special Hide Menu item, nor the separator immediately following Hide Menu. This method also removes the focus from the menu, to assure that a new default item is chosen when the menu appears.

deleteItem

public void deleteItem(int position)

Deletes an item from this menu.

Parameters:

position - Position of menu item to delete.

Throws:

IllegalArgumentException - if position is invalid.

Since:

JDE 3.7.0

getItemCookie

public Object getItemCookie(int position)

Retrieves the cookie for menu item at provided position.

Parameters:

position - Position of the menu item.

Returns:

Cookie for menu item at position; if the item's cookie hasn't been set this method returns null.

Throws:

IllegalArgumentException - if position is invalid.

Since:

JDE 3.7.0

getItemId

public int getItemId(int position)

Retrieves the ID for menu item at provided position.

Parameters:

position - Position of the menu item.

Returns:

ID for menu item at position; if the item's ID hasn't been set, or if the item is a separator, this method returns UNDEFINED.

Throws:

IllegalArgumentException - if position is invalid.

Since:

JDE 3.7.0

getSelectedId

public int getSelectedId()

Retrieves the ID of the selected menu item.

This method only returns a meaningful method after this method is shown with show().

Returns:

ID of the selected menu item; if the menu item's ID has not been set, this method returns UNDEFINED.

getSelectedCookie

public Object getSelectedCookie()

Retreives cookie for the selected menu item.

This method only returns a meaningful method after this method is shown with show().

Returns:

Cookie for selected item; if the selected item hasn't had its cookie set, this method returns null.

getSize

public int getSize()

Retrieves the number of items in this menu.

Note that this method does not include the special Hide Menu item in its count, but does include separator items.

Returns:

Number of items in the menu.

isDisplayed

public boolean isDisplayed()

Determines if this menu is currently visible.

Returns:

True if this menu is currently visible; otherwise, false.

setItemHighlight

public void setItemHighlight(int position,
                             boolean highlight)

Controls highlighting of a menu item.

Parameters:

position - Position of the menu item.

highlight - If true, this method highlights a menu item and draws a box around it; if false, turn off the highlighting for menu item.

Since:

JDE 3.7.0

setDefault

public void setDefault(int position)

Sets this menu's default item.

When this menu is activated, the default menu item is pre-selected.

Parameters:

position - Position of the default menu item.

Throws:

IllegalArgumentException - if position is invalid.

Since:

JDE 3.7.0

setDefault

public void setDefault(MenuItem item)

Sets this menu's default item.

When this menu is activated, the default menu item is pre-selected.

Parameters:

item - Item to make as the first selection.

Since:

JDE 3.7.0

show

public int show()

Shows the menu to the user.

This menu shows this menu to the user; if a default menu item has been set for this menu, it shows pre-selected; otherwise, the first menu item in the list is selected.

This method blocks until the user either chooses a menu item, or dismisses the menu by pressing ESCAPE.

If the user chooses a menu item, this menu returns that item's position in the menu.

It also invokes contextMenu.setTarget(null) to ensure that the context menu it updated properly next time it is used.

Returns:

Position of the chosen menu item or CANCELLED.