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 theHelloMIDlet
example 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.