Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`. 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. The label should be positioned on the same horizontal row as the item or directly above the item. The implementation should attempt to distinguish label strings from other textual content, possibly by displaying the label in a different font, aligning it to a different margin, or appending a colon to it if it is placed on the same line as other string content. If the screen is scrolling, the implementation should try to keep the label visible at the same time as 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 place. 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.

### Item Layout

An `Item's` layout within its container is influenced through layout directives:

- `LAYOUT_DEFAULT`
- `LAYOUT_LEFT`
- `LAYOUT_RIGHT`
- `LAYOUT_CENTER`
- `LAYOUT_TOP`
- `LAYOUT_BOTTOM`
- `LAYOUT_VCENTER`
- `LAYOUT_NEWLINE_BEFORE`
- `LAYOUT_NEWLINE_AFTER`
- `LAYOUT_SHRINK`
- `LAYOUT_VSHRINK`
- `LAYOUT_EXPAND`
- `LAYOUT_VEXPAND`
- `LAYOUT_2`

The `LAYOUT_DEFAULT` directive indicates that the container's default layout policy is to be used for this item. `LAYOUT_DEFAULT` has the value zero and has no effect when combined with other layout directives. It is useful within programs in order to document the programmer's intent.

The `LAYOUT_LEFT`, `LAYOUT_RIGHT`, and `LAYOUT_CENTER` directives indicate horizontal alignment and are mutually exclusive. Similarly, the `LAYOUT_TOP`, `LAYOUT_BOTTOM`, and `LAYOUT_VCENTER` directives indicate vertical alignment and are mutually exclusive.

A horizontal alignment directive, a vertical alignment directive, and any combination of other layout directives may be combined using the bit-wise `OR` operator (`|`) to compose a layout directive value. Such a value is used as the parameter to the `setLayout(int)` method and is the return value from the `getLayout()` method.

Some directives have no defined behavior in some contexts. A layout directive is ignored if its behavior is not defined for the particular context within which the `Item` resides.

A complete specification of the layout of `Items` within a `Form` is given here.

### Item Sizes

`Items` have two explicit size concepts: the minimum size and the preferred size. Both the minimum and the preferred sizes refer to the total area of the `Item`, which includes space for the `Item's` contents, the `Item's` label, as well as other space that is significant to the layout policy. These sizes do not include space that is not significant for layout purposes. For example, if the addition of a label to an `Item` would cause other `Items` to move in order to make room, then the space occupied by this label is significant to layout and is counted as part of the `Item's` minimum and preferred sizes. However, if an implementation were to place the label in a margin area reserved exclusively for labels, this would not affect the layout of neighboring `Items`. In this case, the space occupied by the label would not be considered part of the minimum and preferred sizes.

The minimum size is the smallest size at which the `Item` can function and display its contents, though perhaps not optimally. The minimum size may be recomputed whenever the `Item's` contents changes.

The preferred size is generally a size based on the `Item's` contents and is the smallest size at which no information is clipped and text wrapping (if any) is kept to a tolerable minimum. The preferred size may be recomputed whenever the `Item's` contents changes. The application can lock the preferred width or preferred height (or both) by supplying specific values for parameters to the `setPreferredSize` method. The manner in which an `Item` fits its contents within an application-specified preferred size is implementation-specific. However, it is recommended that textual content be word-wrapped to fit the preferred size set by the application. The application can unlock either or both dimensions by supplying the value `-1` for parameters to the `setPreferredSize` method.

When an `Item` is created, both the preferred width and height are unlocked. In this state, the implementation computes the preferred width and height based on the `Item's` contents, possibly including other relevant factors such as the `Item's` graphic design and the screen dimensions. After having locked either the preferred width or height, the application can restore the initial, unlocked state by calling `setPreferredSize(-1, -1)`.

The application can lock one dimension of the preferred size and leave the other unlocked. This causes the system to compute an appropriate value for the unlocked dimension based on arranging the contents to fit the locked dimension. If the contents changes, the size on the unlocked dimension is recomputed to reflect the new contents, but the size on the locked dimension remains unchanged. For example, if the application called `setPreferredSize(50, -1)`, the preferred width would be locked at `50` pixels and the preferred height would be computed based on the `Item's` contents. Similarly, if the application called `setPreferredSize(-1, 60)`, the preferred height would be locked at `60` pixels and the preferred width would be computed based on the `Item's` contents. This feature is particularly useful for `Items` with textual content that can be line wrapped.

The application can also lock both the preferred width and height to specific values. The `Item's` contents are truncated or padded as necessary to honor this request. For `Items` containing text, the text should be wrapped to the specified width, and any truncation should occur at the end of the text.

`Items` also have an implicit maximum size provided by the implementation. The maximum width is typically based on the width of the screen space available to a `Form`. Since `Forms` can scroll vertically, the maximum height should typically not be based on the height of the available screen space.

If the application attempts to lock a preferred size dimension to a value smaller than the minimum or larger than the maximum, the implementation may disregard the requested value and instead use either the minimum or maximum as appropriate. If this occurs, the actual values used must be visible to the application via the values returned from the `getPreferredWidth` and `getPreferredHeight` methods.

### Commands

