javax.microedition.lcdui
Class Item

java.lang.Object
  |
  +--javax.microedition.lcdui.Item

Direct Known Subclasses:

ChoiceGroup, CustomItem, DateField, Gauge, ImageItem, Spacer, StringItem, TextField

public abstract class Item

extends Object

A superclass for components that can be added to a Form and Alert. All Item objects have a label field, which is a string that is attached to the item. The label is typically displayed near the component when it is displayed within a screen. This means that the implementation tries to keep the label on the same horizontal row with the item or directly above the item. If the screen is scrolling, the implementation tries to keep the label visible at the same time with the Item.

In some cases, when the user attempts to interact with an Item, the system will switch to a system-generated screen where the actual interaction takes places. If this occurs, the label will generally be carried along and displayed within this new screen in order to provide the user with some context for the operation. For this reason it is recommended that applications supply a label to all interactive Item objects. However, this is not required, and a null value for a label is legal and specifies the absence of a label.

Field Summary

static int	BUTTON An appearance mode value indicating that the Item is to appear as a button.
static int	HYPERLINK An appearance mode value indicating that the Item is to appear as a hyperlink.
static int	LAYOUT_2 A layout directive indicating that new MIDP 2.0 layout rules are in effect for this Item.
static int	LAYOUT_BOTTOM A layout directive indicating that this Item should have a bottom-aligned layout.
static int	LAYOUT_CENTER A layout directive indicating that this Item should have a horizontally centered layout.
static int	LAYOUT_DEFAULT A layout directive indicating that this Item should follow the default layout policy of its container.
static int	LAYOUT_EXPAND A layout directive indicating that this Item's width may be increased to fill available space.
static int	LAYOUT_LEFT A layout directive indicating that this Item should have a left-aligned layout.
static int	LAYOUT_NEWLINE_AFTER A layout directive indicating that this Item should the last on its line or row, and that the next Item (if any) in the container should be placed on a new line or row.
static int	LAYOUT_NEWLINE_BEFORE A layout directive indicating that this Item should be placed at the beginning of a new line or row.
static int	LAYOUT_RIGHT A layout directive indicating that this Item should have a right-aligned layout.
static int	LAYOUT_SHRINK A layout directive indicating that this Item's width may be reduced to its minimum width.
static int	LAYOUT_TOP A layout directive indicating that this Item should have a top-aligned layout.
static int	LAYOUT_VCENTER A layout directive indicating that this Item should have a vertically centered layout.
static int	LAYOUT_VEXPAND A layout directive indicating that this Item's height may be increased to fill available space.
static int	LAYOUT_VSHRINK A layout directive indicating that this Item's height may be reduced to its minimum height.
static int	PLAIN An appearance mode value indicating that the Item is to have a normal appearance.

Method Summary

void	addCommand(Command cmd) Adds a context sensitive Command to the item.
String	getLabel() Gets the label of this Item object.
int	getLayout() Gets the layout directives used for placing the item.
int	getMinimumHeight() Gets the minimum height for this Item.
int	getMinimumWidth() Gets the minimum width for this Item.
int	getPreferredHeight() Gets the preferred height of this Item.
int	getPreferredWidth() Gets the preferred width of this Item.
void	notifyStateChanged() Causes this Item's containing Form to notify the Item's ItemStateListener.
void	removeCommand(Command cmd) Removes the context sensitive command from item.
void	setDefaultCommand(Command cmd) Sets default Command for this Item.
void	setItemCommandListener(ItemCommandListener l) Sets a listener for Commands to this Item, replacing any previous ItemCommandListener.
void	setLabel(String label) Sets the label of the Item.
void	setLayout(int layout) Sets the layout directives for this item.
void	setPreferredSize(int width, int height) Sets the preferred width and height for this Item.

Methods inherited from class java.lang.Object

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

Field Detail

LAYOUT_DEFAULT

public static final int LAYOUT_DEFAULT

A layout directive indicating that this Item should follow the default layout policy of its container.

Value 0 is assigned to LAYOUT_DEFAULT.

Since:

MIDP 2.0

LAYOUT_LEFT

public static final int LAYOUT_LEFT

A layout directive indicating that this Item should have a left-aligned layout.

Value 1 is assigned to LAYOUT_LEFT.

Since:

MIDP 2.0

LAYOUT_RIGHT

public static final int LAYOUT_RIGHT

A layout directive indicating that this Item should have a right-aligned layout.

Value 2 is assigned to LAYOUT_RIGHT.

Since:

MIDP 2.0

LAYOUT_CENTER

public static final int LAYOUT_CENTER

