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

java.lang.Object
  net.rim.device.api.ui.component.Menu

Direct Known Subclasses:

SubMenu

public class Menu
extends Object

Provides a Menu.

Behavior

When users press the Menu key, a menu appears in the lower-left corner of the screen.

Action	BlackBerry devices without a touch screen	BlackBerry devices with a touch screen
Move through the menu.	Roll the trackwheel or trackball. Slide a finger on the trackpad.	Touch and drag a menu item.
Move to a menu item.	Press the first letter of the label for a menu item.	-
Initiate the action associated with a menu item.	Press the Enter key or the Menu key, or click the trackwheel, trackball, or trackpad.	Click the menu item.
Close the menu.	Press the Escape key.	Press the Escape key.

You can add a SeparatorField object to a menu by using one of the following methods:

• Invoke Menu.add(ContextMenu, boolean) and set the addSeparator argument to true
• invoke Menu.addSeparator()

By default, the appearance of the menu is determined by the theme on the BlackBerry device. You can customize the menu by using methods in this class.

Field Summary
static int	CANCELLED Value returned from Menu.show() when the menu is cancelled.
static int	INSTANCE_CONTEXT Menu instance is the context menu.
static int	INSTANCE_CONTEXT_SELECTION Menu instance is during selection.
static int	INSTANCE_DEFAULT Menu instance is the default menu.
static int	MENU_POPUP
static long	SORTED Style that sorts the menu.
static int	UNDEFINED Value of an undefined item ID.

Constructor Summary

Menu()
Constructs a new Menu instance.

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

Method Summary
void	add(String text, Object cookie, int id) Deprecated. Use add(MenuItem.separator(int)).
void	add(ContextMenu contextMenu) Adds a list of menu items to the menu.
void	add(ContextMenu contextMenu, boolean addSeparator) Adds a list of menu items to the menu.
void	add(MenuItem item) Adds a menu item to the menu.
void	add(SubMenu submenu) Adds a submenu to the menu.
int	addSeparator() Adds separator item to the menu.
void	close() Closes the menu.
void	deleteAll() Removes all items from the menu.
void	deleteItem(int position) Deletes an item from the menu.
Background	getBackground() Retrieves the current background object of the menu.
Border	getBorder() Retrieves the current border object for the menu.
Background	getCaretBackground() Gets the caret background to show for the focused item.
MenuItem	getDefault() Retrieves this menu's default item.
Font	getFont() Retrieves the current font for the menu.
MenuItem	getItem(int position) Retrieves menu item by position.
Object	getItemCookie(int position) Deprecated. Use getItem(int) that returns a MenuItem.
int	getItemId(int position) Deprecated. Use getItem(int) that returns a MenuItem.
Object	getSelectedCookie() Deprecated. Use getSelectedItem() that returns a MenuItem.
int	getSelectedId() Deprecated. Use getSelectedItem() that returns a MenuItem.
MenuItem	getSelectedItem() Retrieves the currently selected menu item.
int	getSize() Retrieves the number of items in the menu.
boolean	isDisplayed() Determines if the menu is currently visible.
void	setBackground(Background background) Sets a custom background for the menu (normal state only) and overrides the background determined by the theme if it exists.
void	setBorder(Border border) Sets a custom border for the menu (normal and focus states) and overrides the border determined by the theme if it exists.
void	setCaretBackground(Background background) Sets a custom background for the selected item for the menu screen and overrides the existing theme background if it exists.
void	setDefault(int position) Sets this menu's default item.
void	setDefault(MenuItem item) Sets the menu's default item.
void	setFont(Font font) Sets the font for the menu screen (normal and focus states) and overrides the font determined by the theme.
void	setItemHighlight(int position, boolean highlight) Controls highlighting of a menu item.
void	setTarget(Field field) Deprecated.
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 Menu.show() when the menu is cancelled.

Has the value -1.

See Also:

Constant Field Values

UNDEFINED

