|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
|
+--javax.microedition.lcdui.Displayable
|
+--javax.microedition.lcdui.Screen
|
+--javax.microedition.lcdui.Alert
An alert is a screen that shows data to the user and waits for a
certain period of time before proceeding to the next
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 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.)
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
setIndicator(javax.microedition.lcdui.Gauge) method. The
Gauge object used for the
activity indicator must conform to all of the following restrictions:
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
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
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 setCommandListener(javax.microedition.lcdui.CommandListener) method. If
the application
removes its listener by passing null to the setCommandListener method,
the default listener is implicitly restored.
The Display.setCurrent(Alert, Displayable) method and the
Display.setCurrent(Displayable)
method (when called with an Alert) 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 Ticker
with Displayable.setTicker on an Alert, however it may not be displayed due
to implementation restrictions.
AlertType| Field Summary | ||
static Command |
DISMISS_COMMAND
A Command delivered to a listener to indicate that
the Alert has been
dismissed. |
|
static int |
FOREVER
FOREVER indicates that an Alert is kept
visible until the user
dismisses it. |
|
| Constructor Summary | ||
Alert(String title)
Constructs a new, empty Alert object with the given title. |
||
Alert(String title,
String alertText,
Image alertImage,
AlertType alertType)
Constructs a new Alert object with the given title, content string and image, and alert type. |
||
| Method Summary | ||
void |
addCommand(Command cmd)
Commands are not allowed on Alerts, so this method will always throw IllegalStateException whenever it is called. |
|
int |
getDefaultTimeout()
Gets the default time for showing an Alert. |
|
Image |
getImage()
Gets the Image used in the Alert. |
|
Gauge |
getIndicator()
Gets the activity indicator for this Alert. |
|
String |
getString()
Gets the text string used in the Alert. |
|
int |
getTimeout()
Gets the time this Alert will be shown. |
|
String |
getTitle()
Retrieve the title of the Alert |
|
AlertType |
getType()
Gets the type of the Alert. |
|
void |
removeCommand(Command cmd)
Similar to Displayable.removeCommand(javax.microedition.lcdui.Command), however when the
application removes the last command from an
Alert, DISMISS_COMMAND is implicitly
added. |
|
void |
setCommandListener(CommandListener l)
Listeners are not allowed on Alerts, so this method will always throw IllegalStateException whenever it is called. |
|
void |
setImage(Image img)
Sets the Image used in the Alert. |
|
void |
setIndicator(Gauge indicator)
Sets an activity indicator on this Alert. |
|
void |
setString(String str)
Sets the text string used in the Alert. |
|
void |
setTimeout(int time)
Set the time for which the Alert is to be shown. |
|
void |
setTitle(String title)
Set the title of the Alert |
|
void |
setType(AlertType type)
Sets the type of the Alert. |
|
| Methods inherited from class javax.microedition.lcdui.Displayable |
getHeight, getTicker, getWidth, isShown, setTicker, sizeChanged |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final Command DISMISS_COMMAND
Command delivered to a listener to indicate that
the Alert has been
dismissed. This Command is implicitly present an on
Alert whenever
there are no other Commands present. The field values of
DISMISS_COMMAND are as follows:
The label value visible to the application must be as specified
above. However, the implementation may display
DISMISS_COMMAND to the
user using an implementation-specific label.
Attempting to add or remove DISMISS_COMMAND
from an Alert has no
effect. However, DISMISS_COMMAND is treated as an
ordinary Command if
it is used with other Displayable types.
public static final int FOREVER
FOREVER indicates that an Alert is kept
visible until the user
dismisses it. It is used as a value for the parameter to
setTimeout()
to indicate that the alert is modal. Instead of waiting for a
specified period of time, a modal Alert will wait for the user to take
some explicit action, such as pressing a button, before proceeding to
the next screen.
Value -2 is assigned to FOREVER.
| Constructor Detail |
public Alert(String title)
Constructs a new, empty Alert object with the given title. If null is passed, the Alert will have no title. Calling this constructor is equivalent to calling
Alert(title, null, null, null)
title - the title string, or nullAlert(String, String, Image, AlertType)public Alert(String title, String alertText, Image alertImage, AlertType alertType)
Constructs a new Alert object with the given title, content
string and image, and alert type.
The layout of the contents is implementation dependent.
The timeout value of this new alert is the same value that is
returned by getDefaultTimeout().
If an image is provided it must be immutable.
The handling and behavior of specific AlertTypes is described in
AlertType. Null is allowed as the value of the alertType
parameter and indicates that the Alert is not to have a specific
alert type. DISMISS_COMMAND is the only
Command present on the new Alert. The
CommandListener associated with the new
Alert is the default listener. Its behavior is described
in more detail in the section Commands and
Listeners.
title - the title string, or null if there is no titlealertText - the string contents, or null if there is no stringalertImage - the image contents, or null if there is no imagealertType - the type of the Alert, or null if the Alert has no
specific typeIllegalArgumentException - if the image is mutable| Method Detail |
public void addCommand(Command cmd)
addCommand in class Displayablecmd - the CommandIllegalStateException - alwayspublic int getDefaultTimeout()
Gets the default time for showing an Alert. This is either a positive value, which indicates a time in milliseconds, or the special value FOREVER, which indicates that Alerts are modal by default. The value returned will vary across implementations and is presumably tailored to be suitable for each.
public Image getImage()
public Gauge getIndicator()
Alert.Alert's activity indicator,
or null if
there is nonesetIndicator(javax.microedition.lcdui.Gauge)public String getString()
public int getTimeout()
Gets the time this Alert will be shown. This is either a positive value, which indicates a time in milliseconds, or the special value FOREVER, which indicates that this Alert is modal.
public String getTitle()
getTitle in class Displayablepublic AlertType getType()
public void removeCommand(Command cmd)
Displayable.removeCommand(javax.microedition.lcdui.Command), however when the
application removes the last command from an
Alert, DISMISS_COMMAND is implicitly
added. Calling this method with DISMISS_COMMAND
as the parameter has no effect.removeCommand in class Displayablecmd - the command to be removedpublic void setCommandListener(CommandListener l)
setCommandListener in class Displayablel - the ListenerIllegalStateException - alwayspublic void setImage(Image img)
Sets the Image used in the Alert. The Image may be
mutable or immutable. If img is null,
specifies that this Alert has no image. If
img is mutable, the effect is as if a snapshot is taken
of img's contents immediately prior to the call to
setImage. This snapshot is used whenever the contents of
the Alert are to be displayed. If img is already the
Image of this Alert, the effect is as if a
new snapshot of img's contents is taken. Thus, after painting into a
mutable image contained by an Alert, the application can
call
alert.setImage(alert.getImage());
to refresh the Alert's snapshot of its Image.
If the Alert is visible on the display when its
contents are updated through a call to setImage, the
display will be updated with the new snapshot as soon as it is
feasible for the implementation to do so.
img - the Alert's image, or null if there is no imageIllegalArgumentException - if img is mutablepublic void setIndicator(Gauge indicator)
Alert. The
activity indicator is a
Gauge object. It must be in a restricted state in order for it
to be used as the activity indicator for an Alert.
The restrictions
are listed above. If the
Gauge object
violates any of these restrictions,
IllegalArgumentException is thrown.
If indicator is null, this removes any
activity indicator present on this Alert.
indicator - the activity indicator for this Alert,
or null if
there is to be noneIllegalArgumentException - if indicator does not
meet the restrictions for its use in an AlertgetIndicator()public void setString(String str)
Sets the text string used in the Alert.
If the Alert is visible on the display when its
contents are updated through a call to setString, the display will be
updated with the new contents as soon as it is feasible for the
implementation to do so.
str - the Alert's text string, or null if there is no textpublic void setTimeout(int time)
Set the time for which the Alert is to be shown. This must either be a positive time value in milliseconds, or the special value FOREVER.
time - timeout in milliseconds, or FOREVERIllegalArgumentException - if time is not positive and is
not FOREVERpublic void setTitle(String title)
setTitle in class Displayabletitle - the title string, or null if there is no titlepublic void setType(AlertType type)
AlertType.type - an AlertType, or null if the Alert has no
specific type
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.