A layout directive indicating that this Item should have a horizontally centered layout.

Value 3 is assigned to LAYOUT_CENTER.

Since:

MIDP 2.0

LAYOUT_TOP

public static final int LAYOUT_TOP

A layout directive indicating that this Item should have a top-aligned layout.

Value 0x10 is assigned to LAYOUT_TOP.

Since:

MIDP 2.0

LAYOUT_BOTTOM

public static final int LAYOUT_BOTTOM

A layout directive indicating that this Item should have a bottom-aligned layout.

Value 0x20 is assigned to LAYOUT_BOTTOM.

Since:

MIDP 2.0

LAYOUT_VCENTER

public static final int LAYOUT_VCENTER

A layout directive indicating that this Item should have a vertically centered layout.

Value 0x30 is assigned to LAYOUT_VCENTER.

Since:

MIDP 2.0

LAYOUT_NEWLINE_BEFORE

public static final int LAYOUT_NEWLINE_BEFORE

A layout directive indicating that this Item should be placed at the beginning of a new line or row.

Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.

Since:

MIDP 2.0

LAYOUT_NEWLINE_AFTER

public static final int LAYOUT_NEWLINE_AFTER

A layout directive indicating that this Item should the last on its line or row, and that the next Item (if any) in the container should be placed on a new line or row.

Value 0x200 is assigned to LAYOUT_NEWLINE_AFTER.

Since:

MIDP 2.0

LAYOUT_SHRINK

public static final int LAYOUT_SHRINK

A layout directive indicating that this Item's width may be reduced to its minimum width.

Value 0x400 is assigned to LAYOUT_SHRINK

Since:

MIDP 2.0

LAYOUT_EXPAND

public static final int LAYOUT_EXPAND

A layout directive indicating that this Item's width may be increased to fill available space.

Value 0x800 is assigned to LAYOUT_EXPAND.

Since:

MIDP 2.0

LAYOUT_VSHRINK

public static final int LAYOUT_VSHRINK

A layout directive indicating that this Item's height may be reduced to its minimum height.

Value 0x1000 is assigned to LAYOUT_VSHRINK.

Since:

MIDP 2.0

LAYOUT_VEXPAND

public static final int LAYOUT_VEXPAND

A layout directive indicating that this Item's height may be increased to fill available space.

Value 0x2000 is assigned to LAYOUT_VEXPAND.

Since:

MIDP 2.0

LAYOUT_2

public static final int LAYOUT_2

A layout directive indicating that new MIDP 2.0 layout rules are in effect for this Item. If this bit is clear, indicates that MIDP 1.0 layout behavior applies to this Item.

Value 0x4000 is assigned to LAYOUT_2.

Since:

MIDP 2.0

PLAIN

public static final int PLAIN

An appearance mode value indicating that the Item is to have a normal appearance.

Value 0 is assigned to PLAIN.

Since:

MIDP 2.0

HYPERLINK

public static final int HYPERLINK

An appearance mode value indicating that the Item is to appear as a hyperlink.

Value 1 is assigned to HYPERLINK.

Since:

MIDP 2.0

BUTTON

public static final int BUTTON

An appearance mode value indicating that the Item is to appear as a button.

Value 2 is assigned to BUTTON.

Since:

MIDP 2.0

Method Detail

setLabel

public void setLabel(String label)

Sets the label of the Item. If label is null, specifies that this item has no label.

Parameters:

label - the label string

Since:

JDE 4.0.2

getLabel

public String getLabel()

Gets the label of this Item object.

Returns:

the label string

getLayout

public int getLayout()

Gets the layout directives used for placing the item.

Returns:

a combination of layout directive values

Since:

MIDP 2.0

See Also:

setLayout(int)

setLayout

public void setLayout(int layout)

Sets the layout directives for this item.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

layout - a combination of layout directive values for this item

Throws:

IllegalArgumentException - if the value of layout is not a bit-wise OR combination of layout directives

IllegalStateException - if this Item is contained within an Alert

Since:

MIDP 2.0

See Also:

getLayout()

addCommand

public void addCommand(Command cmd)

Adds a context sensitive Command to the item. The semantic type of Command should be ITEM. The implementation will present the command only when the item is active, for example, highlighted.

If the added command is already in the item (tested by comparing the object references), the method has no effect. If the item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

cmd - the command to be added

Throws:

IllegalStateException - if this Item is contained within an Alert

NullPointerException - if cmd is null

Since:

MIDP 2.0

removeCommand

public void removeCommand(Command cmd)

