Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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, String 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.

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, String, AlertType)`

### Alert

    public Alert(String title,
                 String alertText,
                 String 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

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

### 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

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 0.95 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.