com.nokia.mid.ui
Class IconCommand

java.lang.Object
  javax.microedition.lcdui.Command
      com.nokia.mid.ui.IconCommand

public class IconCommand
extends javax.microedition.lcdui.Command

The Nokia IconCommand class encapsulates the semantic information of an action and is an extension to the javax.microedition.lcdui.Command class. Note that the behaviour generated by selecting the IconCommand is the responsibility of a javax.microedition.lcdui.CommandListener. For further details regarding the definition and use of Command and CommandListener, see the standard MIDP2 Javadoc.

IconCommand differs from Command only in terms of its visual appearance. Whereas a Command is represented using a text label only, IconCommand has both a label and an icon. The icon's image data may come from one of two sources: either from a built-in system icon described using a unique id, or from image data provided by the MIDlet.

On some platforms, an IconCommand's icon may have a different appearance when selected than when unselected. For this reason, when a MIDlet provides its own icon image data, it can supply both selected and unselected versions, although only the unselected version of the icon image is mandatory.

Field Summary

static int	ICON_ADD_CONTACT A unique id representing the system icon "add contact".
static int	ICON_BACK A unique id representing the system icon "back".
static int	ICON_OK A unique id representing the system icon "OK".
static int	ICON_OPTIONS A unique id representing the system icon "options".
static int	ICON_SEND_SMS A unique id representing the system icon "send sms".

Fields inherited from class javax.microedition.lcdui.Command

BACK, CANCEL, EXIT, HELP, ITEM, OK, SCREEN, STOP

Constructor Summary

IconCommand(java.lang.String label, javax.microedition.lcdui.Image unselectedIcon, javax.microedition.lcdui.Image selectedIcon, int commandType, int priority)
Creates a new IconCommand with the given label, unselected icon, selected icon, type and priority.

IconCommand(java.lang.String label, int commandType, int priority, int iconId)
Creates a new IconCommand with the given label, type, priority and system icon id.

IconCommand(java.lang.String shortLabel, java.lang.String longLabel, javax.microedition.lcdui.Image unselectedIcon, javax.microedition.lcdui.Image selectedIcon, int commandType, int priority)
Creates a new IconCommand with the given short label, long label, unselected icon, selected icon, type and priority.

IconCommand(java.lang.String shortLabel, java.lang.String longLabel, int commandType, int priority, int iconId)
Creates a new IconCommand with the given short label, long label, type, priority and system icon id.

Method Summary

int	getIconId() Gets the IconCommand's system icon id.
javax.microedition.lcdui.Image	getSelectedIcon() Gets the selected version of the IconCommand's MIDlet-defined icon.
javax.microedition.lcdui.Image	getUnselectedIcon() Gets the unselected version of the IconCommand's MIDlet-defined icon.

Methods inherited from class javax.microedition.lcdui.Command

getCommandType, getLabel, getLongLabel, getPriority

Methods inherited from class java.lang.Object

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

Field Detail

ICON_ADD_CONTACT

public static final int ICON_ADD_CONTACT

A unique id representing the system icon "add contact".

This value is designed for use with IconCommands that add a personal contact to a database.

Value 0 is assigned to ICON_ADD_CONTACT.

See Also:

Constant Field Values

ICON_BACK

public static final int ICON_BACK

A unique id representing the system icon "back".

This value is designed for use with IconCommands that return the user to the previous screen in the UI.

Value 1 is assigned to ICON_BACK.

See Also:

Constant Field Values

ICON_OPTIONS

public static final int ICON_OPTIONS

A unique id representing the system icon "options".

This value is designed for use with IconCommands that provide access to a list of options.

Value 2 is assigned to ICON_OPTIONS.

See Also:

Constant Field Values

ICON_SEND_SMS

public static final int ICON_SEND_SMS

A unique id representing the system icon "send sms".

This value is designed for use with IconCommands that send a text message.

Value 3 is assigned to ICON_SEND_SMS.

See Also:

Constant Field Values

ICON_OK

public static final int ICON_OK

A unique id representing the system icon "OK".

This value is designed for use with IconCommands that confirm an action.

Value 4 is assigned to ICON_OK.

See Also:

Constant Field Values

Constructor Detail

IconCommand

public IconCommand(java.lang.String shortLabel,
                   java.lang.String longLabel,
                   int commandType,
                   int priority,
                   int iconId)

