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.

The layout policy is such that the items - strings and images - are filled by default. This means that appended items are placed on the same line with the previous item unless:

• the item does not fit on the line; then a new line is started
• the previous item was a string ending with a newline character
• the layout directives attached to the item specify non-default behavior

The items contained within a container object (an instance of either Form or Alert) may be edited using append, delete, insert, and set methods. An item may be placed within at most one container object. If the application attempts to place an item into a container, and the item is already owned by this or another container, IllegalStateException is thrown. The application must remove the item from its container before inserting it into the new container.

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 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.
String	getString() Gets the text string used in the Alert.
int	getTimeout() Gets the time this Alert will be shown.
AlertType	getType() Gets the type of the Alert.
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	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	setType(AlertType type) Sets the type of the Alert.

Methods inherited from class javax.microedition.lcdui.Screen

getTicker, getTitle, setTicker, setTitle

Methods inherited from class javax.microedition.lcdui.Displayable

isShown, removeCommand

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.

See Also:

Constant Field Values

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. The value 15 seconds is set as default.

Returns:

default timeout in milliseconds (15000)

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

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

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

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

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

See Also:

Command

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