Alert

In MIDlets, Alert 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. On Nokia Asha software platform devices, the alert is displayed in full screen. The alert 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 on Nokia Asha (left) and Series 40 (right)

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 on non-touch and with the flick gesture on touch enabled devices. The graphic icon within the Alert does not scroll and it is always shown in the Alert. On Nokia Asha software platform devices however, the commands do not scroll and the graphic icon can be scrolled along with the alert’s title and body text.

For information about supported new line character combinations in Alert text, see section New line handling.

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. however, on full touch Nokia Asha and Series 40 software platform devices, the Command label is displayed along with the alert’s body text on the display.
On Nokia Asha software platform devices, an Alert can display up to three commands, excluding the Command for the Back key. These are the last three commands added to the Alert. The commands are shown reversed compared to their definition order, that is the last Command added to the Alert is displayed first.

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 the Nokia Developer Wiki.

Touch Interaction and scrollbar on touch enabled devices

A non-modal timed Alert is closed on touch down and released on the Alert.
If an Alert is modal and has at least one Command associated with it, only touching down and releasing the Command closes the Alert. This also applies to a modal timed Alert.

Alert supports a scrollbar

A scrollbar is displayed, when the content is larger than the visible area of the alert. The scrollbar is always displayed on Series 40 touch and type devices. On Nokia Asha or Series 40 full touch software platform devices, the scroll bar is automatically hidden upon inactivity and is brought back to the foreground when the user drags or flicks on the Alert. Dragging or flicking the content scrolls it.

More information

For more information about Alert see: