There are three types of lists:

IMPLICIT lists can be used to construct menus by treating each element like a logical command. In this case, no application-defined commands have to be created. The application just has to register a CommandListener that is called when a user selects an item.

For example, you might create an explicit list with three operations: Start Game, Quit Game, and Instructions. Start Game is considered the default operation.

Because the list is of type IMPLICIT, when a player selects a given command, the commandAction() method is called, and the SELECT_COMMAND parameter is passed in.

The javax.microedition.lcdui.Choice interface defines an API for a user interface component implementing a selection from a predefined number of choices. The UI components that implement Choice are List and ChoiceGroup.

Each element of a Choice is composed of a text string and an optional image. If the application provides an image, the implementation can choose to ignore the image if it exceeds the capacity of the device to display it. If the implementation displays the image, it will be displayed adjacent to the text string as a sort of icon, and the pair will be treated as a unit.

After a Choice object has been created, elements may be inserted, appended, and deleted, and each element's string part and image part can be obtained and set. Elements within a Choice object are referred to by their indexes, which are consecutive integers starting from zero.

There are three types of choices: IMPLICIT-CHOICE (valid only for lists), EXCLUSIVE-CHOICE, and MULTIPLE-CHOICE.

When a Choice is present on the display, the user can interact with it indefinitely. These traversing and scrolling operations do not cause application-visible events. The system notifies the application only when some application-defined command is fired, or when the selection state of a ChoiceGroup is changed. When a command is fired, a high-level event is delivered to the listener of the Screen.

The following important methods can be found in the javax.microedition.lcdui.Choice interface:

Lists can be used as menus and track/level selectors. Listing 13.1 shows an example menu. A car racing game can use this menu to select a type of track.

import javax.microedition.lcdui.*;
import javax.microedition.midlet.*;

public class Tracks extends List
    implements CommandListener
{
  private MIDlet midlet;
  private GameCanvas nextForm;
  private Form previousForm;

  private Command backCommand = new
      Command("Back", Command.SCREEN, 1);

  private static String trackNames[] =
      {"City", "Forest", "Mountain"};

  private static int lengths[] =
      {1000, 1400, 800};

  public Tracks(MIDlet midlet, GameCanvas nextForm,
      Form previousForm)
  {
    super("Tracks:", List.IMPLICIT, trackNames, null);
    this.midlet = midlet;
    this.nextForm = nextForm;
    this.previousForm = previousForm;
    addCommand(backCommand);
    setCommandListener(this);
  }

  public void commandAction(Command c, Displayable s)
  {
    if (c.equals(List.SELECT_COMMAND))
    {
      int trackID = getSelectedIndex();
      nextForm.setLength(lengths[trackID]);
      nextForm.setSpeed(Float.createFloat(2, 400));
      nextForm.initEnemies();
      Display.getDisplay(midlet).setCurrent(nextForm);
      nextForm.start();
    }
    else if (c == backCommand)
    {
      Display.getDisplay(midlet).setCurrent(previousForm);
    }
  }
}

The application memorizes the previous and next form so that forward and backward navigation is available. All list options are passed as an array of strings. When the Select key is pressed, it invokes a special SELECT_COMMAND event. In the command listener, when the event is caught, the track's id is read from the list and the game is started (usually by starting a thread). The track is shown in Figure 13.2.

Figure 13.2. The race track selection list.

Sometimes it is useful to know if a user is selecting one of your items. You can have a form listen to a item by using the following static method:

Form.setItemStateListener(ItemStateListener)

When a user does something interesting with a user interface component, the listener's itemStateChanged(Item item) method will be triggered. Such changes include

The listener is not called if the application (as opposed to the user) changes the value of an interactive item.

A javax.microedition.lcdui.ChoiceGroup is a group of selectable elements intended to be placed within a Form. The group may be created with a mode that requires a single choice to be made, or one that allows multiple choices.

Each device implementation is responsible for providing the graphical representation of these modes, and must provide visually different graphics for different modes. For example, some devices might use radio buttons for the single choice mode and check boxes for the multiple-choice mode. Choices implement the javax.microedition.lcdui.Choice interface and therefore have the same methods as lists.

A javax.microedition.lcdui.DateField is an editable component for presenting date and time information that can be placed into a Form.

You can create an instance to accept a given date, a given time, or both. This input mode configuration is accomplished by calling the DATE, TIME, or DATE_TIME static fields of this class. Figure 13.3, for example, shows a typical date and time selection screen.

