Programming MIDlet GUIs
Peter Komisar ©  Conestoga College  version  1.1 /  2009
reference: Learning Wireless Java, Qusay H. Mahmoud,
O'Reilly, User’s Guide Sun JavaTM Wireless Toolkit for
CLDC Version 2.5.2, Sun MicroSystems, 'Java 2ME and
MIDP Development', John Muchow, The Mobile Information
Device Profile and MIDlets, Part 2, Kim Topley, onjava.com

MIDlet Life Cycle

Following is a quick recap of the life cycle methods
of a midlet, showing the three states, paused, active
and destroyed.

Diagram of a Midlet Life Cycle

        +------> PAUSED -----+
        |          |         |
   pauseApp()  startApp()    |
        |          |         |
        |          V         |
        +-----<  ACTIVE      |
                          destroyApp()
                             |
               DESTROYED <---+    
                   |
                  _|_
                  

We saw that we needed all these methods to be
explicitly present in our midlet code. 


The Application Manager

The application manager manages our midlets and
is pre-installed on the MIDP device. It is similar to the
applet context that is provided by browsers but is
described as providing additional operating system
functions.

Following are requirements made on the application
manager by the MIDP specification.


Application Manager Requirements
MIDP GUI Programming

Some who come from Java might ask why the AWT
or Swing components would not be used.  The decision
not to use them were made for the following reasons.


Reasons Why AWT was not Used With MIDlets
The  javax.microedition.lcdui package

The GUI components are held in the microedition's
lcdui package. These are the classes that are
imported with the following import.

Example

import javax.microedition.lcdui.*;


The 23 classes and 4 interfaces are listed below.

GUI Classes
  • Alert
  • AlertType
  • Canvas
  • ChoiceGroup
  • Command
  • CustomItem
  • DateField
  • Display
  • Displayable
  • Font
  • Form
  • Gauge
  • Graphics
  • Image
  • ImageItem
  • Item
  • List
  • Screen
  • Spacer
  • StringItem
  • TextBox
  • TextField 
  • Ticker


Also in the package are the following interfaces
which we look at later.


GUI Interfaces
High and Low Level Components
// structured versus customizable

The MIDP GUI components have what are called
high-level and low-level components each with their
own event types.

High Level Components are portable but not very
customizable. They inherit from the 'Screen' class.

Low-level components give you fine control but may
not port well between devices. The Canvas and
Graphics class implement the low level APIs.


High Level Class

The Screen class is the heart of the high-level API
and descends from the 'Displayable' class, not to
be confused with the 'Display' class we have seen
in earlier examples. Screen class itself is abstract
and acts a parent for the Alert, Form, List and TextBox
classes.

Hierarchy of the Screen Class

       Displayable
       |
     Screen
       |___Alert
       |___Form
       |___List
       |___TextBox
Following is the class signature of the Screen
class.

Signature of the Screen class
public abstract class Screen extends Displayable
Screen's parent Displayable supplies the following
methods.

Displayable Methods
// args and return types eliminated

Screen Defines No Methods!

Screen is marked abstract. As a result you will
never instantiate the Screen class. Also Screen
is somewhat unique in that it does not define
any methods! Rather you will use the methods
defined in it's descendants.

Change Screen Contents Only When Not Visible

Screen descendants have an auto-painting
feature where changes made to their appearance
show automatically. The API recommends that
changes be made to the content of a Screen
object only while it is not visible. That is, while
another Displayable object is visible in the
foreground.

In Earlier Versions

Screen use to have four methods, which were
used to read and write tickers and read and write
title properties. These methods were moved to the
superclass, Displayable in MIDP 2.0.


Screen Types

Three types of screens are described.

Screen Types
 While there are a number more classes to talk
about let us begin by exampling the four descendants
of Screen.

We already used the Form class, but we present
it again for the record. Later we will look at it in more
detail. Note we also used the Diplay class in the above
example. We will talk about it next.


