net.rim.device.api.ui
Class MenuItem

java.lang.Object
  extended by net.rim.device.api.ui.MenuItem
All Implemented Interfaces:
Runnable

public abstract 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 will be 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.

To create menu items in your own application, extend this abstract class. Your subclasses must implement the Runnable interface, which in turn supports abstract dispatching of menu actions on activation. For example

    ...
    // setup the menu items
    MenuItem item = new MyMenuItem();
    menu.addItem(item);
    ...
    class MyMenuItem extends MenuItem {
        MyMenuItem() {
            super(MyResourceBundle.getBundle(), MyResource.MY_MENU_ITEM, 0, 100);
        }
        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)
          Constructs a new MenuItem instance.
MenuItem(ResourceBundle bundle, int id, int ordinal, int priority)
          Constructs a new MenuItem instance.
 
Method Summary
 ResourceBundle getBundle()
          Retrieves resource bundle of this menu item.
 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.
 boolean isSeparator()
          Determines if this is a separator.
static MenuItem separator(int ordinal)
          Adds a separator at the specified position (ordinal).
 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)
          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
 
Methods inherited from interface java.lang.Runnable
run
 



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


Method Detail

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

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

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

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

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

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.





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.