public static final int UNDEFINED

Value of an undefined item ID.

Defined as -1.

See Also:

Constant Field Values

SORTED

public static final long SORTED

Style that sorts the menu.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

INSTANCE_DEFAULT

public static final int INSTANCE_DEFAULT

Menu instance is the default menu. This is the primary menu for a Screen.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

INSTANCE_CONTEXT

public static final int INSTANCE_CONTEXT

Menu instance is the context menu. This is a short menu that typically appears when a user clicks a field with no obvious single unambiguous action. The items in this menu should be field specific, or specific to the selected region. For example, a user clicking a phone number within a text field might display "Call..." and "SMS..." in this menu.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

INSTANCE_CONTEXT_SELECTION

public static final int INSTANCE_CONTEXT_SELECTION

Menu instance is during selection. This will typically contain items such as "Copy", "Cut", etc. An application might want to add selection specific items such as "Define...", or "Call...".

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

MENU_POPUP

public static final int MENU_POPUP

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Constructor Detail

Menu

public Menu()

Constructs a new Menu instance.

Menu

public Menu(long style)

Constructs a new Menu instance 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 the menu.

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

This method does not add a separator.

Parameters:

contextMenu - Array of menu items to add to the menu.

Throws:

NullPointerException - Thrown if contextMenu parameter is null.

add

public void add(ContextMenu contextMenu,
                boolean addSeparator)

Adds a list of menu items to the menu.

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

Parameters:

contextMenu - Array of menu items to add to the menu.

addSeparator - A boolean indicating whether or not to add a separator if the context menu is not empty.

Throws:

NullPointerException - Thrown if contextMenu parameter is null.

add

public void add(MenuItem item)

Adds a menu item to the menu.

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

Parameters:

item - Menu item to add; if null, this method does nothing.

add

public void add(SubMenu submenu)

Adds a submenu to the menu.

Parameters:

submenu - The submenu to add.

Throws:

IllegalArgumentException - If the submenu is null or the submenu's associated MenuItem is null.

Since:

BlackBerry API 6.0.0

add

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

Deprecated. Use add(MenuItem.separator(int)).

Adds text item to the 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 parameter is null.

addSeparator

public int addSeparator()

Adds separator item to the menu.

The separator is added after the last item in the menu.

Returns:

Position for the separator in the menu.

close

public void close()

Closes the menu.

Since:

BlackBerry API 4.0.2

deleteAll

public void deleteAll()

Removes all items from the menu.

This method removes the focus from the menu, to ensure that a new default item is chosen when the menu appears.

deleteItem

public void deleteItem(int position)

Deletes an item from the menu.

Parameters:

position - Position of menu item to delete.

Throws:

IllegalArgumentException - If position is invalid.

getCaretBackground

public Background getCaretBackground()

Gets the caret background to show for the focused item.

Returns:

Background object used for the focused item, null if none exists.

Since:

BlackBerry API 5.0.0

getDefault

public MenuItem getDefault()

Retrieves this menu's default item.

Returns:

Default menu item; if this menu is empty, the returned menu item does nothing.

Since:

BlackBerry API 4.0.0

getItem

public MenuItem getItem(int position)

Retrieves menu item by position.

Parameters:

position - Position of menu item to retrieve.

Returns:

The menu item at provided position.

Since:

BlackBerry API 4.2.1

getItemCookie

public Object getItemCookie(int position)

Deprecated. Use getItem(int) that returns a MenuItem.

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.

getItemId

public int getItemId(int position)

Deprecated. Use getItem(int) that returns a MenuItem.

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 Menu.UNDEFINED.

Throws:

IllegalArgumentException - If position is invalid.

getSelectedId

public int getSelectedId()

Deprecated. Use getSelectedItem() that returns a MenuItem.

Retrieves the ID of the selected menu item.

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

Returns:

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

getBackground

public Background getBackground()