A Form Component Midlet

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

public class Form_Screen extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);
   Form mainForm = new Form("TinyMIDlet");
   mainForm.append
("Here we are using one of the screen descendants, the Form Object.");
   display.setCurrent(mainForm);
}
// destroyApp(boolean) is abstract and must be overridden

public void destroyApp(boolean unconditional) {}
// ditto for pauseApp()
   public void pauseApp(){}
}

 
The Display Class

The Display class is alone in it's own hierarchy
with no descendants. The Display class acts as
the manager of the display as well as the input
devices of the system. It has methods for retrieving
properties of the device and for displaying objects
to screen.


getDisplay( ) and set/getCurrent( )

There is one and one only, instance of Display per
MIDlet. It is obtained using the getDisplay() method. 

The Display class has a setCurrent()  method that
sets the current Displayable object and a getCurrent()
method for retrieving the current Displayable object.


Basic Procedure For Using MIDlet GUIs

Following are the basic steps involved in creating
a display.

1) Get the display Object

Example

Display display = Display.getDisplay(this);

2) Instantiate the Screen object you wish to show


Example

Form mainForm = new Form("TinyMIDlet");


3)  Make it the current viewable object


Example

  display.setCurrent(mainForm);


A Visit to the TextBox Class

Following is the constructor for the TextBox class.


TextBox Class Constructor

TextBox(String title, String text, int maxSize, int constraints)

where: title       - is the title string
       text        - is the initial contents
       maxSize     - maximum size in characters
       constraints - are input constraints, such as
                     data types that are allowed        


Minor Curve Ball!

There is a minor curve ball here. The constraints argument
described in the TextBox constructor are static fields of .
the TextField class.

Text Field Constants

These are interesting to take a look at, in advance of
looking at the TextField component as they  suggest
the sorts of text constraints that may be available for a
given implementation. These constraints could be useful
as  'front end' validators for different sorts of applications.

Text Field Constants

Included here are calls on the maximum size, the constraint
type value and whether and how many  colors are supported.


A TextBox Component MIDlet

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

public class TextBox_Screen extends MIDlet{

public void startApp() {
  Display display = Display.getDisplay(this);
  String string="The rain in Spain falls mainly in the plains.";
  TextBox box = new TextBox("Text Screen",string,512,0);
  box.setString(
     "Max. Size:        " + box.getMaxSize()  + "\n" +
     "Constraints:      " + TextField.ANY     + "\n" + 
     "Color Support:    " + display.isColor() + "\n" +
     "Number of Colors: " + display.numColors() 
      );
   display.setCurrent(box);
  }
  
// abstract destroyApp(boolean) is overridden

public void destroyApp(boolean unconditional) {}

// ditto for pauseApp()

  public void pauseApp(){}

}

Using setString( ) like append(  )

Really, the way we have used TextBox here is little
different than appending text to the Form object.
Instead of an append( )  method we used a setString( )
call. We will also look at TextBox more carefully later in
the discussion.


The List Class

The next of our four key high level screens is the List
class. The signature of the List class shows it implements
the Choice interface.


The List Class Signature  // implements Choice
public class List extends Screen implements Choice
The List class constructors are as follows. There is
a simple one that enables setting a title and specifying
what type of choice the list will represent.


The List Class Constructors
The List Types

There are four types of Choices specified as constants
in the Choice interface.

Types of Choices
Static Constants Representing The Choice Types
Example

Choice.MULTIPLE

Here is a short example showing the MULTIPLE
choice.

List Multiple Choice Example

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

public class NewAutos extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);
   String string="NEW AUTO TYPES";
   List list = new List(string,Choice.MULTIPLE);
  
   list.append("ELECTRIC",null);
   list.append("DIESEL",null);
   list.append("HYBRID",null);
   list.append("FUEL CELL",null);
   display.setCurrent(list);
   }
   //  destroyApp(boolean) is abstract and must be overridden

