Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

Java ME Command mapping for Nokia Asha

From Wiki
Jump to: navigation, search

This article explains how LCDUI Commands are mapped in Nokia Asha Software Platform 1.0 devices such as Nokia Asha 501. It also explains how a Command can be mapped to the physical Back button.

Article Metadata
Code ExampleTested with
Devices(s): Nokia Asha 501
Created: jarmlaht (09 May 2013)
Last edited: hamishwillee (13 Aug 2013)



As explained in MIDP specification, "The Command class is a construct that encapsulates the semantic information of an action." and "The behavior that the Command activates is not encapsulated in this object. The action is defined in a CommandListener associated with the Displayable." MIDlets commonly have Commands implemented, which are associated with certain actions, like a Command for closing the MIDlet.

This article shows how to use Commands and how they are mapped in Asha Software Platform 1.0, specifically in Nokia Asha 501 device.

Using Commands in MIDlets

As said above, a Command works as a link to a certain action. Commands are commonly mapped to an options menu, softkey or other location on the device's UI. Command contains a label, type and priority number. Label is a visible name for the Command. Type is used for specifying the intent of the Command. The defined types are BACK, CANCEL, EXIT, HELP, ITEM, OK, SCREEN, and STOP. In practice the types are used for defining the position of the Command in the options menu, or in other words, the importance (priority) of the Command. In addition to the type, priority number can be used for defining the importance of a Command. Priority values are integers, where a lower number indicates greater importance. These numbers are especially useful, when there are several Commands of the same type.

The following code shows how Commands are used:

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
public class CommandMapping extends MIDlet implements CommandListener {
private Form form;
private Command itemCommand;
private Command stopCommand;
private Command cancelCommand;
private Command exitCommand;
private Command backCommand;
private Command helpCommand;
private Command okCommand;
private Command screenCommand;
public void startApp() {
form = new Form("CommandMapping");
itemCommand = new Command("ITEM", Command.ITEM, 1);
stopCommand = new Command("STOP", Command.STOP, 1);
cancelCommand = new Command("CANCEL", Command.CANCEL, 1);
exitCommand = new Command("EXIT", Command.EXIT, 1);
backCommand = new Command("BACK", Command.BACK, 1);
helpCommand = new Command("HELP", Command.HELP, 1);
okCommand = new Command("OK", Command.OK, 1);
screenCommand = new Command("SCREEN", Command.SCREEN, 1);
public void pauseApp() {}
public void destroyApp(boolean unconditional) {}
public void commandAction(Command c, Displayable d) {
form.append("Command: " + c.getLabel());
if (c == itemCommand) {}
if (c == stopCommand) {}
if (c == cancelCommand) {}
if (c == exitCommand) {
if (c == backCommand) {}
if (c == helpCommand) {}
if (c == okCommand) {}
if (c == screenCommand) {}

Command mapping in Nokia Asha 501

There are small implementation specific differences in command mapping between devices and platforms. The MIDP specification gives only guidelines, how Commands should be mapped. For example, not all the devices have softkeys, where Commands can be mapped. Also the importance (priority) order of Command types can differ. In Nokia Asha 501 the Command type priority order is as follows: ITEM, STOP, CANCEL, EXIT, BACK, HELP, OK, SCREEN.

Asha Software Platform 1.0 has one specific feature in Asha Software Platform 1.0 mapping. The highest priority Command is mapped to a button, which is shown on the bottom of the screen. The image below shows, how it looks Nokia Asha 501 device.

"Go" Command mapped to the command button

Utilizing the physical Back button

Nokia Asha 501 has no physical keyboard, but only Back button (and volume keys and screen lock key). The BACK and EXIT Commands when implemented in a MIDlet make the Back button to work as follows:

  1. If Displayable has EXIT Command implemented, but not BACK Command, pressing Back key closes the MIDlet.
  2. If Displayable has BACK Command implemented, but not EXIT Command, pressing back key handles the BACK Command.
  3. If Displayable has BACK and EXIT Commands implemented, BACK Command is mapped to the Back key and EXIT Command is mapped to the Options menu.
  4. If EXIT Command is mapped to the Back key, it is normally handled by using CommandListener.commandAction() method (it is possible, for example, to show confirmation dialog before exiting).

Note.pngNote: The MIDlet is closed by pressing the Back key (after confirmation is accepted), even if the EXIT Command is not implemented. The MIDlets can also be closed by swiping horizontally across the screen or long pressing the Back button.

One way of utilizing the Back button is to add only one Command of BACK type (and no other Commands) to full screen Canvas. In such case no Options menu is added to the Canvas, but this gives a possibility for example in games to go back in the application UI hierarchy. The BACK Command is normally handled by using CommandListener.commandAction(Command c, Displayable d) method.

// In Canvas:
backCommand = new Command("Back", Command.BACK, 1);
public void commandAction(Command c, Displayable d) {
if (c == backCommand) {

See the attached file for simple example MIDlet about this.

Sensitive API calls and Command handling

As explained above, Command handling happens in CommandListener.commandAction() method. The MIDP specification says, that "The specification does not require the platform to create several threads for the event delivery. Thus, if a CommandListener method does not return or the return is delayed, the system may be blocked. So, there is the following note to application developers: the CommandListener method should return immediately."

The implementation in Asha Software Platform 1.0 works so, that sensitive API calls (like opening HTTP connection, sending text message, taking camera snapshot, etc.) must be put to a separate thread. The following code shows a simple way, how to do this.

public void commandAction(Command c, Displayable d) {
if (c == sendCommand) {
// This won't work, Exception is thrown
send(numberTextField.getString(), messageTextField.getString());
// This works
new Thread() {
public void run() {
send(numberTextField.getString(), messageTextField.getString());
protected void send(final String number, final String message) {
try {
String address = "sms://" + number; // address is for example sms://+358501234567
messageConnection = (MessageConnection);
TextMessage msg = (TextMessage) messageConnection.newMessage(MessageConnection.TEXT_MESSAGE);
catch (IllegalArgumentException iae) {
catch (IOException ioe) {

Example application containing sources, BackKeyTest.jad and BackKeyTest.jar

This page was last modified on 13 August 2013, at 06:12.
86 page views in the last 30 days.