Programming Wireless Devices with the Java2 Platform

9.3 Alert

Alerts are Screens that can be used to inform the user about errors and other exceptional conditions. Alerts can also be used as short informational notes and reminders. For the presentation of longer information, other Screen classes such as Form should be used.

An Alert shows a message and an optional Image to the user. An Alert is either presented for a certain period of time, or it can be modal with a special user operation to dismiss (close) the Alert.

The time the Alert is presented can be controlled with the setTimeout method. If the timeout is not set by application, the Alert timeout is the default timeout determined by the device. The default value can be inspected using the getDefaultTimeout method.

The Alert is set to be modal if the application sets the alert time to be infinite with the method call setTimeout(Alert.FOREVER). A timed Alert is forced to be modal if the device cannot present the Alert contents without scrolling. In modal Alerts the device provides a feature that allows the user to dismiss the Alert, whereupon the next screen is displayed.

Timed Alerts can be used when the user does not need to be aware of the information presented and can safely ignore the Alert. Alerts without a timeout should be used when the user must be made aware of the information or condition.

When an Alert is dismissed either explicitly by the user or after a timeout, the current displayable is automatically changed to the next screen. When an Alert is displayed, the application can choose which Displayable is to be displayed after the Alert is complete. This is done by using a specialized setCurrent method of class Display:

public void setCurrent(Alert alert, Displayable nextDisplayable)

If the normal setCurrent(Displayable nextDisplayable) method is used, the display reverts to the current screen after an Alert exits.

The AlertType of an Alert can be set to indicate the nature of the information provided in the Alert. There are five AlertTypes; ALARM, CONFIRMATION, ERROR, INFO, and WARNING. ERROR and WARNING are used for error messages. WARNING should be used when the user has the possibility to prevent the error and ERROR when some non preventable error has already occurred. CONFIRMATION and INFO are used for more positive informational notes. CONFIRMATION is used when the user should confirm that some action has taken place. For example, after the user has selected some element from a settings List, a CONFIRMATION may be presented to the user to indicate that the setting has been changed. The INFO type is used for more generic positive informational notes. The ALARM type should be used when some notification is presented that interrupts the normal interaction in some other way. For example, a calendar application may use the ALARM type for notifying the user that a timed calendar event has been triggered.

The AlertType settings affect the presentation of the Alert. For example, if an application does not provide any image for the Alert, then the device implementation may present some default system icon based on the AlertType. For example, an exclamation icon might be used in an ERROR Alert. AlertTypes can also have system sounds associated with them so that the device can audibly alert the user. The presence and selection of sounds is device-dependent. The sound associated with the AlertType can be played anytime by calling the method AlertType.playSound.

An example of an Alert is shown below:

Alert alert = new Alert("Cinema",
               "Two tickets purchased",
               null,
               AlertType.CONFIRMATION);
alert.setTimeout(4000);
display.setCurrent(alert);

9.3.1 Commands in Alert

Commands added to an Alert make it easy to create query dialogs with a set of predefined user responses such as "OK" and "Cancel." When Commands are added to an Alert, the built-in dismiss operation is removed. Similarly, when a CommandListener is set, the automatic advance behavior is deactivated, and the application must take care to call setCurrent when Alert should be removed from the display.

An Alert that has two or more application-defined Commands is always modal. If there is only one Command in a timed Alert, then the Command is activated automatically when the timeout occurs.

The semantics of an AlertType are slightly different when an Alert is a dialog with multiple answers (Commands.) The alert types generally indicate some forthcoming situation rather than something that has already been happened. For example, ERROR or WARNING can indicate that something erroneous or a harmful situation may result when choosing some of the Commands in Alert; for example, when user data may be lost. CONFIRMATION type should be used in dialogs that indicate less destructive actions. ALARM type is used similarly, but mainly to notify the user of an event that has occurred. For example, the ALARM type might be used to "Snooze" or "Dismiss" an alarm clock application.

An example:

Alert alert = new Alert(null, null, null,
               AlertType.CONFIRMATION);
alert.addCommand(okCommand);
alert.addCommand(backCommand);
alert.setCommandListener(this);
String prompt = "Delete address?\n\n";
String detail = "john.doe@foo.bar";
alert.setString(prompt + detail);
display.setCurrent(alert);

9.3.2 Activity Indicator

An Alert may contain a non-interactive Gauge object that is used as an activity or progress indicator. This can be used for creating simple wait or progress dialogs when there is some background process occurring and the user has to wait for the operation to be completed. For example, an activity indicator might be used when an application is downloading a large amount of data from the network. The Gauge class is described more thoroughly in Section 10.7, "Gauge." There are, however, certain constraints for the Gauge object when it is used as activity indicator in an Alert. For example, the Gauge must be set to non-interactive mode, and there must not be any label or any item Commands in it. The constraints are documented in more detail in the MIDP Specification version 2.0.

Alert alert = new Alert("Cinema",
                        "Sending message",
                        null, null);
alert.setTimeout(4000);
Gauge indicator = new Gauge(null, false,
                    Gauge.INDEFINITE,
                    Gauge.CONTINUOUS_RUNNING);
alert.setIndicator(indicator);
display.setCurrent(alert);