MID Profile

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 (Strings) and images, and which handles events like other screens.

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.

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


Field Summary
static int FOREVER
          FOREVER indicates that an Alert is kept alive until user dismisses it.
 
Constructor Summary
Alert(String title)
          Constructs a new, empty Alert object with the given title.
 
Method Summary
 void addCommand(Command cmd)
          Commands are not allowed on Alerts, so this method will always throw IllegalStateException whenever it is called.
 int appendImage(Image img)
           Adds an item consisting of one Image to the form.
 int appendItem(ImageItem item)
          Adds an ImageItem to the Alert.
 int appendItem(StringItem item)
          Adds an StringItem to the Alert.
 int appendString(String str)
           Adds an item consisting of one String to the form.
 void deleteItem(int itemNum)
          Deletes the Item referenced by itemNum.
 int getDefaultTimeout()
          Get the default time the Alert is shown in milliseconds.
 Item getItemAt(int itemNum)
          Gets the item at given position.
 int getSize()
          Gets the number of items in the Alert.
 int getTimeout()
          Get the time the Alert is shown in milliseconds.
 void insertItem(int itemNum, ImageItem item)
          Inserts an Image into the Alert just prior to the item specified.
 void insertItem(int itemNum, StringItem item)
          Inserts a string into the Alert just prior to the item specified.
 void setItem(int itemNum, Item item)
          Sets the item referenced by itemNum to the specified item, replacing the previous item.
 void setListener(CommandListener l)
          Listeners are not allowed on Alerts, so this method will always throw IllegalStateException whenever it is called.
 void setTimeout(int time)
          Set the time the Alert is shown in milliseconds.
 
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 alive until user dismisses it. It is a parameter in setTimeout() to indicate that the alert is modal and an "ok" or "done" command will be associated with it.

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. The timeout value of this new alert is the same value that is returned by getDefaultTimeout().
Parameters:
title - the title string, or null
Method Detail

getDefaultTimeout

public int getDefaultTimeout()
Get the default time the Alert is shown in milliseconds. That is a value that is most suitable for the specific implementation.
Returns:
default time-out value of the Alert

getTimeout

public int getTimeout()
Get the time the Alert is shown in milliseconds.
Returns:
time-out value of the Alert

setTimeout

public void setTimeout(int time)
Set the time the Alert is shown in milliseconds. By default, i.e., if setTimeout is not called, the implementation uses the default time that is best mapping for particular device.
Parameters:
time - time in milliseconds. The Alert can be made modal by setting a special value FOREVER.
See Also:
getDefaultTimeout()

appendString

public int appendString(String str)

Adds an item consisting of one String to the form. The effect visible to the application is identical to

appendItem(new StringItem(null, str))

Parameters:
str - the text
Returns:
the assigned number of the Item
Throws:
NullPointerException - if str is null

appendImage

public int appendImage(Image img)

Adds an item consisting of one Image to the form. The effect visible to the application is identical to

appendItem(new ImageItem(null, img, ImageItem.LAYOUT_DEFAULT, null))

The image must be immutable, otherwise IllegalArgumentException is thrown. An immutable copy of a mutable image can be created using createImage(Image).

Parameters:
img - the image to be added
Returns:
the assigned number of the image
Throws:
IllegalArgumentException - if img is mutable
NullPointerException - if img is null
See Also:
Image

appendItem

public int appendItem(ImageItem item)
Adds an ImageItem to the Alert. Images are laid out in the same manner as strings, unless the layout directives of ImageItem specify otherwise. For layout control of the images, see ImageItem.

Parameters:
item - the ImageItem to be added.
Returns:
the number assigned to the new Item
Throws:
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

appendItem

public int appendItem(StringItem item)
Adds an StringItem to the Alert. Strings are filled so that current line is continued if possible. If the text width is greater that the remaining horizontal space on the current line, the implementation inserts a new line and appends the rest of the text. Whenever possible the implementation should avoid breaking words into two lines. Instead, occurrences of white space (space or tab) should be used as potential places for splitting the lines. Also, a newline character in the string causes starting of a new line.

Parameters:
item - the StringItem to be added.
Returns:
the number assigned to the new Item
Throws:
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

insertItem

public void insertItem(int itemNum,
                       ImageItem item)
Inserts an Image into the Alert just prior to the item specified. Item numbering starts at zero. In other respects the semantics are identical to appendItem.
Parameters:
itemNum - the location at which the new item is to be inserted
item - the image item to be added
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

insertItem

public void insertItem(int itemNum,
                       StringItem item)
Inserts a string into the Alert just prior to the item specified. Item numbering starts at zero. In other respects the semantics are identical to appendString.
Parameters:
itemNum - the number of the item. Indexing of the items is zero-based.
item - the string item to be added
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

deleteItem

public void deleteItem(int itemNum)
Deletes the Item referenced by itemNum. Item numbering starts at zero. It is legal to delete all items from a Alert.

Parameters:
itemNum - the number of the item to be deleted
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item

setItem

public void setItem(int itemNum,
                    Item item)
Sets the item referenced by itemNum to the specified item, replacing the previous item. The previous item is removed from the Alert. Item numbering starts at zero.

The result will be identical to

insertItem(n, item); deleteItem(n+1);

although the implementation may optimize the repainting and array element copying.

Parameters:
itemNum - the number of the item to be replaced
item - the new item
Throws:
ArrayIndexOutOfBoundsException - if itemNum specifies an invalid item
IllegalStateException - if the item is already owned by a container
NullPointerException - if item is null

getItemAt

public Item getItemAt(int itemNum)
Gets the item at given position. The first position is zero.
Parameters:
itemNum - the index of item
Returns:
the item at given position
Throws:
ArrayIndexOutOfBoundsException - if itemNum is less than zero or greater than or equal to size of the Alert.

getSize

public int getSize()
Gets the number of items in the Alert.
Returns:
number of items

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

setListener

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

MID Profile

Submit a comment or suggestion Version 0.9 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.