Event Handling with Commands

Team-Fly

---

Displayable, the parent of all screen displays, supports a very flexible user interface concept, the command. A command is something the user can invoke-you can think of it as a button. Like a button, it has a title, like "OK" or "Cancel," and your application can respond appropriately when the user invokes the command. The premise is that you want a command to be available to the user, but you don't really care how it is shown on the screen or exactly how the user invokes it-keypad button, soft button, touch screen, whatever.

Every Displayable keeps a list of its Commands. You can add and remove Commands using the following methods:

 public void addCommand(Command cmd) public void removeCommand(Command cmd) 

Creating Commands

In the MIDP, commands are represented by instances of the Command class. To create a Command, just supply a name, a type, and a priority. The name is usually shown on the screen. The type can be used to signify a commonly used command. It should be one of the values defined in the Command class. Table 5-1 shows the type values and their meanings.

Table 5-1: Command Types

NAME	MEANING
OK	Confirms a selection.
CANCEL	Cancels pending changes.
BACK	Moves the user back to a previous screen.
STOP	Stops a running operation.
HELP	Shows application instructions.
SCREEN	Generic type for specific application commands.

To create a standard OK command, for example, you would do this:

 Command c = new Command("OK", Command.OK, 0); 

To create a command specific to your application, you might do this:

 Command c = new Command("Launch", Command.SCREEN, 0); 

It's up to the MIDP implementation to figure out how to show the commands. In the Sun J2MEWTK emulator, commands are assigned to the two soft buttons. A soft button is a button on the device keypad with no predefined function, which allows it to serve a different purpose at different times. If there are more commands than there are soft buttons, the commands that don't fit will be grouped into a menu that is assigned to one of the soft buttons.

A simple priority scheme determines who wins when there are more commands than available screen space. Every command has a priority that indicates how hard the display system should try to show the command. Lower numbers indicate a higher priority. If you add a command with priority 0, then several more with priority 1, the priority 0 command will show up on the screen directly. The other commands will most likely end up in a secondary menu.

Responding to Commands

By themselves, Commands aren't very exciting. They'll show up on the screen, but nothing happens automatically when a user invokes a command. An object called a listener is notified when the user invokes any command in a Displayable. This follows the basic form of the JavaBeans event model; a Displayable is a unicast event source. A Displayable fires off an event every time the user invokes one of its Commands.

The listener is an object that implements the CommandListener interface. To register the listener with a Displayable, use the following method:

 public void setListener(CommandListener l) 

Displayable is a unicast event source because it can only have one listener object. (Multicast event sources can have multiple listeners and use an add… method for adding listeners rather than a set… method.)

Implementing a CommandListener is a matter of defining a single method:

 public void commandAction(Command c, Displayable s) 

When a command is invoked, the Displayable that contains it calls the commandAction() method of the registered listener.

Tip 

Event listeners should not perform lengthy processing inside the event-handling thread. The system uses a thread to call commandAction() in response to user input. If your implementation of commandAction() does any heavy thinking, it will tie up the system's event-handling thread. If you have anything complicated to do, use a separate thread.

A Simple Example

By way of illustration, consider the following class:

 import javax.microedition.midlet.*; import javax.microedition.lcdui.*; public class Commander extends MIDlet {   public void startApp() {     Displayable d = new TextBox("TextBox", "Commander", 20, 0);     Command c = new Command("Exit", Command.EXIT, 0);     d.addCommand(c);     d.setCommandListener(new CommandListener() {       public void commandAction(Command c, Displayable s) {         notifyDestroyed();       }     });     Display.getDisplay(this).setCurrent(d);   }   public void pauseApp() {}   public void destroyApp(boolean unconditional) {} } 

This MIDlet creates a TextBox, which is a kind of Displayable, and adds a single command to it. The listener is created as an anonymous inner subclass. In Sun's J2MEWTK, this MIDlet appears as shown in Figure 5-3.

Figure 5-3: A simple MIDlet with a single command, Exit

Figure 5-3 shows the Exit command being mapped to one of the MIDP simulator's soft buttons. If you add another command to this MIDlet, it will be mapped to the other soft button. If you continue adding commands, the ones that don't fit on the screen will be put into an off-screen menu. For example, a screen with four commands shows up in the MIDP simulator, as illustrated in Figure 5-4a.

Figure 5-4: This MIDlet has more commands than the device has soft buttons. Invoking the (a) system-generated Menu command brings up the (b) remaining commands.

If you press the soft button for Menu, you'll see the remainder of the commands as shown in Figure 5-4b. Menu items can now be selected by pressing a number or using the arrow keys for navigation. In the example shown in Figure 5-4, the Exit command is given a higher priority (lower number) than the other commands, which insures that it appears directly on the screen. The other commands, with a lower priority, are relegated to the command menu.

---

Team-Fly