The Java ME
Mobile Information Device Profile (MIDP) first customer
ship (FCS) release provides a targeted Java API for writing wireless applications
that run in all mobile phones and two-way pagers that support the MID profile. To
use the MID profile APIs, you will need to download and install the
Java ME Connected Limited Device Configuration (CLDC).
Another name for MIDP applications is MIDlets. Like applets, MIDlets are
controlled by the software that runs them. In the case of an applet, the underlying
software is a browser or the appletviewer tool. In the case of a
MIDlet, the underlying software is the cell phone or two-way pager device
implementation that supports the CLDC and MIDP.
This article is the first in a series on MIDP application programming. It introduces you to the MIDlet test environment and the MIDP APIs with a very simple MIDlet example.
The MIDP download includes an examples directory that contains a
number of example MIDlets. One of those examples is HelloMIDlet. The
only thing it does is display text in the display area of a mobile phone or two-way
pager. While the code is very short and simple, this MIDlet is a good place to
start learning the MID profile because it introduces you to the MIDlet test
environment and the structure of a MIDlet.
Note: Instructions for compiling and running theHelloMIDletexample are in MIDP Setup Explained. You can find additional information in the MIDP download underdocs/MIDletInstructions.html.
The figure at right shows how HelloMIDlet looks when it runs. The MIDP
executable is a test environment that provides the cell phone image, display area,
and key input. All MIDlets extend the MIDlet class, which is the
interface between the runtime environment (the application manager), and the MIDlet
application code. The MIDlet class provides programmatic interfaces
for invoking, pausing, restarting, and terminating the MIDlet application. MIDP
applications are portable across cell phones and pagers, and the MIDP platform
handles differences in screen size and button layout.
The MIDlet runs in the display area and accepts keypad input by way of mouse clicks. There are several kinds of keys on the MIDlet test environment keypad: soft buttons, control keys, navigation keys, and alphanumeric keys.
The soft buttons are the two angled keys to the left and right of and
directly below the display area. Soft buttons invoke application commands, and
their exact functionality is determined by the labels that appear near them on the
screen. In the figure at right, the left soft button is mapped to the
Exit command shown in the display just above it.
The control keys are the keys with the green and red telephone handset icons
on them. Control keys are found on most handheld phones and sometimes labeled
Talk and End. Because the test environment is not an
actual phone, control keys are not used for any call control from within the
MIDlet; however, the End (red) key terminates the currently running
MIDP application.
While the red key terminates the running MIDlet by calling the
destroyApp(true) method, invoking the Exit command by
pressing the Exit soft key sends a command event to the application's
commandAction method, which you can implement to exit or doing
something else.
The navigation keys are the five keys with the arrows and dot. Navigation keys let you move around and select items in the display area.
The alphanumeric keys are the 12 keys with numbers, letters, and symbols on them at the bottom. Alphanumeric keys let you enter numbers, letters, and symbols into the display area.
When a text entry screen is showing, the button on the alphanumeric keypad with the pound sign and up arrow lets you cycle through several different input modes that allow entry of lowercase letters, uppercase letters, numbers, or symbols. The top of the display area indicates which one is active.
The HelloMIDlet user interface is created from a TextBox
component, which is similar to the Abstract Window Toolkit (AWT)
TextArea and TextField components. MIDlet UI components
are designed to meet the low memory and small footprint requirements of cell phone
and two-way pager display areas. If you are already familiar with creating user
interfaces using AWT components, your learning curve for creating MIDlet user
interfaces will be somewhat shorter because you can apply some of what you already
know to MIDlet components.
A MIDlet TextBox component has three areas: title, initial contents,
and command. When you create the TextBox component, you specify text
for the title and initial contents areas. Once created, you add commands to its
command area and tell the MIDlet to listen for action events by calling the
TextBox.setCommand and TextBox.setCommandListener
methods.
In the HelloMIDlet example, the Hello MIDLet text appears
in the title area, and the Test String text appears in the initial
contents area. The Exit command appears in the command area, and is
mapped to the control keys directly below it and to the right.
The command-to-key mapping is device dependent, and handled by the device according
to the type specified when you create the command. The MIDP Command
class lets you specify the following command types:
BACK,
CANCEL,
EXIT,
HELP,
ITEM,
OK,
SCREEN, and
STOP.
In the HelloMIDlet example, pressing the soft button that has the
Exit label above it calls the MIDlet's commandAction()
method and passes it a reference to the exitCommand command. Pressing
the red key calls the MIDlet's destroyApp(true) method. After the
MIDlet exits by either invocation, the test environment returns to the application
manager if it was invoked by the application manager, or exits the test environment
entirely.
If an application has more than one command of the same type, the command's priority value describes its importance in terms of the command to key mappings. The lower the priority value, the greater the importance of the command.
The device chooses the placement of a command based on the type of command and then places commands with the same type by their priority order. This might mean that the command with the highest priority is placed so the user can trigger it directly, and that commands with a lower priority are placed on a menu.
MIDlet code structure is very similar to applet code. There is no main
method and MIDlets always extend from the MIDLet class. The user
interface components are in the lcdui package, and the
MIDlet class in the MIDlet package provides methods to
manage a MIDlet's life cycle.
The complete, uncommented code appears here. The sections below describe the parts of the MIDlet code beginning with the class declaration.
import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
public class HelloMIDlet extends MIDlet
implements CommandListener {
private Command exitCommand;
private Display display;
private TextBox t = null;
public HelloMIDlet() {
display = Display.getDisplay(this);
exitCommand = new Command("Exit", Command.EXIT, 2);
t = new TextBox("Hello MIDlet",
"Test string",
256, 0);
t.addCommand(exitCommand);
t.setCommandListener(this);
}
public void startApp() {
display.setCurrent(t);
}
public void pauseApp() {
}
public void destroyApp(boolean unconditional) {
}
public void commandAction(Command c, Displayable s) {
if (c == exitCommand) {
destroyApp(false);
notifyDestroyed();
}
}
}
The HelloMIDlet class extends MIDLet and implements the
CommandListener interface. The MIDlet class defines an
MIDP application and provides the life cycle methods. The
CommandListener interface allows a HelloMIDlet object to
be an action listener for command events. In this example, the
HelloMIDlet object listens for exit events.
public class HelloMIDlet extends MIDlet
implements CommandListener {
Instance variables store the unique data for an instance of the
HelloMIDlet class, and make the data available to the constructor and
life cycle methods. The Command, Display, and
TextBox instance variables are initialized in the constructor.
private Command exitCommand; private Display display; private TextBox = null;
The constructor gets the Display object for this instance of the
HelloMIDlet class and creates a command of type EXIT with
a priority of 2. The Display object represents the
manager of the display and input devices of the system. It includes methods for
retrieving properties of the device and for requesting that objects be displayed on
the device.
The constructor creates and initializes the MIDlet's user interface, which is a
TextBox object with a title of Hello MIDlet, display text
of Text string, a maximum character width of 256 characters, and no
constraints on inputs. A TextBox receives inputs from the keypad, and
input constraints restrict the characters that can be entered. Input constraints do
not currently impose any syntax checking or formatting.
The startApp method does the following to set up command action
listening and make the user interface visible:
exitCommand is added to the TextBox.HelloMIDlet action listener is set on the
TextBox (t.setCommandListener(this)) so the
HelloMIDlet.commandAction method will be called whenever a command on
the TextBox generates an event.TextBox is passed to the Display to make it
visible on the device's display. Every MIDlet has one and only one
Display object.
public HelloMIDlet() {
display = Display.getDisplay(this);
exitCommand = new Command("Exit", Command.EXIT, 2);
t = new TextBox("Hello MIDlet",
"Test string",
256, 0);
t.addCommand(exitCommand);
t.setCommandListener(this);
}
The underlying device implementation controls the MIDlet by calling its life cycle
methods. The device implementation calls the startApp method to make
the MIDlet ready for use. In this example, the startApp() method makes
the Display current.
public void startApp(){
display.setCurrent(t)
}
public void pauseApp() { }
public void destroyApp(boolean unconditional) { }
The device implementation calls the pauseApp method to stop the MIDlet
temporarily. This method should release shared resources such as threads or
connections. This simple example has no shared resources. The implementation might
ask the MIDlet to continue by calling the startApp() method again.
The device implementation calls the destroyApp method to terminate and
destroy the MIDlet. This method should release all shared and local resources, and
save any persistent data such as preferences or state. This simple example uses no
resources or persistent data.
The commandAction method is passed an event object that represents the
action event that occurred. Next, it uses an if statement to find out
which component had the event, and takes action according to its findings.
If the command action is a command of type Exit, the application is
destroyed, and the application management software is notified that the MIDlet has
entered the destroyed state (notifyDestroyed).
public void commandAction(Command c, Displayable s) {
if (c == exitCommand) {
destroyApp(false);
notifyDestroyed();
}
}
}
This simple example shows how easy it is to write and run a small MIDlet consisting of one user interface component and command. MIDlet programming is easy in comparison to programming with Java 2, Standard Edition, because the MIDP API is simpler. There are only a handful of classes you need to learn before you can start writing MIDlet applications.
Future articles in this series will cover creating more than one command, placing commands on menus, using a canvas for a drawing area, and making Internet connections.
© 1994-2005 Sun Microsystems, Inc.