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

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

public class Menu
extends Object

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

A SeparatorField object can be added to a menu in the following ways:


Field Summary
static int CANCELLED
          Value returned from show() when the menu is cancelled.
static int INSTANCE_CONTEXT
          Menu instance is the context one.
static int INSTANCE_CONTEXT_SELECTION
          Menu instance is during selection.
static int INSTANCE_DEFAULT
          Menu instance is the default one.
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(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)
          Deprecated. Use add(MenuItem.separator(int)).
 int addSeparator()
          Adds separator item to this menu.
 void close()
          Closes the menu.
 void deleteAll()
          Removes all items from this menu.
 void deleteItem(int position)
          Deletes an item from this menu.
 MenuItem getDefault()
          Retrieves this menu's default item.
 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 currently selected 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.
 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 show() when the menu is cancelled.

Has the value -1.


INSTANCE_CONTEXT

public static final int INSTANCE_CONTEXT
Menu instance is the context one.
Since:
JDE 4.2.0

INSTANCE_CONTEXT_SELECTION

public static final int INSTANCE_CONTEXT_SELECTION
Menu instance is during selection.
Since:
JDE 4.2.0

INSTANCE_DEFAULT

public static final int INSTANCE_DEFAULT
Menu instance is the default one.
Since:
JDE 4.2.0

SORTED

public static final long SORTED
Style that sorts the menu.
Since:
JDE 3.6.0

UNDEFINED

public static final int UNDEFINED
Value of an undefined item ID.

Defined as -1.

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

This method invokes 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 this menu.
Throws:
NullPointerException - Thrown if contextMenu parameter is null.

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:
contextMenu - Array of menu items to add to this menu.
addSeparator - A boolean indicating whether or not to add a separator if the context menu is non empty.
Throws:
NullPointerException - Thrown if contextMenu parameter is null.

add

public void add(MenuItem item)
Adds a menu item to this menu.

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

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

add

public void add(String text,
                Object cookie,
                int id)
Deprecated. Use add(MenuItem.separator(int)).

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 parameter is null.

addSeparator

public int addSeparator()
Adds separator item to this menu.

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

Returns:
Position for the separator in this menu.

close

public void close()
Closes the menu.
Since:
JDE 4.0.2

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.

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

getItem

public MenuItem getItem(int position)
Retrieves menu item by position.
Parameters:
position - Position of menu item to retrieve.
Returns:
Menu item at provided position.
Since:
JDE 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 UNDEFINED.
Throws:
IllegalArgumentException - If position is invalid.

getSelectedCookie

public Object getSelectedCookie()
Deprecated. Use getSelectedItem() that returns a MenuItem.

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.

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 show().

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

getSelectedItem

public MenuItem getSelectedItem()
Retrieves currently selected item.
Returns:
Currently selected menu item.
Since:
JDE 4.0.0

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.

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 may be unsuccessful in case default the menu item was set by ContextMenu.

Parameters:
position - Position of the default menu item.
Throws:
IllegalArgumentException - If position is invalid.

setDefault

public void setDefault(MenuItem item)
Sets this menu's default item.

When this menu is activated, the default menu item is pre-selected. This call may be unsuccessful in case default menu item was set by ContextMenu or in case when menu item parameter was not added to current menu prior to setDefault was called.

Parameters:
item - Item to make 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 this menu.

This is the same field that creates the context menu.

Parameters:
field - Target field for this menu.
Since:
JDE 4.0.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 is updated properly next time it is used.

Returns:
Position of the chosen menu item or CANCELLED.



Copyright 1999-2009 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.