net.rim.device.api.ui
Class MenuItem

java.lang.Object
  net.rim.device.api.ui.MenuItem

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

SendCommandMenuItem

public class MenuItem
extends Object
implements Runnable

Represents an abstract menu item.

Each item has an ordinal specifying the sort order within the menu. A separator is automatically inserted between adjacent items whose ordinals differ by at least 0x00010000. Each item also has a priority specifying which one should be the default. A lower value indicates a higher priority.

Creating menu items by using commands

Since BlackBerry API 6.0, you can use the Command Framework API to create a menu item. The process is as follows:

1. Define the functionality to be performed by using a CommandHandler. The command handler might be limited to your application, or might be registered so it is available to any application on the BlackBerry device.
2. In your screen, optionally specify the context of the menu item by invoking setCommandContext(). The context might be required in order to determine what the command handler should do.
3. Associate the menu item with a Command by invoking setCommand(). The Command defines what to execute when the menu item is selected by acting as a proxy to an instance of a class that extends a command handler. The command is only executed if there is no implementation of Runnable. If the context was specified, it is passed to the command's execute method. Otherwise, this menu item is passed.

Code sample

 class MyUiScreen extends MainScreen
 {
     public MyUiScreen()
     {
       //...
       // Create MenuItem with command context
       MenuItem myItem = new MenuItem(new StringProvider("My Menu Item"), 0x230000, 0);
       myItem.setCommandContext(new Object()
       {
           public String toString()
           {
               return "My MenuItem Object"; 
           }          
       });
       // Set command to be invoked by the MenuItem
       myItem.setCommand(new Command(new DialogCommandHandler()));
      
       addMenuItem(myItem);
     }

 // A CommandHandler implementation which will be executed unconditionally
 class DialogCommandHandler extends CommandHandler
 {
     public void execute(ReadOnlyCommandMetadata metadata, Object context)
     {
         Dialog.alert("Executing command for " + context.toString());
     }           
 }
 

Creating menu items by subclassing and implementing Runnable

If subclassing the extending class must implement the Runnable interface, which in turn supports abstract dispatching of menu actions on activation.

    ...
    // setup the menu items
    MenuItem item = new MyMenuItem();
    menu.addItem(item);
    ...
    class MyMenuItem extends MenuItem {
        MyMenuItem() {
            super(MyResourceBundle.getBundle(), MyResource.MY_MENU_ITEM, 0x230000, 0);
        }
        public void run() {
            // do something
        }
    }
 

Field Summary
static int	CANCEL_SELECT Cancel selection menu item.
static int	CHANGE_OPTION Change option menu item.
static int	CLOSE Close menu item.
static int	COPY Copy menu item.
static int	CUT Cut menu item.
static Comparator	ORDINAL_COMPARATOR Menu item comparator..
static int	PASTE Paste menu item.
static int	SAVE_CLOSE Save menu item.
static int	SELECT Select menu item.

Constructor Summary

MenuItem(String text, int ordinal, int priority)
Deprecated. Use MenuItem(StringProvider, int, int)

MenuItem(ResourceBundle bundle, int id, int ordinal, int priority)
Constructs a new MenuItem instance.

MenuItem(StringProvider text, int ordinal, int priority)
Constructs a new MenuItem instance.

Method Summary
static MenuItem	createMenuItem(Command command) Creates a MenuItem given a Command.
ResourceBundle	getBundle() Retrieves resource bundle of this menu item.
Command	getCommand() Retrieves this menu item's command.
Object	getCommandContext() Retrieves this menu item's command context.
Image	getIcon() Retrieves the icon associated with this menu item.
int	getId() Retrieves ID of this menu item.
int	getOrdinal() Retrieves relative ordering of this menu item.
static MenuItem	getPrefab(int id) Retrieves a prefabricated menu item.
int	getPriority() Retrieves relative priority of this menu item.
Field	getTarget() Gets the target field for the menu.
StringProvider	getTextStringProvider() Gets the text for the menu as a StringProvider.
boolean	isSeparator() Determines if this is a separator.
void	run() Executes menu item.
static MenuItem	separator(int ordinal) Adds a separator at the specified position (ordinal).
void	setCommand(Command command) Sets command to execute when the menu item is activated.
void	setCommandContext(Object commandContext) Sets command context to use when the menu item is activated.
void	setIcon(Image icon) Sets the icon for this menu item.
void	setOrdinal(int ordinal) Dynamically sets the ordinal of this menu item.
void	setPriority(int priority) Dynamically sets the priority of this menu item.
void	setText(String text) Deprecated. Use setText(StringProvider)
void	setText(StringProvider text) Sets the text for this menu item.
String	toString() Retrieves text string associated with this menu item.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CHANGE_OPTION

public static final int CHANGE_OPTION

Change option menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

COPY

public static final int COPY

Copy menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

CUT

public static final int CUT

Cut menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

PASTE

public static final int PASTE

Paste menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

SELECT

public static final int SELECT

Select menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

CANCEL_SELECT

public static final int CANCEL_SELECT

Cancel selection menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

CLOSE

public static final int CLOSE

Close menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

SAVE_CLOSE

public static final int SAVE_CLOSE

Save menu item.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

ORDINAL_COMPARATOR

public static final Comparator ORDINAL_COMPARATOR

Menu item comparator..

Since:

BlackBerry API 3.6.0

Constructor Detail

MenuItem

public MenuItem(ResourceBundle bundle,
                int id,
                int ordinal,
                int priority)

Constructs a new MenuItem instance.

Parameters:

bundle - Resource bundle to support internationalization.

id - ID for this menu item (key value for the menu item's associated string in the resource bundle).

ordinal - Ordering parameter, lower values are placed closer to the top of the menu screen. A separator will be automatically inserted between adjacent items whose ordinals differ by at least 0x00010000.

priority - Priority of the menu item. A lower value indicates a higher priority, conversely a higher value indicates a lower priority.

MenuItem

public MenuItem(String text,
                int ordinal,
                int priority)

Deprecated. Use MenuItem(StringProvider, int, int)

Constructs a new MenuItem instance.

Parameters:

text - The text to appear with the menu item.

ordinal - Ordering parameter, lower values are placed closer to the top of the menu screen. A separator will be automatically inserted between adjacent items whose ordinals differ by at least 0x00010000.

priority - The priority of the menu item. A lower value indicates a higher priority, conversely a higher value indicates a lower priority.

Since:

BlackBerry API 3.6.0

MenuItem

public MenuItem(StringProvider text,
                int ordinal,
                int priority)

Constructs a new MenuItem instance.

Parameters:

text - The text to appear with the menu item.

ordinal - Ordering parameter, lower values are placed closer to the top of the menu screen. A separator will be automatically inserted between adjacent items whose ordinals differ by at least 0x00010000.

priority - The priority of the menu item. A lower value indicates a higher priority, conversely a higher value indicates a lower priority.

Since:

BlackBerry API 6.0.0

Method Detail

createMenuItem

public static MenuItem createMenuItem(Command command)

Creates a MenuItem given a Command. Typically, this would be metadata that is pulled from the command registrar. Will first attempt to create the menu icon from the CommandMetadata provided with the Command, if that fails it will attempt to get the menu icon from the CommandItem. If no image can be retrieved from either, it will leave the menu icon as null.

Parameters:

command - The command to associate with this Menuitem

Returns:

a MenuItem that will execute the command passed in

Throws:

IllegalArgumentException - thrown if Command passed in is null.

Since:

BlackBerry API 7.0.0

getBundle

public ResourceBundle getBundle()

Retrieves resource bundle of this menu item.

Returns:

Resource bundle parameter passed to the constructor when this item was created.

Since:

BlackBerry API 4.0.0

getCommand

public Command getCommand()

Retrieves this menu item's command.

Returns:

Command for menu item.

Since:

BlackBerry API 6.0.0

getCommandContext

public Object getCommandContext()

Retrieves this menu item's command context.

Returns:

Command context for menu item.

Since:

BlackBerry API 6.0.0

getIcon

public Image getIcon()

Retrieves the icon associated with this menu item.

Returns:

Icon The image

Since:

BlackBerry API 5.0.0

getId

public int getId()

Retrieves ID of this menu item.

Returns:

ID parameter passed to the constructor when this item was created.

Since:

BlackBerry API 4.0.0

getOrdinal

public int getOrdinal()

Retrieves relative ordering of this menu item.

Returns:

Ordering parameter passed to the constructor when this item was created.

getPrefab

public static MenuItem getPrefab(int id)

Retrieves a prefabricated menu item.

Items may be cached.

Parameters:

ID - ID for prefabricated menu item.

Returns:

Prefabricated menu item.

Since:

BlackBerry API 4.0.0

getPriority

public int getPriority()

Retrieves relative priority of this menu item.

A lower value indicates a higher priority. A higher value indicates a lower priority.

Returns:

Priority parameter passed to the constructor when this item was created.

getTarget

public Field getTarget()

Gets the target field for the menu.

Returns:

Field object returned by invoking ContextMenu.getTarget().

getTextStringProvider

public StringProvider getTextStringProvider()

Gets the text for the menu as a StringProvider.

Returns:

StringProvider object.

Since:

BlackBerry API 6.0.0

isSeparator

public boolean isSeparator()

Determines if this is a separator.

Returns:

True if this menu item is a separator; otherwise, false.

Since:

BlackBerry API 3.7.0

run

public void run()

Executes menu item. If command has been set then it is executed. If command context has been set then it will be passed to Command instances execute method otherwise this MenuItem is passed.

Specified by:

run in interface Runnable

See Also:

Thread.run()

Since:

BlackBerry API 6.0.0

separator

public static MenuItem separator(int ordinal)

Adds a separator at the specified position (ordinal).

Parameters:

ordinal - Ordinal at which to add the separator.

Returns:

Menu item created.

Since:

BlackBerry API 3.7.0

setCommand

public void setCommand(Command command)

Sets command to execute when the menu item is activated. For more information, see Command Framework API.

Parameters:

command - Command to use for the menu item.

Since:

BlackBerry API 6.0.0

setCommandContext

public void setCommandContext(Object commandContext)

Sets command context to use when the menu item is activated.

Parameters:

commandContext - Command context to use when the Command instance is executed.

See Also:

MenuItem.run()

Since:

BlackBerry API 6.0.0

setIcon

public void setIcon(Image icon)

Sets the icon for this menu item.

The size of the icon that is painted with a menu item is determined during the layout of the menu. You cannot change the width and height of the icon to be displayed. Instead, the icon is scaled to a size that fits within a square that has the same height of the menu font. If the icon is resized, the aspect ratio of the icon is preserved.

The icon is centered vertically with the menu item text. If the scaled icon height is smaller than the default font height, the icon is painted in the vertical center of the paint region. The icon is aligned to the left or right of the menu item text depending on the direction of the text (for example, if the text direction is left-to-right, the icon is aligned to the left of the text).

If you add an icon to a menu item and there is more than one menu item in the menu, the text of all the menu items is aligned along the same vertical line offset to the left or right based on the height of the menu font.

Parameters:

icon - Icon to associate with this menu item

Since:

BlackBerry API 5.0.0

setOrdinal

public void setOrdinal(int ordinal)

Dynamically sets the ordinal of this menu item.

Parameters:

ordinal - the value to set for the ordinal of this menu item.

Since:

BlackBerry API 4.2.0

setPriority

public void setPriority(int priority)

Dynamically sets the priority of this menu item.

Parameters:

priority - the value to set for the priority of this menu item.

Since:

BlackBerry API 4.2.0

setText

public void setText(String text)

Deprecated. Use setText(StringProvider)

Sets the text for this menu item.

This method sets the text string that appears in the menu for this menu item.

Parameters:

String - Text to appear in menu.

setText

public void setText(StringProvider text)

Sets the text for this menu item.

This method sets the text string that appears in the menu for this menu item.

Parameters:

String - Text to appear in menu.

Since:

BlackBerry API 6.0.0

toString

public String toString()

Retrieves text string associated with this menu item.

This method retrieves the text string associated with this menu item. If the menu item object's locale is not the same as the current default locale, this method first sets this menu item's locale to the current default locale, and then returns the appropriate menu string from the resource bundle provided to the menu item at creation time.

Overrides:

toString in class Object

Returns:

Localized string for the menu item.