File	Doc	Category	Size	Date	Package
Alert.java	API Doc	phoneME MR2 API (J2ME)	29770	Wed May 02 18:00:22 BST 2007	javax.microedition.lcdui

Alert

• java.lang.Object
  • Screen

Fields Summary
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 {@link #setTimeout(int) 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 Displayable. Value -2 is assigned to FOREVER.
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.
AlertType	type The type of this alert
String	text The layout object for the alert text string
Image	image The image of this alert
private Image	mutableImage A reference to the original, mutable Image passed to setImage(). This is only so getImage() can return the correct Image Object.
Gauge	indicator The activity indicator for this alert
int	time The timeout value of this alert
Displayable	returnScreen The screen which the display will return to when this Alert is completed
CommandListener	userCommandListener The application's command listener
AlertLF	alertLF The Alert look&feel object associated with this Alert
private CommandListener	implicitListener Special CommandListener instance to handle execution of the default "OK" Command

Constructors Summary
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) param title the title string, or null see #Alert(String, String, Image, AlertType) // ***************************************************** // Constructor(s) // ***************************************************** this(title, null, null, null);
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(). The Image provided may either be mutable or immutable. The handling and behavior of specific AlertTypes is described in {@link 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. param title the title string, or null if there is no title param alertText the string contents, or null if there is no string param alertImage the image contents, or null if there is no image param alertType the type of the Alert, or null if the Alert has no specific type super(title); synchronized (Display.LCDUILock) { this.text = alertText; this.type = alertType; setImageImpl(alertImage); displayableLF = alertLF = LFFactory.getFactory().getAlertLF(this); this.time = alertLF.lGetDefaultTimeout(); // Call addCommandImpl to avoid notification to AlertLF // cause we know this Alert is not yet visible addCommandImpl(alertLF.lGetDismissCommand()); // Note that we have to call super.setCommandListener since // this.setCommandListener will set application's command // listener super.setCommandListener(implicitListener); }

Methods Summary
public void	addCommand(Command cmd) Similar to {@link Displayable#addCommand}, however when the application first adds a command to an Alert, {@link #DISMISS_COMMAND} is implicitly removed. Calling this method with DISMISS_COMMAND as the parameter has no effect. param cmd the command to be added throws NullPointerException if cmd is null if (cmd == null) { throw new NullPointerException(); } if (cmd == DISMISS_COMMAND) { return; } synchronized (Display.LCDUILock) { Command dismissCmd = alertLF.lGetDismissCommand(); if (commands[0] == dismissCmd) { super.removeCommand(dismissCmd); } super.addCommand(cmd); }
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 {@link #FOREVER 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. return default timeout in milliseconds, or FOREVER synchronized (Display.LCDUILock) { return alertLF.lGetDefaultTimeout(); }
public Image	getImage() Gets the Image used in the Alert. return the Alert's image, or null if there is no image see #setImage synchronized (Display.LCDUILock) { if (mutableImage != null) { return mutableImage; } else { return image; } }
public Gauge	getIndicator() Gets the activity indicator for this Alert. return a reference to this Alert's activity indicator, or null if there is none see #setIndicator // SYNC NOTE: no locking necessary return indicator;
Displayable	getReturnScreen() Get the screen that the display should return to when this Alert is dismissed. return The Displayable to display when this Alert is completed return returnScreen;
public java.lang.String	getString() Gets the text string used in the Alert. return the Alert's text string, or null if there is no text see #setString // SYNC NOTE: no locking necessary return text;
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. This value is not necessarily the same value that might have been set by the application in a call to {@link #setTimeout}. In particular, if the Alert is made modal because its contents is large enough to scroll, the value returned by getTimeout will be FOREVER. return timeout in milliseconds, or FOREVER see #setTimeout synchronized (Display.LCDUILock) { if (alertLF.lIsModal()) { return FOREVER; } else { return time; } }
public AlertType	getType() Gets the type of the Alert. return a reference to an instance of AlertType, or null if the Alert has no specific type see #setType // SYNC NOTE: return of atomic value, no locking necessary return type;
private boolean	isConformantIndicator(Gauge ind) Verify the activity indicator is conformant with the spec requirements for addition to an Alert. param ind The indicator to be verified return boolean True if the gauge is conformant; false otherwise return ((ind.interactive == false) && (ind.owner == null) && (ind.numCommands == 0) && (ind.commandListener == null) && (ind.label == null) && (ind.layout == Item.LAYOUT_DEFAULT) && (ind.lockedWidth == -1) && (ind.lockedHeight == -1));
void	lDismiss() Dismisses this alert. Display dpy = alertLF.lGetCurrentDisplay(); if (dpy != null && returnScreen != null) { dpy.clearAlert(this, returnScreen); }
public void	removeCommand(Command cmd) Similar to {@link Displayable#removeCommand}, however when the application removes the last command from an Alert, {@link #DISMISS_COMMAND} is implicitly added. Calling this method with DISMISS_COMMAND as the parameter has no effect. param cmd the command to be removed if (cmd == DISMISS_COMMAND) { return; } synchronized (Display.LCDUILock) { super.removeCommand(cmd); if (numCommands == 0) { super.addCommand(alertLF.lGetDismissCommand()); } }
public void	setCommandListener(CommandListener l) The same as {@link Displayable#setCommandListener} but with the following additional semantics. If the listener parameter is null, the default listener is restored. See Commands and Listeners for the definition of the behavior of the default listener. param l the new listener, or null synchronized (Display.LCDUILock) { userCommandListener = l; }
public 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. param img the Alert's image, or null if there is no image see #getImage synchronized (Display.LCDUILock) { Image oldImg = image; if (setImageImpl(img)) { // Always pass the immutable image snapshot as new image alertLF.lSetImage(oldImg, image); } }
private boolean	setImageImpl(Image img) Set the Image for this Alert. param img The img to use for this Alert return true if look&feel object has to be notified of an image change if (img != null && img.isMutable()) { this.image = Image.createImage(img); // use immutable copy of img this.mutableImage = img; } else { if (image == img) { return false; } this.image = img; this.mutableImage = null; // Make sure to clear mutableImage } return true;
public void	setIndicator(Gauge indicator) Sets an activity indicator on this Alert. The activity indicator is a {@link 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. param 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 see #getIndicator synchronized (Display.LCDUILock) { // do nothing if indicator is the same // that includes both indicators (old and new) being null if (this.indicator == indicator) { return; } Gauge oldIndicator = this.indicator; if (indicator == null) { // The Alert no longer owns this Gauge; // We do not need to check if this.indicator != null // since we already returned if they are both null oldIndicator.lSetOwner(null); } else { if (!isConformantIndicator(indicator)) { throw new IllegalArgumentException("Gauge in wrong state"); } indicator.lSetOwner(this); // if old indicator is not null // it is no longer is owned by this alert if (oldIndicator != null) { oldIndicator.lSetOwner(null); } } this.indicator = indicator; alertLF.lSetIndicator(oldIndicator, indicator); }
void	setReturnScreen(Displayable d) Set the screen that the display should return to when this Alert is dismissed. param d The Displayable to display when this Alert is completed this.returnScreen = d;
public void	setString(java.lang.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. param str the Alert's text string, or null if there is no text see #getString synchronized (Display.LCDUILock) { if (str == text || (str != null && str.equals(text))) { return; } String oldStr = text; text = str; alertLF.lSetString(oldStr, str); }
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. param time timeout in milliseconds, or FOREVER throws IllegalArgumentException if time is not positive and is not FOREVER see #getTimeout if (time <= 0 && time != FOREVER) { throw new IllegalArgumentException(); } synchronized (Display.LCDUILock) { this.time = time; alertLF.lSetTimeout(time); }
public void	setType(AlertType type) Sets the type of the Alert. The handling and behavior of specific AlertTypes is described in {@link AlertType}. param type an AlertType, or null if the Alert has no specific type see #getType synchronized (Display.LCDUILock) { if (this.type != type) { this.type = type; alertLF.lSetType(type); } }
void	uNotifyTimeout() LF notifies that the Alert is dismissed due to timeout, instead of user action. Commandlistener will be notified with the default Command. try { synchronized (Display.calloutLock) { listener.commandAction(commands[0], this); } } catch (Throwable thr) { Display.handleThrowable(thr); }