Retrieves the current background object of the menu. Set a custom background and override the background determined by the theme by invoking Menu.setBackground(Background).

Returns:

Background object currently displayed or null if a custom or theme background does not exist.

Since:

BlackBerry API 5.0.0

getBorder

public Border getBorder()

Retrieves the current border object for the menu. A border represents the area within a field outside the padding and before the margin. Set a custom border and override the border determined by the theme by invoking Menu.setBorder(Border).

Returns:

Border object currently displayed or null if a custom or theme border does not exist.

Since:

BlackBerry API 5.0.0

getFont

public Font getFont()

Retrieves the current font for the menu. Set a custom font and override the font determined by the theme by invoking Menu.setFont(Font).

Returns:

Font object currently displayed or Font.getDefault() if no font has been set for the menu.

Since:

BlackBerry API 5.0.0

getSelectedCookie

public Object getSelectedCookie()

Deprecated. Use getSelectedItem() that returns a MenuItem.

Retrieves cookie for the selected menu item.

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

Returns:

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

getSelectedItem

public MenuItem getSelectedItem()

Retrieves the currently selected menu item.

Returns:

Currently selected menu item.

Since:

BlackBerry API 4.0.0

getSize

public int getSize()

Retrieves the number of items in the menu.

Note that this method includes separator items in its count.

Returns:

Number of items in the menu.

isDisplayed

public boolean isDisplayed()

Determines if the menu is currently visible.

Returns:

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

setDefault

public void setDefault(int position)

Sets this menu's default item.

When this menu is activated, the default menu item is pre-selected. This call might be unsuccessful if the default menu item was set by ContextMenu.

Parameters:

position - Position of the default menu item or Menu.UNDEFINED for undefined position.

Throws:

IllegalArgumentException - If position is less than 0 (and not Menu.UNDEFINED) or greater than the number of elements in this menu.

setCaretBackground

public void setCaretBackground(Background background)

Sets a custom background for the selected item for the menu screen and overrides the existing theme background if it exists. Setting the caret background to null will reset it back to the default theme caret background.

Parameters:

background - Background object display, null to use default theme caret background.

Since:

BlackBerry API 5.0.0

setBackground

public void setBackground(Background background)

Sets a custom background for the menu (normal state only) and overrides the background determined by the theme if it exists. If you want to reset the background to the theme background, set the background to null.

Parameters:

background - Background object display or null to use default theme background.

Since:

BlackBerry API 5.0.0

setBorder

public void setBorder(Border border)

Sets a custom border for the menu (normal and focus states) and overrides the border determined by the theme if it exists. The border is the area within a field outside the padding and before the margin. If you want to reset the border to the theme border, set the background to null. Note that the layout is automatically updated.

Parameters:

border - Border object to display or null to use default theme border.

Since:

BlackBerry API 5.0.0

setFont

public void setFont(Font font)

Sets the font for the menu screen (normal and focus states) and overrides the font determined by the theme. If necessary, this method updates the display.

Parameters:

font - Font object to display in the menu.

Since:

BlackBerry API 5.0.0

setDefault

public void setDefault(MenuItem item)

Sets the menu's default item.

When this menu appears, the default menu item is selected. Setting the default menu item might be unsuccessful if the default menu item was set by ContextMenu or if the menu item parameter was not added to current menu prior to invoking setDefault().

Parameters:

item - Menu item to set as the first selection.

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.

setTarget

public void setTarget(Field field)

Deprecated.

Sets the target field for the menu.

This is the same field that creates the context menu.

Parameters:

field - Target field for the menu.

Since:

BlackBerry API 4.0.0

show

public int show()

Shows the menu to the user.

If a default menu item was set for the menu, it is selected. Otherwise, the first menu item in the list is selected.

This method blocks until the user selects a menu item or dismisses the menu by pressing the Escape key.

If the user selects a menu item, the menu returns the position of the selected menu item in the menu.

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

Returns:

Position of the chosen menu item or Menu.CANCELLED.