|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.component.Menu
public class Menu
Provides a Menu.
Behavior
When users press the Menu key, a menu appears in the lower-left corner of the screen.
Action | BlackBerry devices without a touch screen | BlackBerry devices with a touch screen |
---|---|---|
Move through the menu. | Roll the trackwheel or trackball. Slide a finger on the trackpad. | Touch and drag a menu item. |
Move to a menu item. | Press the first letter of the label for a menu item. | - |
Initiate the action associated with a menu item. | Press the Enter key or the Menu key, or click the trackwheel, trackball, or trackpad. | Click the menu item. |
Close the menu. | Press the Escape key. | Press the Escape key. |
You can add a SeparatorField
object to a menu by using one of the following methods:
Menu.add(ContextMenu, boolean)
and set the addSeparator argument
to true
Menu.addSeparator()
By default, the appearance of the menu is determined by the theme on the BlackBerry device. You can customize the menu by using methods in this class.
Field Summary | ||
---|---|---|
static int |
CANCELLED
Value returned from Menu.show() when the menu is cancelled. |
|
static int |
INSTANCE_CONTEXT
Menu instance is the context menu. |
|
static int |
INSTANCE_CONTEXT_SELECTION
Menu instance is during selection. |
|
static int |
INSTANCE_DEFAULT
Menu instance is the default menu. |
|
static int |
MENU_POPUP
|
|
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(String text,
Object cookie,
int id)
Deprecated. Use add(MenuItem.separator(int)) . |
|
void |
add(ContextMenu contextMenu)
Adds a list of menu items to the menu. |
|
void |
add(ContextMenu contextMenu,
boolean addSeparator)
Adds a list of menu items to the menu. |
|
void |
add(MenuItem item)
Adds a menu item to the menu. |
|
void |
add(SubMenu submenu)
Adds a submenu to the menu. |
|
int |
addSeparator()
Adds separator item to the menu. |
|
void |
close()
Closes the menu. |
|
void |
deleteAll()
Removes all items from the menu. |
|
void |
deleteItem(int position)
Deletes an item from the menu. |
|
Background |
getBackground()
Retrieves the current background object of the menu. |
|
Border |
getBorder()
Retrieves the current border object for the menu. |
|
Background |
getCaretBackground()
Gets the caret background to show for the focused item. |
|
MenuItem |
getDefault()
Retrieves this menu's default item. |
|
Font |
getFont()
Retrieves the current font for the menu. |
|
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 the currently selected menu item. |
|
int |
getSize()
Retrieves the number of items in the menu. |
|
boolean |
isDisplayed()
Determines if the menu is currently visible. |
|
void |
setBackground(Background background)
Sets a custom background for the menu (normal state only) and overrides the background determined by the theme if it exists. |
|
void |
setBorder(Border border)
Sets a custom border for the menu (normal and focus states) and overrides the border determined by the theme if it exists. |
|
void |
setCaretBackground(Background background)
Sets a custom background for the selected item for the menu screen and overrides the existing theme background if it exists. |
|
void |
setDefault(int position)
Sets this menu's default item. |
|
void |
setDefault(MenuItem item)
Sets the menu's default item. |
|
void |
setFont(Font font)
Sets the font for the menu screen (normal and focus states) and overrides the font determined by the theme. |
|
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 |
---|
public static final int CANCELLED
Menu.show()
when the menu is cancelled.
Has the value -1.
public static final int UNDEFINED
Defined as -1.
public static final long SORTED
public static final int INSTANCE_DEFAULT
public static final int INSTANCE_CONTEXT
public static final int INSTANCE_CONTEXT_SELECTION
public static final int MENU_POPUP
Constructor Detail |
---|
public Menu()
public Menu(long style)
style
- Combination of style flags from Screen
or
Manager
.Method Detail |
---|
public void add(ContextMenu contextMenu)
This method invokes Menu.add(MenuItem)
for each item in your
provided array.
This method does not add a separator.
contextMenu
- Array of menu items to add to the menu.
NullPointerException
- Thrown if contextMenu parameter is null
.public void add(ContextMenu contextMenu, boolean addSeparator)
This method simply invokes Menu.add(MenuItem)
for each item in
your provided array.
contextMenu
- Array of menu items to add to the menu.addSeparator
- A boolean indicating whether or not to add a
separator if the context menu is not empty.
NullPointerException
- Thrown if contextMenu
parameter is null
.public void add(MenuItem item)
When the user selects the menu item, the system invokes its
MenuItem.run()
method.
item
- Menu item to add; if null
, this method does nothing.public void add(SubMenu submenu)
submenu
- The submenu to add.
IllegalArgumentException
- If the submenu is null
or the submenu's associated MenuItem
is null
.public void add(String text, Object cookie, int id)
add(MenuItem.separator(int))
.
text
- Text to display for the new item.cookie
- Cookie to associate with the new item.id
- ID to associate with the new item.
NullPointerException
- If text parameter is null
.public int addSeparator()
The separator is added after the last item in the menu.
public void close()
public void deleteAll()
This method removes the focus from the menu, to ensure that a new default item is chosen when the menu appears.
public void deleteItem(int position)
position
- Position of menu item to delete.
IllegalArgumentException
- If position is invalid.public Background getCaretBackground()
Background
object used for the focused item, null
if none exists.public MenuItem getDefault()
public MenuItem getItem(int position)
position
- Position of menu item to retrieve.
public Object getItemCookie(int position)
position
- Position of the menu item.
null
.
IllegalArgumentException
- If position is invalid.public int getItemId(int position)
position
- Position of the menu item.
Menu.UNDEFINED
.
IllegalArgumentException
- If position is invalid.public int getSelectedId()
This method only returns a meaningful method after this method is
shown with Menu.show()
.
Menu.UNDEFINED
.public Background getBackground()
Menu.setBackground(Background)
.
Background
object currently displayed or null
if a custom or theme background does not exist.public Border getBorder()
Menu.setBorder(Border)
.
Border
object currently displayed or null
if a custom or theme border does not exist.public Font getFont()
Menu.setFont(Font)
.
Font.getDefault()
if no font has been
set for the menu.public Object getSelectedCookie()
This method only returns a meaningful method after this method is
shown with Menu.show()
.
null
.public MenuItem getSelectedItem()
public int getSize()
Note that this method includes separator items in its count.
public boolean isDisplayed()
public void setDefault(int position)
When this menu is activated, the default menu item is pre-selected.
This call might be unsuccessful if the default menu item was set by
ContextMenu
.
position
- Position of the default menu item or Menu.UNDEFINED
for undefined position.
IllegalArgumentException
- If position is less than 0 (and not Menu.UNDEFINED
)
or greater than the number of elements in this menu.public void setCaretBackground(Background background)
null
will reset it back to the default theme caret background.
background
- Background object display, null
to use default theme caret background.public void setBackground(Background background)
null
.
background
- Background object display or null
to use default theme background.public void setBorder(Border border)
null
. Note that the layout is automatically updated.
border
- Border object to display or null
to use default theme border.public void setFont(Font font)
font
- Font object to display in the menu.public void setDefault(MenuItem item)
When this menu appears, the default menu item is selected.
Setting the default menu item might be unsuccessful if the default menu item was set by
ContextMenu
or if the menu item parameter was not added to
current menu prior to invoking setDefault()
.
item
- Menu item to set as the first selection.public void setItemHighlight(int position, boolean highlight)
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.public void setTarget(Field field)
This is the same field that creates the context menu.
field
- Target field for the menu.public int show()
If a default menu item was set for the menu, it is selected. Otherwise, the first menu item in the list is selected.
This method blocks until the user selects a menu item or dismisses the menu by pressing the Escape key.
If the user selects a menu item, the menu returns the position of the selected menu item in the menu.
This method also invokes contextMenu.setTarget(null)
to ensure that the
context menu is updated the next time that it is used.
Menu.CANCELLED
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.