alert.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)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.
     *