javax.microedition.lcdui
Class Alert

java.lang.Object
  |
  +--javax.microedition.lcdui.Displayable
        |
        +--javax.microedition.lcdui.Screen
              |
              +--javax.microedition.lcdui.Alert

public class Alert
extends Screen

An alert is a screen that shows data to the user and waits for a certain period of time before proceeding to the next screen. An alert is an ordinary screen that can contain text (String) and image, and which handles events like other screens.

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 screen 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().

Alerts do not accept application-defined commands.

If the Alert is visible on the display when changes to its contents are requested by the application, the changes take place automatically. That is, applications need not take any special action to refresh a Alert's display after its contents have been modified.

See Also:
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()
          Gets the title of the Screen.
 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)
          Sets the title of the Screen.
 void setType(AlertType type)
          Sets the type of the Alert.
 
Methods inherited from class javax.microedition.lcdui.Screen
getTicker, setTicker
 
Methods inherited from class javax.microedition.lcdui.Displayable
getHeight, getWidth, isShown, sizeChanged
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FOREVER

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.


DISMISS_COMMAND

public static final Command DISMISS_COMMAND
A 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:
  • label = "" (an empty string)
  • type = Command.OK
  • priority = 0

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.

Since:
MIDP 2.0
Constructor Detail

Alert

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)
 
Parameters:
title - the title string, or null
See Also:
Alert(String, String, Image, AlertType)

Alert

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.

Parameters:
title - the title string, or null if there is no title
alertText - the string contents, or null if there is no string
alertImage - the image contents, or null if there is no image
alertType - the type of the Alert, or null if the Alert has no specific type
Throws:
IllegalArgumentException - if the image is mutable
Method Detail

getDefaultTimeout

public 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.

Returns:
default timeout in milliseconds, or FOREVER

getTimeout

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.

Returns:
timeout in milliseconds, or FOREVER

setTimeout

public 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.

Parameters:
time - timeout in milliseconds, or FOREVER
Throws:
IllegalArgumentException - if time is not positive and is not FOREVER
Since:
JDE 4.0.2

getType

public AlertType getType()
Gets the type of the Alert.
Returns:
a reference to an instance of AlertType, or null if the Alert has no specific type

setType

public void setType(AlertType type)
Sets the type of the Alert. The handling and behavior of specific AlertTypes is described in AlertType.
Parameters:
type - an AlertType, or null if the Alert has no specific type
Since:
JDE 4.0.2

getString

public String getString()
Gets the text string used in the Alert.
Returns:
the Alert's text string, or null if there is no text

setString

public void setString(String str)

Sets the text string used in the Alert.

Parameters:
str - the Alert's text string, or null if there is no text
Since:
JDE 4.0.2

getImage

public Image getImage()
Gets the Image used in the Alert.
Returns:
the Alert's image, or null if there is no image

setImage

public void setImage(Image img)

Sets the Image used in the Alert.

Parameters:
img - the Alert's image, or null if there is no image
Throws:
IllegalArgumentException - if img is mutable
Since:
JDE 4.0.2

setIndicator

public void setIndicator(Gauge indicator)
Sets an activity indicator on this 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.

Parameters:
indicator - the activity indicator for this Alert, or null if there is to be none
Throws:
IllegalArgumentException - if indicator does not meet the restrictions for its use in an Alert
Since:
MIDP 2.0
See Also:
getIndicator()

getIndicator

public Gauge getIndicator()
Gets the activity indicator for this Alert.
Returns:
a reference to this Alert's activity indicator, or null if there is none
Since:
MIDP 2.0
See Also:
setIndicator(javax.microedition.lcdui.Gauge)

addCommand

public void addCommand(Command cmd)
Commands are not allowed on Alerts, so this method will always throw IllegalStateException whenever it is called.
Overrides:
addCommand in class Displayable
Parameters:
cmd - the Command
Throws:
IllegalStateException - always
Since:
JDE 4.0.2

removeCommand

public 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. Calling this method with DISMISS_COMMAND as the parameter has no effect.
Overrides:
removeCommand in class Displayable
Parameters:
cmd - the command to be removed
Since:
JDE 4.0.2

setCommandListener

public void setCommandListener(CommandListener l)
Listeners are not allowed on Alerts, so this method will always throw IllegalStateException whenever it is called.
Overrides:
setCommandListener in class Displayable
Parameters:
l - the Listener
Throws:
IllegalStateException - always
Since:
JDE 4.0.2

getTitle

public String getTitle()
Description copied from class: Screen
Gets the title of the Screen. Returns null if there is no title.
Overrides:
getTitle in class Screen
Following copied from class: javax.microedition.lcdui.Displayable
Returns:
the title of the instance, or null if no title
See Also:
Displayable.setTitle(java.lang.String)

setTitle

public void setTitle(String title)
Description copied from class: Screen
Sets the title of the Screen. If null is given, removes the title.

If the Screen is physically visible, the visible effect should take place no later than immediately after the callback or startApp returns back to the implementation.

Overrides:
setTitle in class Screen
Since:
JDE 4.0.2


Copyright 1999-2004 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.