public void destroyApp(boolean unconditional) {}

//  ditto for pauseApp()
 
public void pauseApp(){}
}


Tickers and Titles

The Display class has taken over setting a Ticker
and a Title from the Screen class.


The Ticker Class

The Ticker class implements a ticker tape that runs
continuously across a display.  The Ticker class is
simple. It has a constructor that take a String object
that it will run as a banner.

It also has  get and set methods for this string.


Ticker Class Constructor
 Ticker Class Methods

Setting a Ticker

Setting a Ticker object is quite simple. The
setTicker( ) method is used with an instantiation
of the Ticker that takes as an argument the string
that is to be displayed. We could also use the
setString( ) method.

We can put the above information to use in the following
MIDlet.


List and Ticker Example

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

public class TickerList extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);
   String string="The rain in Spain falls mainly in the plains.";
   List list = new List("List Screen",Choice.EXCLUSIVE);
   list.setTicker(
      new Ticker
      ("THIS IS A CAKE. CAN YOU HAVE IT AND EAT IT TOO?"));
   list.append("EAT THE CAKE",null);
   list.append("HAVE THE CAKE",null);
   list.append("EAT AND HAVE IT TOO!",null);
   list.append("I DON'T LIKE CAKE!",null);
   display.setCurrent(list);
   }
   //  destroyApp(boolean) is abstract and must be overridden

public void destroyApp(boolean unconditional) {}

//  ditto for pauseApp()
 
public void pauseApp(){}
}


Limitations of the Ticker Object

Alert Class

The final screen to test is the Alert class. It may contain
text or text and an image. It has two constructors.

Alert Constructors
Null values can be inserted if one of the arguments
needs to be omitted.


Timeout Values

An aspect that isn't evident regarding the Alert class
is that it has a default time out value. It does have methods
to discover and set the value shown below. The methods
use int type for the timeout values in milliseconds.

Alert Timeout Methods
There is  also a constant value to timeout forever.

Example

Alert.FOREVER

AlertType

Alerts can trigger different sorts of signals including
sounds. AlertType is a class itself and has the following
constants.

AlertType Constants

 Alert Methods

Aside from using the constructor, images, strings and
alert types can be set using Alert class methods.
Following are minimized signatures of the Alert methods.

Alert Methods in Minimized Form

In the following example an Alert comes up for
four seconds and then disappears to reveal the
underlying text box. Notice a different overloaded
version of the setCurrent( ) method is used.

Timed Alert Example

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

public class AlertScreen extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);
   String string="The rain in Spain falls mainly in the plains.";
   TextBox box= new TextBox("TEXTER", string, 80,TextField.ANY);
   Alert alert =new Alert
("RAIN NOTICE","It is raining in Spain!",null,AlertType.CONFIRMATION);
   alert.setTimeout(4000);
   display.setCurrent(alert,box);
   }
 
 
//  destroyApp(boolean) is abstract and must be overridden

public void destroyApp(boolean unconditional) {}

//  ditto for pauseApp()
  public void pauseApp(){}

}

Timed vs Modal Alerts

In the previous example the alert disappeared after
a prescribed amount of time had passed. In the
case of modal alerts the alert stays on until the
screen is closed by the user.

The following MIDlet examples a modal Alert.


Modal Alert Example

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

public class AlertScreen2 extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);
String
string="The rain in Spain falls mainly in the plains. It's normal !!!";
   TextBox box= new TextBox("TEXT BOX", string, 80,TextField.ANY);
   Alert alert =new Alert
("RAIN ERROR","  It's not suppose to raining!",null,AlertType.ERROR);
   alert.setTimeout(Alert.FOREVER);
   display.setCurrent(alert,box);
   }
//  destroyApp(boolean) is abstract and must be overridden

public void destroyApp(boolean unconditional) {}

//  ditto for pauseApp()

  public void pauseApp(){}

}