Figure 13.3. Displaying date and time.

Methods for manipulating the date and time include the following:

Often times, it's a good idea to show a load bar to a user as a bunch of graphics or classes are loaded from the network or from storage memory. The javax.microedition.lcdui.Gauge class implements a bar graph display of a value intended for use in the form of a progress meter. Figure 13.4 shows a typical gauge.

Figure 13.4. An interactive and non-interactive gauge.

The values accepted by the Gauge object are small integers in the range zero through a maximum value established by the application. The application is expected to normalize its values into this range. The device is also expected to normalize this range into a smaller set of values for display purposes. Doing so will not change the actual value contained within the object. The range of values specified by the application may be larger than the number of distinct visual states possible on the device, so more than one value may have the same visual representation.

Applications can set or retrieve the Gauge's value at any time, regardless of the interaction mode. The user is prohibited from moving the value outside the established range. The expected behavior is that the application sets the initial value, then allows the user to modify the value thereafter. However, the application is not prohibited from modifying the value even while the user is interacting with it.

The Gauge class has the following important methods:

An example of a progress meter in use can be seen in Listing 13.2.

import javax.microedition.lcdui.*;
import javax.microedition.midlet.*;

public class ProgressForm extends Form
implements CommandListener, Runnable
{
  private final int MAX = 10;

  private MIDlet midlet;
  private Form nextForm;
  private Gauge gauge;
  private StringItem label;
  private Command nextCommand = new
      Command("Next", Command.SCREEN, 1);

  public ProgressForm(MIDlet midlet, Form nextForm)
  {
    super("Loader");
    this.midlet = midlet;
    this.nextForm = nextForm;
    addCommand(nextCommand);
    setCommandListener(this);

    gauge = new Gauge("", false, MAX, 0);
    append(gauge);
  }

  public void commandAction(Command c, Displayable s)
  {
    if (c.equals(nextCommand))
    {
      Thread thread = new Thread(this);
      thread.start();
    }
  }

  public void run()
  {
    for (int i = 0; i < MAX; i++)
    {
      // Do something
      gauge.setValue(i + 1);
    }
    Display.getDisplay(midlet).setCurrent(nextForm);
  }
}

Progress meters are often used during the execution of segmented actions that are quite slow (for example, loading images and levels over the network). Users want some kind of feedback that showing that the device is not frozen. The value MAX should have the number of items to be done (such as number of images). When pressing the Next soft key, a new thread is invoked.

The javax.microedition.lcdui.StringItem class is a simple item that can contain a string. This is used to create a display-only text label. Both the label and the textual content of a StringItem can be modified by the application. The visual representation of the label may differ from that of the textual contents.

To manipulate a StringItem, use the following methods:

Similar to StringItem, the javax.microedition.lcdui.ImageItem class provides layout control when Image objects are added to a Form. Each ImageItem object contains a reference to an Image object. This image must be immutable. The value null may be specified for the image contents of an ImageItem. If this occurs (and if the label is also null), the ImageItem will occupy no space on the screen.

Each ImageItem object contains a layout field that is combined from the following values:

Because of device constraints such as limited screen size, the implementation might choose to ignore layout directions.

There are some implicit rules on how the layout directives can be combined:

Important methods within ImageItem are the following:

The javax.microedition.lcdui.TextField class is an editable text component that may be placed into a Form, as seen in Figure 13.5).

Figure 13.5. A typical text password field.

You can give a text field an initial value. It also has a maximum size, which is the maximum number of characters that can be stored in the object at any time. This limit is enforced when the TextField instance is constructed, when the user is editing text within the TextField, as well as when the application program calls methods on the TextField that modify its contents. The maximum size is the maximum stored capacity and is unrelated to the number of characters that may be displayed at any given time. The number of characters displayed and their arrangement into rows and columns are determined by the device.

The TextField shares the concept of input constraints with the TextBox object. The different constraints allow the application to request that the user's input be restricted in a variety of ways. The implementation is required to restrict the user's input as requested by the application. The following constants can be used to restrict the character set:

The implementation may provide special formatting for the value entered. For example, a PHONENUMBER field may be separated and punctuated as appropriate for the phone number conventions in use, grouping the digits into country code, area code, prefix, and so on. Note that in some networks a + prefix is part of the number, and is returned as a part of the string.