Using Alerts - Wireless Java Developing with J2ME, Second Edition

Using Alerts

An alert is an informative message shown to the user. In the MIDP universe, there are two flavors of alert:

A timed alert is shown for a certain amount of time, typically just a few seconds. It displays an informative message that does not need to be acknowledged, like "Your transaction is complete," or "I can't do that right now, Dave."
A modal alert stays up until the user dismisses it. Modal alerts are useful when you need to offer the user a choice of actions. You might display a message like "Are you ready to book these tickets?" and offer Yes and No commands as options.

MIDP alerts can have an associated icon, like a stop sign or question mark. Alerts may even have an associated sound, although this depends on the implementation. MIDP alerts are very much the same concept as modal dialogs in windowing systems like MacOS and Windows. Figure 5-6 shows a typical Alert.

Figure 5-6: Alerts are similar to modal dialogs in a desktop windowing system.

Alerts are represented by instances of the javax.microedition.lcdui.Alert class, which offers the following constructors:

public Alert()
public Alert(String title, String alertText, Image alertImage, AlertType alertType)

Any or all of the parameters in the second constructor may be null. (Don't worry about the Image class right now; I'll discuss it in the next chapter in the section on Lists.)

By default, timed Alerts are created using a default timeout value; you can find out the default value by calling getDefaultTimeout(). To change the Alert's timeout, call setTimeout() with the timeout value in milliseconds. A special value, FOREVER, may be used to indicate that the Alert is modal.

You could create a simple timed Alert with the following code:

Alert alert = new Alert("Sorry", "I'm sorry, Dave...", null, null);

To explicitly set the timeout value to five seconds, you could do this:

alert.setTimeout(5000);

If, instead, you wanted a modal alert, you would use the special value FOREVER:

alert.setTimeout(Alert.FOREVER);

The MIDP implementation will automatically supply a way to dismiss a modal alert. Sun's reference implementation, for example, provides a Done command mapped to a soft button. MIDP 2.0 exposes this command as the static member DISMISS_COMMAND, allowing you to register your own command listener and explicitly recognize this command. You can add your own commands to an Alert using the usual addCommand() method. The first time you call addCommand(), the system's dismiss command is removed.

The default behavior for Alerts automatically advances to the next screen when the Alert is dismissed or times out. You can specify the next screen by passing it and the Alert to the two-argument setCurrent() method in Display. If you call the regular one-argument setCurrent() method, the previous screen is restored when the Alert is dismissed. Alert types serve as hints to the underlying MIDP implementation. The implementation may use the alert type to decide what kind of sound to play when the alert is shown. The AlertType class provides five types, accessed as static member variables: ALARM, CONFIRMATION, ERROR, INFO, and WARNING.

MIDP 2.0 adds an indicator to an Alert. By default, no indicator is present, but you can add one by passing a Gauge to Alert's setIndicator() method. (Gauge is presented in the next chapter in the section on Forms.) The indicator is handy for showing progress in a network connection or a long computation.

The following example, TwoAlerts, shows both types of alert. It features a main TextBox that is displayed when the MIDlet begins. Two commands, Go and About, provide access to the alerts. The Go command shows a timed alert that contains a message about a fictitious network error. The About command displays a modal alert that could contain copyright information. A third command, Exit, provides a way to exit the MIDlet. Keep in mind that all three commands may not fit on the screen; some of them may be accessible from a secondary menu.

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;

public class TwoAlerts
    extends MIDlet
    implements CommandListener {
  private Display mDisplay;

  private TextBox mTextBox;
  private Alert mTimedAlert;
  private Alert mModalAlert;

  private Command mAboutCommand, mGoCommand, mExitCommand;

  public TwoAlerts() {
    mAboutCommand = new Command("About", Command.SCREEN, 1);
    mGoCommand = new Command("Go", Command.SCREEN, 1);
    mExitCommand = new Command("Exit", Command.EXIT, 2);

    mTextBox = new TextBox("TwoAlerts", "", 32, TextField.ANY);
    mTextBox.addCommand(mAboutCommand);
    mTextBox.addCommand(mGoCommand);
    mTextBox.addCommand(mExitCommand);
    mTextBox.setCommandListener(this);

    mTimedAlert = new Alert("Network error",
        "A network error occurred. Please try again.",
        null,
        AlertType.INFO);
    mModalAlert = new Alert("About TwoAlerts",
          "TwoAlerts is a simple MIDlet that demonstrates the use of Alerts.",
          null,
          AlertType.INFO);
    mModalAlert.setTimeout(Alert.FOREVER);
  }

  public void startApp() {
    mDisplay = Display.getDisplay(this);

    mDisplay.setCurrent(mTextBox);
  }

  public void pauseApp() {
  }

  public void destroyApp(boolean unconditional) {}

  public void commandAction(Command c, Displayable s) {
    if (c == mAboutCommand)
      mDisplay.setCurrent(mModalAlert);
    else if (c == mGoCommand)
      mDisplay.setCurrent(mTimedAlert, mTextBox);
    else if (c == mExitCommand)
      notifyDestroyed();
  }
}

[ directory ]