/* * @(#)Alert.java	1.59 01/08/10 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information").  You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING * THIS SOFTWARE OR ITS DERIVATIVES. */package javax.microedition.lcdui;import com.sun.midp.lcdui.Resource;/** * <P>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. </P> * * <P>The intended use of Alert is to inform the user about errors and other * exceptional conditions.</P> * * <P>The application can set the alert time to be infinity with * <code> setTimeout(Alert.FOREVER)</code> * in which case the Alert is considered to be <em>modal</em> 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.</P> * * <P>If an application specifies an alert to be of a * timed variety <em>and</em> gives it too much content such that it must * scroll, * then it automatically becomes a modal alert.</P> * * <P> An alert may have an <code>AlertType</code> 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 {@link AlertType#playSound(javax.microedition.lcdui.Display) * AlertType.playSound()}. * * <P>Alerts do not accept application-defined commands. * </P> * * <p> 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. </p> * * @see AlertType */public class Alert extends Screen {    /**     * <P>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 screen.</P>     *     * <P>Value -2 is assigned to FOREVER.</P>     */    public final static int FOREVER = -2;        /**     * <p>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</p>     *     * <pre>     *    Alert(title, null, null, null)     * </pre>     *     * @param title the title string, or null     *      * @see #Alert(String, String, Image, AlertType)     */    public Alert(String title) {        this(title, null, null, null);    }    /**     * <p>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     * {@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. </p>     *      * @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     * @throws IllegalArgumentException if the image is mutable     */    public Alert(String title, String alertText,                 Image alertImage, AlertType alertType) {        super(title);        time = DEFAULT_TIMEOUT;        setImageImpl(alertImage);        setStringImpl(alertText);        this.type = alertType;        // in order to have an accurate alert time, the screen        // has to have an opportunity to lay itself out.	    doLayout();    }    /**     * <p>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.</p>     *     * @return default timeout in milliseconds, or FOREVER     */    public int getDefaultTimeout() {        synchronized (Display.LCDUILock) {            return (alertHeight > viewPortHeight) ? FOREVER : DEFAULT_TIMEOUT;        }    }    /**     * <p>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.</p>     *     * @return timeout in milliseconds, or FOREVER     * @see #setTimeout     */    public int getTimeout() {        synchronized (Display.LCDUILock) {            return (alertHeight > viewPortHeight) ? FOREVER : time;        }    }    /**     * <p>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.     * </p>     *      * @param time timeout in milliseconds, or FOREVER     * @throws IllegalArgumentException if time is not positive and is     * not FOREVER     * @see #getTimeout     */    public void setTimeout(int time) {        if (time <= 0 && time != FOREVER) {            throw new IllegalArgumentException();        }        synchronized (Display.LCDUILock) {            this.time = time;        }    }    /**     * 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     */    public AlertType getType() {        // SYNC NOTE: return of atomic value, no locking necessary        return type;    }    /**     * Sets the type of the Alert.     * The handling and behavior of specific AlertTypes is described in     * {@link AlertType}.     * @param type an AlertType, or <code>null</code> if the Alert has no     * specific type     * @see #getType     */    public void setType(AlertType type) {        synchronized (Display.LCDUILock) {            this.type = type;        }    }    /**     * Gets the text string used in the Alert.     * @return the Alert's text string, or null if there is no text     * @see #setString     */    public String getString() {        synchronized (Display.LCDUILock) {            return getStringImpl();        }    }    /**     * <p> Sets the text string used in the Alert.     * @param str the Alert's text string, or null if there is no text     * @see #getString     */    public void setString(String str) {        synchronized (Display.LCDUILock) {            setStringImpl(str);        }    }    /**     * Gets the Image used in the Alert.     * @return the Alert's image, or null if there is no image     * @see #setImage     */    public Image getImage() {        // SYNC NOTE: return of atomic value, no locking necessary        return alertImage;    }    /**     * <p> Sets the Image used in the Alert.     * @param img the Alert's image, or null if there is no image     * @throws IllegalArgumentException if img is mutable     * @see #getImage     */    public void setImage(Image img) {        synchronized (Display.LCDUILock) {            setImageImpl(img);        }    }    /**     * Commands are not allowed on Alerts, so this method will always throw     * IllegalStateException whenever it is called.     *