More on the Form Class

Earlier we used the Form class and it's append( )
method as a tablet to add String objects to.

The Form class also serves as a container to which
a  developer can add a set of objects. These objects
may include:

Items that can Be Added to a Form
The Form Class Constructors

The Form class has the following two constructors,
a simple constructor based on a string and one that
takes a string and an array of Item type.

 
Form Class Constructors

Detour to The Item Class

The Form constructor takes an array of Item
type which sends us on a detour to get some
detail about the Item class.

The Item class serves as the abstract parent for
a set of elements that can be added to a form.
This brings into play a number of additional GUI
components. Following is the Item class hierarchy.


Item Class Hierarchy

Item
  |__ChoiceGroup
  |__CustomItem
  |__DateField
  |__Gauge
  |__ImageItem
  |__Spacer
  |__StringItem
  |__TextField


Two Techniques for Loading Forms


We can use the simple constructor form to create
a blank form and then use the append() method to
add items to our form.

We saw the append method in an earlier example.
Let us borrow from the item list above the StringItem
that serves as a label object and the venerable
TextField object.


A Quick Note on StringItem and TextField

Two of the Item descendants are StringItem and
TextField which we would like to use in our examples.

The Micro version of these elements anticipate
some of your needs. The String Item also serves
as a information device. It has two arguments
for two strings. One ends up in bold text on screen
and serves as a title for the following information
byte. The second string is the instruction or piece
of information itself.  The more complex constructor
has an appearance mode.

StringItem Constructors
The appearance mode may allow the String item
take on a different appearance. The constant
values are as follows.

Item Class Appearance Mode Constants

The following example shows the approach
using the simple form of the constructor followed
by instantation of objects and adding them with
the append(  ) method.


Sample Using Form's Simple Constructor

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

public class SimpleForm extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);

   Form form= new Form("SIMPLE FORM");
   StringItem instruction=new StringItem
("Name & Registration Number", "Please enter your first and last name, and your product registration number." );
 form.append(instruction);

   TextField firstField = new TextField("First Name",null,24,TextField.ANY);
   form.append(firstField);
  
   TextField lastField=new TextField("Last Name","",24,TextField.ANY);
   form.append(lastField);
 
   TextField regField = new TextField
("Registration Number",null,24,TextField.ANY);
   form.append(regField);
  
   display.setCurrent(form);
   }
public void destroyApp(boolean unconditional){}
public void pauseApp(){}
}

Using the array form of the constructor could save
you a bit of coding. Instead of using an append
statement for each item, the items are collected into
an array and then added to the constructor.


Sample Using Form's Array Form Constructor

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

public class ArrayForm extends MIDlet{

public void startApp() {
   Display display = Display.getDisplay(this);
  
 StringItem instruction=new StringItem
    ("Instruction", "Enter your name and product registration number" );
 TextField firstField = new TextField("First Name",null,24,TextField.ANY);
 TextField lastField=new TextField("Last Name","",24,TextField.ANY);
 TextField regField = new TextField
                     ("Registration Number",null,24,TextField.ANY);
 
   Item[] items={instruction,firstField,lastField,regField};  
   Form form= new Form("SIMPLE FORM",items);
   display.setCurrent(form);
   }
public void destroyApp(boolean unconditional){}
public void pauseApp(){}
}

Coming Soon!

We will cover the remaining  Item classes next week.
After that we start our discussion of event processing
so we can start making the widgets operational.


Assignment

1. Create a MIDLET with a List Screen included. As a title
put the name of some kind of commodity for which options
can be specified. For instance a car, boat or house.  Make
the list a multiple choice list. Include at least five options.
Also include an Alert that is modal, stating that the user
recognizes these choices are final.

Optionally add images. Whether with or without images
screen shot the emulation and include your source code.

// note if you use images you will need to drop them in
// the res folder, you should be able to use gif, jpg or png files.