Displayable
. An alert can contain a text string and an image. The intended use of Alert
is to inform the user about errors and other exceptional conditions. The application can set the alert time to be infinity with setTimeout(Alert.FOREVER)
in which case the Alert
is considered to be modal and the implementation provide a feature that allows the user to "dismiss" the alert, whereupon the next Displayable
is displayed as if the timeout had expired immediately.
If an application specifies an alert to be of a timed variety and gives it too much content such that it must scroll, then it automatically becomes a modal alert.
An alert may have an AlertType
associated with it to provide an indication of the nature of the alert. The implementation may use this type to play an appropriate sound when the Alert
is presented to the user. See {@link AlertType#playSound(javax.microedition.lcdui.Display) AlertType.playSound()}.
An alert may contain an optional Image
. The Image
may be mutable or immutable. If the Image
is mutable, the effect is as if a snapshot of its contents is taken at the time the Alert
is constructed with this Image
and when setImage
is called with an Image
. This snapshot is used whenever the contents of the Alert
are to be displayed. Even if the application subsequently draws into the Image
, the snapshot is not modified until the next call to setImage
. The snapshot is not updated when the Alert
becomes current or becomes visible on the display. (This is because the application does not have control over exactly when Displayables
appear and disappear from the display.)
An alert may contain an optional {@link Gauge} object that is used as an activity or progress indicator. By default, an Alert
has no activity indicator; one may be set with the {@link #setIndicator} method.The Gauge
object used for the activity indicator must conform to all of the following restrictions:
Alert
or Form
);Commands
;ItemCommandListener
;null
;LAYOUT_DEFAULT
.It is an error for the application to attempt to use a Gauge
object that violates any of these restrictions. In addition, when the Gauge
object is being used as the indicator within an Alert
, the application is prevented from modifying any of these pieces of the Gauge's
state.
Like the other Displayable
classes, an Alert
can accept Commands
, which can be delivered to a CommandListener
set by the application. The Alert
class adds some special behavior for Commands
and listeners.
When it is created, an Alert
implicitly has the special Command
{@link #DISMISS_COMMAND} present on it. If the application adds any other Commands
to the Alert
, DISMISS_COMMAND
is implicitly removed. If the application removes all other Commands
, DISMISS_COMMAND
is implicitly restored. Attempts to add or remove DISMISS_COMMAND
explicitly are ignored. Thus, there is always at least one Command
present on an Alert
.
If there are two or more Commands
present on the Alert
, it is automatically turned into a modal Alert
, and the timeout value is always {@link #FOREVER}. The Alert
remains on the display until a Command
is invoked. If the Alert has one Command (whether it is DISMISS_COMMAND or it is one provided by the application), the Alert
may have the timed behavior as described above. When a timeout occurs, the effect is the same as if the user had invoked the Command
explicitly.
When it is created, an Alert
implicitly has a CommandListener
called the default listener associated with it. This listener may be replaced by an application-provided listener through use of the {@link #setCommandListener} method. If the application removes its listener bypassing null
to the setCommandListener
method, the default listener is implicitly restored.
The {@link Display#setCurrent(Alert,Displayable)} method and the {@link Display#setCurrent(Displayable)} method (when called with anAlert
) define special behavior for automatically advancing to another Displayable
after the Alert
is dismissed. This special behavior occurs only when the default listener is present on the Alert
at the time it is dismissed or when a command is invoked. If the user invokes a Command
and the default listener is present, the default listener ignores the Command
and implements the automatic-advance behavior.
If the application has set its own CommandListener
, the automatic-advance behavior is disabled. The listener code is responsible for advancing to another Displayable
. When the application has provided a listener, Commands
are invoked normally by passing them to the listener's commandAction
method. The Command
passed will be one of the Commands
present on the Alert
: either DISMISS_COMMAND
or one of the application-provided Commands
.
The application can restore the default listener by passing null
to the setCommandListener
method.
Note: An application may set a {@link Ticker Ticker}with {@link Displayable#setTicker Displayable.setTicker} on anAlert
, however it may not be displayed due to implementation restrictions.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|