net.rim.device.api.ui
Class ContextMenu

java.lang.Object
  net.rim.device.api.ui.ContextMenu

public final class ContextMenu
extends Object

A context menu that provides actions "appropriate" to the current field hierarchy.

As of BlackBerry API 6.0, you can use the Command Framework API and the net.rim.device.api.ui.menu package to build a pop-up menu. Context menus built using previous versions of BlackBerry APIs are automatically converted to pop-up menus. See DefaultContextMenuProvider for more information on pop-up menus.

For example, an EditField in the hierarchy might add actions to the context menu for Cut and Paste operations (if appropriate for that particular edit field).

Each application supports a single context menu. Each time a Field in the application has its getContextMenu method invoked (to show the context menu for that field), the application's context menu gets re-populated (with the menu items appropriate for that field). The context menu's contents remain set until the next call to getContextMenu.

The context menu is stored as a simple array of MenuItem objects. The first menu item in the list, therefore, has position zero.

Each menu item added to the menu has, among other attributes, a priority value. The menu item with the highest priority (the priority value closest to zero) becomes the default menu item for the context menu. When the context menu appears to the user, the default menu item is selected, so the user simply has to click to choose it.

Field Summary
static int	UNDEFINED Value of an undefined item ID.

Method Summary
void	addItem(MenuItem item) Adds an item to the menu.
void	clear() Resets all values in this context menu and clears it of any menu items.
int	getDefault() Retrieves the position in this menu of the default menu item.
MenuItem	getDefaultItem() Retrieves the default item in this menu.
static ContextMenu	getInstance() Retrieves instance of the system context menu.
int	getSize() Retrieves the number of items in this menu.
Field	getTarget() Retrieves the target field for this context menu.
boolean	isDefaultSet() Determines if a default item is set for this menu.
boolean	isEmpty() Determines if this context menu is empty.
void	setDefault(int position) Sets item identified by position to default item for this menu.
boolean	setDefaultItem(MenuItem item) Sets default item for this context menu.
void	setTarget(Field target) Sets the target field for the context menu.

Methods inherited from class java.lang.Object

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

Field Detail

UNDEFINED

public static final int UNDEFINED

Value of an undefined item ID.

Defined as -1.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Method Detail

addItem

public void addItem(MenuItem item)
             throws IllegalStateException

Adds an item to the menu.

Use this method to add a MenuItem to the application's context menu. If the priority of the new item to add is "higher" (closer to zero) than that of the current default item, this method makes the newly added item the default.

If you override Field.makeContextMenu(net.rim.device.api.ui.ContextMenu), then you should invoke this method there.

Parameters:

item - Menu item to add to context menu.

Throws:

IllegalStateException - if setTarget has not yet been called

getDefaultItem

public MenuItem getDefaultItem()

Retrieves the default item in this menu.

Returns:

Default menu item for this menu, or null if non defined.

getDefault

public int getDefault()

Retrieves the position in this menu of the default menu item.

Returns:

Method retrieves the position of this menu's default item, or ContextMenu.UNDEFINED if this menu has no default menu item.

Since:

BlackBerry API 4.0.0

setDefaultItem

public boolean setDefaultItem(MenuItem item)

Sets default item for this context menu.

When this menu is opened, the default menu item will be highlighted.

Parameters:

item - Item in this menu that should be made the default item.

Returns:

True if specified item has been made the default; otherwise false (specified item did not already exist in this menu).

Since:

BlackBerry API 4.0.0

setDefault

public void setDefault(int position)

Sets item identified by position to default item for this menu.

Parameters:

position - Item position within this menu to make default; if the item at your position is ContextMenu.UNDEFINED, this method results in no default item being set for this menu.

Since:

BlackBerry API 4.0.0

isDefaultSet

public boolean isDefaultSet()

Determines if a default item is set for this menu.

Returns:

True if this menu has a default menu item set; otherwise, false.

Since:

BlackBerry API 4.0.0

getInstance

public static ContextMenu getInstance()

Retrieves instance of the system context menu.

Returns:

System context menu.

getSize

public int getSize()

Retrieves the number of items in this menu.

Returns:

Number of menu items in the context menu.

getTarget

public Field getTarget()

Retrieves the target field for this context menu.

When a field's Field.getContextMenu() method is invoked, it calls ContextMenu.setTarget(net.rim.device.api.ui.Field) to point to itself as the target field.

Returns:

Target field of the context menu.

isEmpty

public boolean isEmpty()

Determines if this context menu is empty.

Returns:

True if this menu has no items; otherwise, false.

setTarget

public void setTarget(Field target)

Sets the target field for the context menu.

When a field's Field.getContextMenu() method is invoked, it calls this method passing itself in as the parameter, making itself the target field for the context menu.

This method sets the current default priority value to the maximum integer value (absolutely lowest priority), and the number of items to zero.

Subsequent calls to ContextMenu.addItem(net.rim.device.api.ui.MenuItem) are used to populate the context menu.

Parameters:

target - Field to set as target for context menu.

clear

public void clear()

Resets all values in this context menu and clears it of any menu items.

Since:

BlackBerry API 4.0.0