From Forum Nokia Wiki

Contents 1 Introduction 2 DateField 3 Gauge 4 StringItem 5 TextField 6 ChoiceGroup 7 Image and ImageItem 8 Conclusion

Introduction

In our fifth part of the MIDP's User Interface Hierarchy series, we discussed about the Form MIDP's UI component (MIDP's User Interface Hierarchy: Form). This sixth part I'll introduce the set of Items components provided by the MIDP, such as Gauge, TextField and ImageItem, which they can be composed in a Form-based screen. As discussed in MIDP's User Interface Hierarchy: Form, the following figure depicts the main relationship among the MIDP's UI components, focusing in the Item's components.

DateField

The DateField component (javax.microedition.lcdui.DateField) allows applications to manipulate a Date object (as defined in java.util.Date) using the keys and/or soft buttons on a mobile device. The following figure illustrates a DateField in action (only date, time and date and only time):

You can create three kinds of DateFields, which specifies whether a user can edit the date, the time, or both. The following table describes each of them:

DateField.DATE: Allows the user to edit just the date
DateField.TIME: Allows the user to edit just the time
DateField.DATE_TIME: Allows the user to edit both the date and the time

The DateField API provides a set of constructors and methods in order to manipulate dates. In addition to the methods inherited from Item class, the following table ilustrates other important actions that can be made in a DateField component:

To create a new DateField component, you can use one of the two constructors described in the table:

//Creates a new DateField with DATE as mode
DateField field = new DateField("Birthday", DateField.DATE);
//Creates a new DateField with DATE and TIME as mode
field = new DateField("Birthday", DateField.DATE_TIME);
//Creates a new DateField with TIME as mode
field = new DateField("Birthday", DateField.TIME);

Gauge

Gauge (javax.microedition.lcdui.Gauge) components allows you to add progress meters to Form screens. Percentage indicators that is displayed when downloading a file or during the installation of a software are well-known examples of progress meters.

The Gauge component can be built in two modes: interactive, where the user makes the changes in the progress; the second is called non-interactive mode, where its up to the application developer to change the values.

The Gauge API provides the constructors and methods described in the following table:

The following example shows an interactive Gauge where the user can adjust a volume/sound of a music/video.

NOTE: As with all high-level interface components, the implementation decides how the Gauge will look on the screen.

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.CommandListener;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.Gauge;
import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;
 
 
public class GaugeInteractive extends MIDlet implements CommandListener {
 
    private Display display;
    private Form form;
    private Gauge gauge;
    private Command cmdInc;
    private Command cmdDec;
 
    public GaugeInteractive() {
        display = Display.getDisplay(this);
        //creates a new Gauge as interactive mode: true parameter
        gauge   = new Gauge("Download progress", true, 10, 3);
        cmdInc = new Command("Inc", Command.OK, 1);
        cmdDec = new Command("Dec", Command.OK, 1);
        form    = new Form("Items");
        //appends gauge to the form screen
        form.append(gauge);
        form.addCommand(cmdInc);
        form.addCommand(cmdDec);
        form.setCommandListener(this);
    }
 
    protected void destroyApp(boolean arg0) throws MIDletStateChangeException {}
    protected void pauseApp() {}
 
    protected void startApp() throws MIDletStateChangeException {
        display.setCurrent(form);
    }
 
    public void commandAction(Command arg0, Displayable arg1) {
        if(arg0 == cmdInc) {
            //checks if the gauge's current value is lower than the gauge's max value
            if(gauge.getValue() < gauge.getMaxValue())
                //adds 1 to gauge's value
                gauge.setValue(gauge.getValue() + 1);                
        } else {
            //checks if gauge's current value is higher than one
            if(gauge.getValue() > 0)
                gauge.setValue(gauge.getValue() - 1);
        }
 
    }
 
}

The result is:

The next example shows a non-interactive Gauge based on the Timer class in order to update the gauge's value. With the Timer class, we can provide our MIDlet with periodic "interruptions", where we increment the Gauge. When using non-interactive mode, it is not needed to set the max and initial values. Otherwise, you can use the following value types:

• Gauge.INDEFINITE: It is used for the maximum value in order to indicate that the Gauge has indefinite range.You can use Gauge.INDEFINITE as the maxValue parameter to the constructor, or the parameter passed to setMaxValue(), and as the return value of getMaxValue().
• Gauge.CONTINUOUS_IDLE: The value representing the continuous-idle state of a non-interactive Gauge with indefinite range. In the continuous-idle state, the gauge shows a graphic indicating that no work is in progress.
• Gauge.INCREMENTAL_IDLE: The value representing the incremental-idle state of a non-interactive Gauge with indefinite range. In the incremental-idle state, the gauge shows a graphic indicating that no work is in progress.
• Gauge.CONTINUOUS_RUNNING: The value representing the continuous-running state of a non-interactive Gauge with indefinite range. In the continuous-running state, the gauge shows a continually-updating animation sequence that indicates that work is in progress.

public class NonInteractiveGauge extends MIDlet implements CommandListener {
 
    private Display display;
    private Form form;
    private Gauge gauge;
    private Command cmdStop;
    private Command cmdExit;
    private Timer timer;
    private TimerDownload timerDownload;
 
    public NonInteractiveGauge() {
        display = Display.getDisplay(this);
        //creates a new Gauge as non-interactive: false parameter:
        //Gauge.INDEFINITE specifies that the gauge has no max value
        gauge   = new Gauge("Download progress", false, Gauge.INDEFINITE,  Gauge.INCREMENTAL_IDLE);
        cmdStop = new Command("Stop", Command.CANCEL, 1);
        cmdExit = new Command("Exit", Command.EXIT, 1);
        form    = new Form("Items");
        //appends gauge to the form screen
        form.append(gauge);
        form.addCommand(cmdStop);
        form.setCommandListener(this);
    }
 
    protected void destroyApp(boolean arg0) throws MIDletStateChangeException {}
    protected void pauseApp() {}
 
    protected void startApp() throws MIDletStateChangeException {
        display.setCurrent(form);
        //creates a new timer instance
        timer = new Timer();
        //creates a new TimerDownload instance. Thread that will increment our Gauge's value
        timerDownload = new TimerDownload();
        //sets the time interval to be fired
        timer.scheduleAtFixedRate(timerDownload, 0, 1000);
    }
 
    public void commandAction(Command arg0, Displayable arg1) {
        if(arg0 == cmdExit)
            notifyDestroyed();
        else if(arg0 == cmdStop) {
            timer.cancel();
            form.removeCommand(cmdStop);
            form.addCommand(cmdExit);
            gauge.setLabel("Download canceled!");
        }
 
    }
 
    /*
     * Handle the timer task
     * It is executed at a given time interval
     */
    private class TimerDownload extends TimerTask {
 
        public void run() {
            gauge.setValue(Gauge.INCREMENTAL_UPDATING);
        }
 
    }
 
}

The result would be:

StringItem

A StringItem (javax.microedition.lcdui.StringItem) component aims to display a static label and text message. The StringItem does not allow the user to edit the label or the text. The following table ilustrates the main constructor and methods provided by the StringItem class.

Note that the StringItem class provides the necessary methods to change the text message. However, if you would like to change the label's name, you should use the methods inherited from Item class (setLabel() and getLabel()).

public class StringItemExample extends MIDlet implements CommandListener {
 
    private Display display;
    private Form form;
    private Command cmdChange;
    private Command cmdExit;
    private StringItem stringItem;
 
    public StringItemExample() {
        display = Display.getDisplay(this);
        form    = new Form("StringItem Example");
        //creates a new string item
        stringItem = new StringItem("Name:", "Thiago Sales");
        cmdChange = new Command("Change", Command.OK, 1);
        cmdExit = new Command("Exit", Command.EXIT, 1);
        //appends the StringItem object to a form screen
        form.append(stringItem);
        form.addCommand(cmdChange);
        form.addCommand(cmdExit);
        form.setCommandListener(this);
    }
 
    protected void destroyApp(boolean arg0) throws MIDletStateChangeException {}
    protected void pauseApp() {}
 
    protected void startApp() throws MIDletStateChangeException {
        display.setCurrent(form);
    }
 
    public void commandAction(Command arg0, Displayable arg1) {
        if(arg0 == cmdChange) {
            //changes the StringItem's label: method inherited from Item class
            stringItem.setLabel("Nickname");
            //changes the StringItem's text: method available by the StringItem class
            stringItem.setText("Thiagobrunoms");
            form.removeCommand(cmdChange);
        } else
            notifyDestroyed();
    }
 
}

The following images depicts when the StringItem was created and after we press "Change", respectively.

There is one more option to set a message to a form, by appending a String object directly. If you choose this option, you do not have an associated label to your text. In order to use a String object instead of a StringItem, you can use the append(String str) overwritten method available by the Form class.

form.append("Name: Thiago Sales");

TextField

If you are familiar with HTML form screens, you can use the TextField ( ) component in order to provide text inputs with JavaME. When you create a TextField component, you can specify an input constraint. A constraint provides restrictions on the data that the user will enter. For instance, if you have a TextField that prompts for email address, you can set a constraint that checks if all email characters are allowed in an email address. Below you can check the main constraints available by the MIDP.

• TextField.ANY: Allow any character input
• TextField.EMAILADDR: Allow only characters that are valid within an email address
• TextField.NUMBER: Allow only numbers (Positive and negative).
• TextField.PASSWORD: Masks all characters input to provide privacy when entering data.
• TextField.PHONENUMBER: Allow only characters that are valid as part of a phone number.
• TextField.URL: Only characters that are valid within a URL.

The following table describes the main constructor and methods provided by the TextField component.

The following code example shows how to create TextField and sets different types of constraints.

public class TextFieldExample extends MIDlet {
 
    private Display d;
    private Form f;
    private TextField textAny;
    private TextField textEmail;
    private TextField textNumber;
    private TextField textPassword;
    private TextField textPhoneNumber;
    private TextField textURL;
 
    public TextFieldExample() {
        this.d         = Display.getDisplay(this);
        this.f         = new Form("TextField Example");
 
        //Creates a new TextField allowing any characters
        this.textAny = new TextField("Name: ", "", 5, TextField.ANY);
        //Creates a new TextField allowing only characters that are valid within an email address
        this.textEmail = new TextField("Email: ", "", 10, TextField.EMAILADDR);
        //Creates a new TextField allowing only numbers
        this.textNumber = new TextField("Age: ", "", 3, TextField.NUMERIC);
        //Creates a new TextField that masks all characters
        this.textPassword = new TextField("Password: ", "", 8, TextField.PASSWORD);
        //Creates a new TextField allowing only characters valid within phone numbers
        this.textPhoneNumber = new TextField("Phone: ", "", 7, TextField.PHONENUMBER);
        //Creates a new TextField allowing only characters that are valid within a URL address
        this.textURL = new TextField("URL: ", "", 8, TextField.URL);
 
        //Appends all TextField objects to the Form screen
        this.f.append(this.textAny);
        this.f.append(this.textEmail);
        this.f.append(this.textNumber);
        this.f.append(this.textPassword);
        this.f.append(this.textPhoneNumber);
        this.f.append(this.textURL);
 
    }
 
    protected void destroyApp(boolean arg0) throws MIDletStateChangeException { }
    protected void pauseApp() {}
 
    protected void startApp() throws MIDletStateChangeException {
        this.d.setCurrent(this.f);
    }
 
}

The result would be:

ChoiceGroup

The ChoiceGroup (javax.microedition.lcdui.ChoiceGroup) component allows a user to manipulating various types of predefined selections. The ChoiceGroup provides two types of selections: multiple (Choice.MULTIPLE) and exclusive (Choice.EXCLUSIVE). Imagine checkbox and radio buttons, respectively. The former allows the user to select only one option at any time. On the other hand, the second option allows zero or more selections at any time. The following table describes the main constructor and methods provided by the ChoiceGroup class.

The following examples show an exclusive and a multiple choice types. Note that, as an Item component, you can append as many ChoiceGroup's as possible in a Form-based screen.

public class ChoiceGroupExample extends MIDlet {
 
    private Display d;
    private Form f;
    private ChoiceGroup choiceMultiple;
    private ChoiceGroup choiceExclusive;
 
    public ChoiceGroupExample() {
        d         = Display.getDisplay(this);
        f         = new Form("ChoiceGroup Example");
        //Creates a new ChoiceGroup as MULTIPLE
        choiceMultiple = new ChoiceGroup("Choice Multiple", Choice.MULTIPLE);
        //Creates a new ChoiceGroup as EXCLUSIVE
        choiceExclusive = new ChoiceGroup("Choice Exclusive", Choice.EXCLUSIVE);
 
        //Appends elements to the MULTIPLE ChoiceGroup
        choiceMultiple.append("Thiago", null);
        choiceMultiple.append("Sales", null);
 
        //Appends elements to the EXCLUSIVE ChoiceGroup
        choiceExclusive.append("22", null);
        choiceExclusive.append("23", null);
 
        //Appends ChoiceGroup's to the Form screen
        f.append(this.choiceMultiple);
        f.append(this.choiceExclusive);
    }
 
    protected void destroyApp(boolean arg0) throws MIDletStateChangeException {}
    protected void pauseApp() {}
 
    protected void startApp() throws MIDletStateChangeException {
        this.d.setCurrent(this.f);
    }
 
}

The following figures depicts the result of the previous code example:

Image and ImageItem

The ImageItem component (javax.microedition.lcdui.ImageItem) helps you to specify the position of images in a Form screen. For instance, centered horizontally, to the left or to the right. However, It is still up to the device implementation to decide where the image will actually appear.

Before going deeper into the ImageItem class, I also have to show you the Image (javax.microedition.lcdui.Image) class. As image in a mobile device can be divided into two types:

• Immutable: once you create this type of image, you cannot change it. Usually, you will create an immutable image through a resource, such as files, or byte array.
• Mutable: provides more flexibility. It can be created through the paint method provided by the Canvas class.

The following table shows the main methods provided by the Image class. Note that Image has no constructors.

If you wish to specify the position (left, right, center, etc) of the images, you can use the ImageItem component. Below we can see the various layouts available.

• LAYOUT_DEFAULT: Use the default layout of the device implementation.
• LAYOUT_LEFT: The image will appear on the left.
• LAYOUT_RIGHT: The image should appear on the right.
• LAYOUT_CENTER: Center the image horizontally.
• LAYOUT_NEWLINE_BEFORE: Insert a newline before the image is drawn. This assures that previous text/images will appear above the image (not sharing the same horizontal space).
• LAYOUT_NEWLINE_AFTER: Insert a newline after the image is drawn. Subsequent text/images

will appear below the image.

The following code example demonstrates it:

// Create an image
Image im = Imae.createImage("/someimage.png");
// Append to a form with the specified layout
fmMain.append(new ImageItem(null, im, ImageItem.LAYOUT_CENTER, null));

The result would be:

Conclusion

Finally, I hope this post helped you for building simple screens with JavaME. The next part of this series will treat about the Events (MIDP's User Interface Hierarchy: Event Handling) that the device should handle when a user selects a command or changes the state of the Items discussed in this post.