J2ME mobile applications are simple solutions that allow users to manage their data using different controls that are placed in forms, windows or Displayable. In the J2ME API, the equivalent of desktop applications windows is represented by a relative reduced set of forms which are subclasses of Displayable class. The entire framework is a limited, smaller set of classes which are easy to use and less demanding of memory and processor resources than the desktop counterpart as Java AWT (Abstract Window Toolkit) or Swing.

The J2ME platform provides developers 2 API’s to define and control the user interface of the mobile application:

• the high level API which is covered in this post, implemented by the javax.microedition.lcdui package;
• the low-level user interface API which is more difficult to use but more powerful in terms of what you can do; the low level API allows also the development of games;

Before understanding how to use Display and Displayable type forms you must understand that despite things look more complicated than the desktop approach (J2SE – AWT or Swing), in fact they are really simple because:

• the range of mobile devices that support J2ME applications is very large; each has unique characteristics as keyboard type, display size and colors, input methods, touch screens;
• the J2ME architecture has been designed to optimize use of memory and processor power; the framework is reduced and the virtual machine is very efficient regarding memory requirements.

The simplicity of the J2ME user interface is based on these rules:

• the number of available controls is very reduced compared with J2SE AWT or Swing;
• there are special types of forms for particular types of activities; there is a multi-purpose form but it is limited regarding what and how controls can be used and customized;
• there are limited possibilities to control the look and feel of the forms because you CAN’T customize colors, fonts or components layout;
• only ONE form or window is visible, active or in the foreground; the J2ME API provides a way, by using a Display instance, to manage which form is the visible one or is in the foreground

The Display class

The Display class represents a manger for a virtual display which is associated with the mobile screen.

The class is very important because:

each MIDlet application has only one Display instance;

the instance can’t be created and it is obtained from the Display static method getDisplay( );

the Display instance is used to decide which form is displayed or it us in the foreground;

to save processor time, it is better to save the reference of the Display instance once the MIDlet has been created; if you remember from the J2ME tutorial – How to create a simple MIDlet application with NetBeans post, there are some important events in the MIDlet lifecycle; the startApp(), starter function of the application, is the a good place to initialize the Display reference:

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

public class MidletUI extends MIDlet {

    //define the Display reference of the MIDlet
    Display midletDisplay = null;

    public void startApp() {
	//get the reference for the Display instance
        if(midletDisplay==null)
            midletDisplay = Display.getDisplay(this);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
    }
}

Now, that you have the reference of the Display class you can use it to display different types of forms, only once at a time.

The method of the Display class used to display a form is setCurrent(). But, in order to create forms let’s see what Displayable is.

The Displayable class

The Displayable class is the second important class when talking about MIDlets user interface. The Displayable class represents an abstract class for all the objects that has the capability to be placed on a Display. And these are the different types of forms.

The next figure describes the main types of Displayable:

J2ME Display framework

Screen – is the another abstract class from which are derived the main high-level UI forms;

Canvas – it is another abstract class that allow developers to use the low-level user interface API; the Canvas class provides the paint() method which can be used to draw the entire interface;

The main types of forms are:

Form – it is the most flexible type of windows because it can contain different types of user controls like TextField, ChoiceGroup, StringItem and others;

TextBox – is a special type of form that has a multiline text box that extends on the entire screen; the sms editor is a good example of TextBox form;

List – is a form that represents a vertical list of items; in the Desktop API, it is the equivalent of the ListBox control;

Alert – is the classic DialogBox or the message box form used to alert user with different short messages;

How to display a form

In order to see how simple is to create a form and display it, we will create a text editor based on the TextBox form:

J2ME TextBox Example

1. Define the TextBox reference:

	//define the TextBox reference
	TextBox textBox = null;

2. Because the TextBox form is needed by the application and it is not something temporary, we will create the form at the same time with the MIDlet; this is done in the MIDlet constructor; REMEMBER that if you construct a form, it is not displayed until you use setCurrent() method of the Display instance;

    //define the MIDlet constructor
    public MidletUI()
    {
        textBox = new TextBox(
                "Hello J2ME!",      //the text from the form title bar
                "Your message is: ", //content
                255,    //maximum number of characters
                TextField.ANY); //filter on the content
    }

3. The TextBox constructor, public TextBox(String title, String text, int maxSize, int constraints) requires:

• title – the text from the form title bar; can be changed later using the class setTitle() method;
• text – the content of the TextBox;
• maxSize – maximum number of accepted characters; even if you set a higher limit, the actual limit may be lower than that;
• constraints – represent filters for the user input; all constraints are static fields in the TextField class; this can be helpful because it can make it easier to introduce numbers from a non QWERTY keyboard; for example the TextField.NUMERIC filter allows only the input of digits; other constraints are TextField.ANY, TextField.EMAILADDR, TextField.NUMERIC, TextField.PHONENUMBER, TextField.URL, TextField.DECIMAL

4. Because we want to display the TextBox right after the application starts, the place for the call to setCurrent() is the startApp method:

    public void startApp() {
        //get the reference for the Display instance
        if(midletDisplay==null)
            midletDisplay = Display.getDisplay(this);

        //display the form
        midletDisplay.setCurrent(textBox);
    }

How to display Alerts

Alert is another class derived from Screen and is a special form used to display short messages. The detailed constructor of the Alert is public Alert(String title, String alertText, Image alertImage, AlertType alertType):

• title – the text from the form title bar;
• alertText – the text from the Alert message;
• alertImage – an image to be loaded into the Alert;
• alertType – the type of the Alert; these are predefined values as AlertType.INFO, AlertType.ALARM, AlertType.CONFIRMATION, AlertType.ERROR, AlertType.WARNING, used to control (somehow) how the alert is delivered to the user.

The Alert lifecycle is very short and after it is closed another form is placed in the foreground. To do this, Alert is displayed using the two parameters form (the second parameter is the form to be displayed after the alert is closed) of the setCurrent() method of Display:

public void startApp() {
        //get the reference for the Display instance
        if(midletDisplay==null)
            midletDisplay = Display.getDisplay(this);

        //display the form
        midletDisplay.setCurrent(textBox);

        //define an alert
        Alert alert = new Alert("Info",
                "The MIDlet has started !",
                null, AlertType.INFO);

        //display the alert and set the TextBox as the next displayable
        midletDisplay.setCurrent(alert, textBox);
    }

By default, an Alert is displayed only for 2 seconds. If you want to change the timeout, you can use  the setTimeout(int time) method from the the Alert class. For the Alert.FOREVER parameter, the Alert is displayed until the user presses the OK key.

	alert.setTimeout(Alert.FOREVER);

J2ME Alert Example

The complete example of the TextBox J2ME application is available in this complete solution file.