Removes the context sensitive command from item. If the command is not in the Item (tested by comparing the object references), the method has no effect. If the Item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so. If the command to be removed happens to be the default command, the command is removed and the default command on this Item is set to null. The following code:

     // Command c is the default command on Item item
     item.removeCommand(c);
 

is equivalent to the following code:

     // Command c is the default command on Item item
     item.setDefaultCommand(null);
     item.removeCommand(c);
 

Parameters:

cmd - the command to be removed

Since:

MIDP 2.0

setItemCommandListener

public void setItemCommandListener(ItemCommandListener l)

Sets a listener for Commands to this Item, replacing any previous ItemCommandListener. A null reference is allowed and has the effect of removing any existing listener.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

l - the new listener, or null.

Throws:

IllegalStateException - if this Item is contained within an Alert

Since:

MIDP 2.0

getPreferredWidth

public int getPreferredWidth()

Gets the preferred width of this Item. If the application has locked the width to a specific value, this method returns that value. Otherwise, the return value is computed based on the Item's contents, possibly with respect to the Item's preferred height if it is locked. See Item Sizes for a complete discussion.

Returns:

the preferred width of the Item

Since:

MIDP 2.0

See Also:

getPreferredHeight(), setPreferredSize(int, int)

getPreferredHeight

public int getPreferredHeight()

Gets the preferred height of this Item. If the application has locked the height to a specific value, this method returns that value. Otherwise, the return value is computed based on the Item's contents, possibly with respect to the Item's preferred width if it is locked. See Item Sizes for a complete discussion.

Returns:

the preferred height of the Item

Since:

MIDP 2.0

See Also:

getPreferredWidth(), setPreferredSize(int, int)

setPreferredSize

public void setPreferredSize(int width,
                             int height)

Sets the preferred width and height for this Item. Values for width and height less than -1 are illegal. If the width is between zero and the minimum width, inclusive, the minimum width is used instead. If the height is between zero and the minimum height, inclusive, the minimum height is used instead.

Supplying a width or height value greater than the minimum width or height locks that dimension to the supplied value. The implementation may silently enforce a maximum dimension for an Item based on factors such as the screen size. Supplying a value of -1 for the width or height unlocks that dimension. See Item Sizes for a complete discussion.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

width - the value to which the width should be locked, or -1 to unlock

height - the value to which the height should be locked, or -1 to unlock

Throws:

IllegalArgumentException - if width or height is less than -1

IllegalStateException - if this Item is contained within an Alert

Since:

MIDP 2.0

See Also:

getPreferredHeight(), getPreferredWidth()

getMinimumWidth

public int getMinimumWidth()

Gets the minimum width for this Item. This is a width at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Returns:

the minimum width of the item

Since:

MIDP 2.0

getMinimumHeight

public int getMinimumHeight()

Gets the minimum height for this Item. This is a height at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Returns:

the minimum height of the item

Since:

MIDP 2.0

setDefaultCommand

public void setDefaultCommand(Command cmd)

Sets default Command for this Item. If the Item previously had a default Command, that Command is no longer the default, but it remains present on the Item.

If not null, the Command object passed becomes the default Command for this Item. If the Command object passed is not currently present on this Item, it is added as if addCommand(javax.microedition.lcdui.Command) had been called before it is made the default Command.

If null is passed, the Item is set to have no default Command. The previous default Command, if any, remains present on the Item.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

cmd - the command to be used as this Item's default Command, or null if there is to be no default command

Throws:

IllegalStateException - if this Item is contained within an Alert

Since:

MIDP 2.0

notifyStateChanged

public void notifyStateChanged()

Causes this Item's containing Form to notify the Item's ItemStateListener. The application calls this method to inform the listener on the Item that the Item's state has been changed in response to an action. Even though this method simply causes a call to another part of the application, this mechanism is useful for decoupling the implementation of an Item (in particular, the implementation of a CustomItem, though this also applies to subclasses of other items) from the consumer of the item.

If an edit was performed by invoking a separate screen, and the editor now wishes to "return" to the form which contained the selected Item, the preferred method is Display.setCurrent(Item) instead of Display.setCurrent(Displayable), because it allows the Form to restore focus to the Item that initially invoked the editor.

In order to make sure that the documented behavior of ItemStateListener is maintained, it is up to the caller (application) to guarantee that this function is not called unless:

• the Item's value has actually been changed, and
• the change was the result of a user action (an "edit") and NOT as a result of state change via calls to Item's APIs

The call to ItemStateListener.itemStateChanged may be delayed in order to be serialized with the event stream. The notifyStateChanged method does not block awaiting the completion of the itemStateChanged method.

Throws:

IllegalStateException - if the Item is not owned by a Form

Since:

MIDP 2.0