A `Command` is said to be present on an `Item` if the `Command` has been added to this `Item` with a prior call to `addCommand(javax.microedition.lcdui.Command)` or `setDefaultCommand(javax.microedition.lcdui.Command)` and if the `Command` has not been removed with a subsequent call to `removeCommand(javax.microedition.lcdui.Command)`. `Commands` present on an item should have a command type of `ITEM`. However, it is not an error for a command whose type is other than `ITEM` to be added to an item. For purposes of presentation and placement within its user interface, the implementation is allowed to treat a command's items as if they were of type `ITEM`.

`Items` may have a default `Command`. This state is controlled by the `setDefaultCommand(javax.microedition.lcdui.Command)` method. The default `Command` is eligible to be bound to a special platform-dependent user gesture. The implementation chooses which gesture is the most appropriate to initiate the default command on that particular `Item`. For example, on a device that has a dedicated selection key, pressing this key might invoke the item's default command. Or, on a stylus-based device, tapping on the `Item` might invoke its default command. Even if it can be invoked through a special gesture, the default command should also be invokable in the same fashion as other item commands.

It is possible that on some devices there is no special gesture suitable for invoking the default command on an item. In this case the default command must be accessible to the user in the same fashion as other item commands. The implementation may use the state of a command being the default in deciding where to place the command in its user interface.

It is possible for an `Item` not to have a default command. In this case, the implementation may bind its special user gesture (if any) for another purpose, such as for displaying a menu of commands. The default state of an `Item` is not to have a default command. An `Item` may be set to have no default `Command` by removing it from the `Item` or by passing `null` to the `setDefaultCommand()` method.

The same command may occur on more than one `Item` and also on more than one `Displayable`. If this situation occurs, the user must be provided with distinct gestures to invoke that command on each `Item` or `Displayable` on which it occurs, while those `Items` or `Displayables` are visible on the display. When the user invokes the command, the listener (`CommandListener` or `ItemCommandListener` as appropriate) of just the object on which the command was invoked will be called.

Adding commands to an `Item` may affect its appearance, the way it is laid out, and the traversal behavior. For example, the presence of commands on an `Item` may cause row breaks to occur, or it may cause additional graphical elements (such as a menu icon) to appear. In particular, if a `StringItem` whose appearance mode is `PLAIN` (see below) is given one or more `Commands`, the implementation is allowed to treat it as if it had a different appearance mode.

### Appearance Modes

The `StringItem` and `ImageItem` classes have an appearance mode attribute that can be set in their constructors. This attribute can have one of the values `PLAIN`, `HYPERLINK`, or `BUTTON`. An appearance mode of `PLAIN` is typically used for non-interactive display of textual or graphical material. The appearance mode values do not have any side effects on the interactivity of the item. In order to be interactive, the item must have one or more `Commands` (preferably with a default command assigned), and it must have a `CommandListener` that receives notification of `Command` invocations. The appearance mode values also do not have any effect on the semantics of `Command` invocation on the item. For example, setting the appearance mode of a `StringItem` to be `HYPERLINK` requests that the implementation display the string contents as if they were a hyperlink in a browser. It is the application's responsibility to attach a `Command` and a listener to the `StringItem` that provide behaviors that the user would expect from invoking an operation on a hyperlink, such as loading the referent of the link or adding the link to the user's set of bookmarks.

Setting the appearance mode of an `Item` to be other than `PLAIN` may affect its minimum, preferred, and maximum sizes, as well as the way it is laid out. For example, a `StringItem` with an appearance mode of `BUTTON` should not be wrapped across rows. (However, a `StringItem` with an appearance mode of `HYPERLINK` should be wrapped the same way as if its appearance mode is `PLAIN`.)

A `StringItem` or `ImageItem` in `BUTTON` mode can be used to create a button-based user interface. This can easily lead to applications that are inconvenient to use. For example, in a traversal-based system, users must navigate to a button before they can invoke any commands on it. If buttons are spread across a long `Form`, users may be required to perform a considerable amount of navigation in order to discover all the available commands. Furthermore, invoking a command from a button at the other end of the `Form` can be quite cumbersome. Traversal-based systems often provide a means of invoking commands from anywhere (such as from a menu), without the need to traverse to a particular item. Instead of adding a command to a button and placing that button into a `Form`, it would often be more appropriate and convenient for users if that command were added directly to the `Form`. Buttons should be used only in cases where direct user interaction with the item's string or image contents is essential to the user's understanding of the commands that can be invoked from that item.

### Default State

Unless otherwise specified by a subclass, the default state of newly created `Items` is as follows:

- the `Item` is not contained within ("owned by") any container;
- there are no `Commands` present;
- the default `Command` is `null`;
- the `ItemCommandListener` is `null`;
- the layout directive value is `LAYOUT_DEFAULT`; and
- both the preferred width and preferred height are unlocked.

Since:
  MIDP 1.0

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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

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.

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

  Parameters:
    `label` - the label string
  Throws:
    `IllegalStateException` - if this `Item` is contained within an `Alert`
  See Also:
    `getLabel()`

### getLabel

    public String getLabel()

  Gets the label of this `Item` object.

  Returns:
    the label string
  See Also:
    `setLabel(java.lang.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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.