SHOW Signed

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.

For example, an EditField in the heirarchy 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.

Method Summary

	void	addItem(MenuItem item) Adds an item to the menu.
	MenuItem	getDefaultItem() Gets the default item.
	static ContextMenu	getInstance() Retrieves instance of the system context menu.
	int	getSize() Gets the number of items in the menu.
	Field	getTarget() Gets the target field for the context menu.
	boolean	isEmpty() Determines if the context menu is empty.
	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

Method Detail

addItem

public void addItem(MenuItem item)

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(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

Since:

JDE 3.6

getDefaultItem

public MenuItem getDefaultItem()

Gets the default item.

Returns:

The menu position for the context menu's default item.

getInstance

public static ContextMenu getInstance()

Retrieves instance of the system context menu.

getSize

public int getSize()

Gets the number of items in the menu.

It's prudent to use this menu to retrieve the number of menu items in the context menu's list before using getItems to retrieve the list itself.

Returns:

The number of menu items in the context menu.

getTarget

public Field getTarget()

Gets the target field for the context menu.

When a field's getContextMenu method is invoked, it calls setTarget to point to itself as the target field.

Returns:

The target field of the context menu.

isEmpty

public boolean isEmpty()

Determines if the context menu is empty.

Returns:

True if the context menu has not items; otherwise, false.

setTarget

public void setTarget(Field target)

Sets the target field for the context menu.

When a field's 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 addItem are used to populate the context menu.

Parameters:

target - Field to set as target for context menu.

Since:

JDE 3.6