Programming Wireless Devices with the Java2 Platform

10.1 Item

Class Item is a superclass of all those components that can be attached to a Form. An Item can be contained only in a single Form at a time. The application must remove the item from the Form in which it is currently contained before inserting it into another Form.

All Item objects can have a label field, which is a String representing the title of the Item. If the label String is null, then no label is presented. The label is typically displayed near the Item when the Item is visible on the screen. If the screen is scrolling, the implementation tries to keep the label visible at the same time as the Item.

10.1.1 ItemStateListener

When the user changes an editable Item in a Form, the application can be notified of the change by implementing the ItemStateListener interface and setting the listener on the Form. The itemStateChanged method of the ItemStateListener set on the Form is called automatically when the value of an interactive Gauge, ChoiceGroup, DateField, or TextField changes. The listener is set for the Form using the setItemListener method. It is not expected that the listener is called after every event that causes a change. However, if the value has changed, the listener is called sometime before it is called for another Item, or before a Command is delivered to the ItemStateListener of the Form.

Continuing the example started in Section 9.4, "Form," the ItemStateListener would be set as follows:

form.setItemListener(this);

10.1.2 Item Commands

In MIDP 2.0, context-sensitive Commands can be added to Items. Commands added to an Item are made available to the user only when the focus is on that Item. As with Commands added to Displayables, the device implementation decides how the Commands are presented in the user interface. For example, the Commands might appear as a context-sensitive menu for the Item or as a normal menu when the Item is being manipulated by the user.

Context-sensitive Commands are used much like ordinary Commands in Displayables. The addCommand and removeCommand methods of the Item class control which Commands are associated with Items. There is a dedicated listener type called ItemCommandListener that is notified automatically when the user activates a Command of an Item. The listener of an Item is set with the setItemCommandListener method.

One of the Commands of an Item can also be chosen as the default Command using the method setDefaultCommand. A device may make this Command more easily accessible, for example, using the "Select" key of a device if such a key is available.

For an example on item command use, refer to the sample code in Section 10.2.1, "Appearance Modes."