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

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

public class Menu
extends Object

Screen to provide 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 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)
          Adds text item to this menu with the given cookie and ID.
 int addSeparator()
          Adds separator item to this menu.
 void close()
           
 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.
 Object getItemCookie(int position)
          Retrieves the cookie for menu item at provided position.
 int getItemId(int position)
          Retrieves the ID for menu item at provided position.
 Object getSelectedCookie()
          Retreives cookie for the selected menu item.
 int getSelectedId()
          Retrieves the ID of the selected menu item.
 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)
          Sets the target field for this menu.
 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.


UNDEFINED

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

Defined as -1.


SORTED

public static final long SORTED
Style that sorts the menu.
Since:
JDE 3.6.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 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)
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.

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

getItemCookie

public Object getItemCookie(int position)
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)
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.

getSelectedId

public int getSelectedId()
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.

getSelectedCookie

public Object getSelectedCookie()
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.

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.

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.

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.

setTarget

public void setTarget(Field field)
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 it updated properly next time it is used.

Returns:
Position of the chosen menu item or CANCELLED.

close

public void close()
Since:
JDE 4.0.2


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