Command Class and Command Listener

Command Object is an instance of the Command class of javax.microedition.lcdui package.  The methods defined in Command class are as follows:

• Command(String label, int commandType, int priority)     -   Creates an instance of the Command class using the parameters passed to it - label, commandType and priority 

• int getCommandType()     -    Retrieves the commandType of a command 

• String getLabel()     -    Retrieves the label of a command 

• int getPriority()     -    Retrieves the priority of a command

We can create an instance of Command class by passing the required parameters to the constructor of the Command class within a J2ME application.  The constructor of the Command class returns a reference to the newly created instance of the Command class (called command object) after its invocation.

The three parameters to be passed to the constructor of the Command class are:

1. The command label
2. The command type
3. The command Priority

Any string passed as value to the first parameter will be used as caption or label of the command on the screen.  The second parameter is any one of the predefined command types from the following list of command types:

• BACK    -    Moves to the previous screen

• CANCEL    -    Cancels the current operation

• EXIT    -    Terminates the application

• HELP    -    Displays help information

• ITEM    -    Maps the command to an item on the screen

• OK    -    Refers to Positive Acknowledgement

• SCREEN    -    Indicates that there is no direct key mapping available on device; command will be mapped to object on a form or canvas

• STOP    -    Stops the current operation

Priority is established by a value assigned to the third parameter of the command declaration.  The priority indicates the preference of each command object created by the application.  A low value has a higher priority than a higher value.  

The device's application manager has the option of ignoring the priority or using the priority to resolve conflicts between two commands.  The application manager may use the priority to determine the order in which command labels appear on the screen.

The following example illustrates the creation of Cancel command:

cancel = new Command("Cancel", Command.CANCEL, 1);

This line of code creates a command object named cancel with highest priority for cancelling the current operation that takes place in the life cycle of an application.

Command Listener

Every J2ME application that creates an instance of the Command class must also provide  the implementation of the CommandListener interface in order to handle the event associated with the command object.  The CommandListener is notified whenever the user interacts with the command object by way of the commandAction() method. 

Classes that implement the CommandListener interface must have the code for commandAction() method in it.  The method commandAction() takes two parameters: a reference to an instance of the Command class, and a reference to the instance of the Displayable class.

The device’s application manager calls the commandAction() method and passes the command selected by the user.  The commandAction() method must contain the code for processing all the events that may occur when the user selects a command through the UI provided in the application.

Here are the steps to follow to implement commandAction():

1. Evaluate the command to determine the command selected by the user, using an if statement.
2. Compare the command (first parameter) with the reference to the instance of the Command class that was returned when we created the command within the application. 
3. Provide the required code in commandAction() based on the events that the user might trigger through the UI provided in the application. 

For instance, Exit command listener is used to determine whether the user selected the Exit command. Make use of the functions - destroyApp() and notifyDestroyed() for implementing Exit command. 

The destroyApp() method is called to unconditionally terminate the application; and before the application terminates, the notifyDestroyed() method is called to notify the device’s application manager that the application is terminating.  The below lines of code provides the code for handling cancel (or exit) command:

public void commandAction(Command command, Displayable displayable) { 

if (command == cancel) { 

destroyApp(false); 

notifyDestroyed(); 

} 

}