Creates a new IconCommand with the given short label, long label, type, priority and system icon id.

Parameters:

shortLabel - a shortened version of the IconCommand's text label.

longLabel - a full-length version of the IconCommand's text label.

commandType - the IconCommand's type, which may be any legal javax.microedition.lcdui.Command type.

priority - the IconCommand's priority.

iconId - the id of the system icon to be used to represent the IconCommand.

Throws:

java.lang.NullPointerException - if shortLabel is null.

java.lang.IllegalArgumentException - if commandType is invalid.

java.lang.IllegalArgumentException - if iconId is invalid.

java.lang.IllegalArgumentException - if iconId and commandType If iconId is ICON_BACK and commandType is anything not BACK or EXIT, throw exception.

IconCommand

public IconCommand(java.lang.String label,
                   int commandType,
                   int priority,
                   int iconId)

Creates a new IconCommand with the given label, type, priority and system icon id.

Calling this constructor is equivalent to calling IconCommand(shortLabel, null, commandType, priority, iconId). The IconCommand created by this constructor will therefore have no long label.

Parameters:

label - a shortened version of the IconCommand's text label.

commandType - the IconCommand's type, which may be any legal javax.microedition.lcdui.Command type.

priority - the IconCommand's priority.

iconId - the id of the system icon to be used to represent the IconCommand.

Throws:

java.lang.NullPointerException - if label is null.

java.lang.IllegalArgumentException - if commandType is invalid.

java.lang.IllegalArgumentException - if iconId is invalid.

java.lang.IllegalArgumentException - if iconId and commandType is not match.

IconCommand

public IconCommand(java.lang.String shortLabel,
                   java.lang.String longLabel,
                   javax.microedition.lcdui.Image unselectedIcon,
                   javax.microedition.lcdui.Image selectedIcon,
                   int commandType,
                   int priority)

Creates a new IconCommand with the given short label, long label, unselected icon, selected icon, type and priority.

Parameters:

shortLabel - a shortened version of the IconCommand's text label.

longLabel - a full-length version of the IconCommand's text label.

unselectedIcon - an Image providing the visual representation of the element when unselected.

selectedIcon - an Image providing the visual representation of the element when selected. This parameter may be null if no selected version is required.

commandType - the IconCommand's type, which may be any legal javax.microedition.lcdui.Command type.

priority - the IconCommand's priority.

Throws:

java.lang.NullPointerException - if shortLabel is null.

java.lang.NullPointerException - if unselectedIcon is null.

java.lang.IllegalArgumentException - if commandType is invalid.

IconCommand

public IconCommand(java.lang.String label,
                   javax.microedition.lcdui.Image unselectedIcon,
                   javax.microedition.lcdui.Image selectedIcon,
                   int commandType,
                   int priority)

Creates a new IconCommand with the given label, unselected icon, selected icon, type and priority.

Calling this constructor is equivalent to calling IconCommand(shortLabel, null, unselectedImage, selectedImage, commandType, priority) . The IconCommand created by this constructor will therefore have no long label.

Parameters:

label - a shortened version of the IconCommand's text label.

unselectedIcon - an Image providing the visual representation of the element when unselected.

selectedIcon - an Image providing the visual representation of the element when selected. This parameter may be null if no selected version is required.

commandType - the IconCommand's type, which may be any legal javax.microedition.lcdui.Command type.

priority - the IconCommand's priority.

Throws:

java.lang.NullPointerException - if label is null.

java.lang.NullPointerException - if unselectedIcon is null.

java.lang.IllegalArgumentException - if commandType is invalid.

Method Detail

getIconId

public int getIconId()

Gets the IconCommand's system icon id.

Returns:

the IconCommand's system icon id, or CUSTOM_ICONS if the icons are application provided images.

getUnselectedIcon

public javax.microedition.lcdui.Image getUnselectedIcon()

Gets the unselected version of the IconCommand's MIDlet-defined icon.

Returns:

the unselected version of the MIDlet-defined icon, or null if no MIDlet-defined icon exists.

getSelectedIcon

public javax.microedition.lcdui.Image getSelectedIcon()

Gets the selected version of the IconCommand's MIDlet-defined icon.

Returns:

the selected version of the MIDlet-defined icon, or null if no selected version exists.