Alert

In MIDlets, Alerts are used to notify the user of errors, exceptions, or otherwise important events by showing a popup window on top of the active MIDlet. Technically, Alert is a Screen that displays data either for a specified time period or until the user dismisses the prompt. The duration of the Alert can be defined with the setTimeout() method. If Alert.FOREVER is used, the Alert is modal. Otherwise the Alert is timed. You can query the duration with the getTimeout() method.

Alert is displayed in a popup window on top of the previously displayed screen, which remains dimmed in the background. The popup window consists of the following parts:

Title is an optional heading for the Alert. It is situated on top of the dialog.
Body contains the alert message. The body text can be left empty.
Icon is an optional graphic placed on the right side of the dialog. If this is not set, a default graphic is used.
Progress bar is an optional Gauge object shown at the bottom of the content area.

You can map Commands to Alerts.

Figure: Timed Alert using the AlertType.INFO property

Source code for the example:

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

public class ExampleAlert extends MIDlet {

    Display display = Display.getDisplay(this);

    public void startApp() {
        // Alert(title, text, icon, AlertType)
        Alert alert = new Alert("Info", "This is an alert for informative purposes", null, AlertType.INFO);
        display.setCurrent(alert);
    }

    public void pauseApp() {}

    public void destroyApp(boolean unconditional) {}

}

Note: The java.lang.OutOfMemoryError exception is thrown when there is not enough memory for allocating the string which is used for the content or label of an Alert. This generally happens when the MIDlet specifies a very large string.

Note the following when using Alerts:

Alerts are either modal or non-modal (timed). The timer for a non-modal Alert is only started when the Alert is brought to the foreground, which can happen some time after the MIDlet has made the request to display the Alert. If a non-modal Alert is interrupted by a system application, the timer is restarted when the MIDlet is returned to the foreground.
If the Alert contents requires scrolling, the Alert becomes modal.
If the AlertType is changed with the setType() method after the Alert object has been created, it does not affect the timeout.
If the text content of a modal Alert is bigger than what can be visible at one time, the text can be scrolled with the Arrow Up and Arrow Down keys. The graphic icon within the Alert does not scroll and it is always shown in the Alert.

Default Alert properties

The default Alert text, icon, tone, and timeout length shown in the table below are used when the corresponding attribute is not explicitly set. Their presentation is based on the AlertType that is set for the Alert.

Note: If you do not define the Alert text, the default text is shown. If you want to use the Alert without any visible text content, use setString(" ").

**Table:** Alert properties based on AlertType
AlertType	Default text (in English locale)	Default icon	Default tone	Default timeout length
`AlertType.ERROR`	Error	Error	Error tone	3 seconds
`AlertType.WARNING`	Warning	Warning	Warning tone	3 seconds
`AlertType.INFO`	Information	Info	Confirmation tone	3 seconds
`AlertType.CONFIRMATION`	OK	Confirmation	Confirmation tone	1,5 seconds
`AlertType.ALARM`	Alarm	Alarm	SMS alert tone	3 seconds
`AlertType` is `null`	Alert	No icon or image is presented. Space is made available for `Alert` text.	No tone	3 seconds

Using Command with Alert

If there is a CommandListener set to an Alert, then that listener is always called when Command activation happens regardless of whether there is a DISMISS_COMMAND or application settable Commands present and whether the Alert is timed or modal.

On a timed Alert there can only be one Command, which is either the DISMISS_COMMAND or an application set Command.

If the setCommandListener has not been called there is so called "default listener" used in the Alert. The behavior of "default listener" is as follows:

When the listener is called the listener will automatically change the current Displayable to either the previous Displayable or to a specified Displayable.
The previous Displayable is made current if the Alert was made current with Display's setCurrent(Displayable nextDisplayable) method.
The specified Displayable is made current if the MIDlet used setCurrent(Alert alert, Displayable nextDisplayable) method.

If the setCommandListener has been called, that listener is always in use even when an Alert is timed or the DISMISS_COMMAND is in use. It is up to the application to do the Displayable change when the listener is activated.

The number of application settable Commands has the following effect on an Alert:

If no application settable Commands are present on the Alert, the default DISMISS_COMMAND is used.
If there are one or more Commands set by an application then the DISMISS_COMMAND is replaced.
If there is only one Command and the Alert is modal then the one Command is visible normally as a softkey and the Command is activated only when the user selects it.
If there are two or more Commands set by an application then the Alert becomes automatically modal even if it is set as a timed Alert. A longer text, which requires scrolling, also forces a timed Alert to become modal.
On a timed Alert, the label of the Command is not visible in the device display. The Command is either implicitly activated (the set listener or default listener is notified) when the timer expires or explicitly activated if the user presses some other key defined to dismiss a timed Alert.

Alert with Ticker

An Alert screen can dynamically have a Ticker attached/detached to it, but the ticker is not displayed when the MIDlet is running in full-screen Canvas mode. In situations where an Alert with a ticker is set to be displayed on top of a full-screen Canvas, the background Canvas is changed to normal mode and then the Alert with the ticker is displayed on top of it. After the Alert is dismissed, the background is again restored to full-screen Canvas mode.

For information on Alert implementation in Touch UI -enabled devices, see section Displayables and commands.

For an example on using Alert, see article Using Alerts in Java ME in Forum Nokia.