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

Since:
JDE 4.0.0
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(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

clear

public void clear()
Resets all values in this context menu and clears it of any menu items.
Since:
JDE 4.0.0

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 UNDEFINED if this menu has no default menu item.
Since:
JDE 4.0.0

getDefaultItem

public MenuItem getDefaultItem()
Retrieves the default item in this menu.
Returns:
Default menu item for this menu, or null if non defined.

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 setTarget(net.rim.device.api.ui.Field) to point to itself as the target field.

Returns:
Target field of the context menu.

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:
JDE 4.0.0

isEmpty

public boolean isEmpty()
Determines if this context menu is empty.
Returns:
True if this menu has no items; otherwise, false.

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 UNDEFINED, this method results in no default item being set for this menu.
Since:
JDE 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:
MenuItem - 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:
JDE 4.0.0

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 addItem(net.rim.device.api.ui.MenuItem) are used to populate the context menu.

Parameters:
target - Field to set as target for context menu.



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.