alert.java

SUN官方的资料

     */
    public void setTimeout(int time) {
        if (time <= 0 && time != FOREVER) {
            throw new IllegalArgumentException();
        }

        synchronized (Display.LCDUILock) {
            this.time = time;
        }
    }

    /**
     * Gets the type of the <code>Alert</code>.
     * @return a reference to an instance of <code>AlertType</code>,
     * or <code>null</code>
     * if the <code>Alert</code>
     * 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 <code>Alert</code>.
     * The handling and behavior of specific <code>AlertTypes</code>
     * is described in
     * {@link AlertType}.
     * @param type an <code>AlertType</code>, or <code>null</code> if the
     * <code>Alert</code> has no
     * specific type
     * @see #getType
     */
    public void setType(AlertType type) {
        synchronized (Display.LCDUILock) {
            this.type = type;
        }
    }

    /**
     * Gets the text string used in the <code>Alert</code>.
     * @return the <code>Alert's</code> text string, or <code>null</code> 
     * if there is no text
     * @see #setString
     */
    public String getString() {
        // SYNC NOTE: no locking necessary
        return text;
    }

    /**
     * Sets the text string used in the <code>Alert</code>.
     *
     * <p>If the <code>Alert</code> is visible on the display when its
     * contents are updated
     * through a call to <code>setString</code>, the display will be
     * updated with the new
     * contents as soon as it is feasible for the implementation to do so.
     * </p>
     *
     * @param str the <code>Alert's</code> text string, or <code>null</code>
     * if there is no text
     * @see #getString
     */
    public void setString(String str) {
        synchronized (Display.LCDUILock) {
            text = str;
            layout();
            if (isShown()) {
                repaintContents();
            }
        }
    }

    /**
     * Gets the <code>Image</code> used in the <code>Alert</code>.
     * @return the <code>Alert's</code> image, or <code>null</code> 
     * if there is no image
     * @see #setImage
     */
    public Image getImage() {
        synchronized (Display.LCDUILock) {
            if (mutableImage != null) {
                return mutableImage;
            } else {
                return image;
            }
        }
    }

    /**
     * Sets the <code>Image</code> used in the <code>Alert</code>.
     * The <code>Image</code> may be mutable or
     * immutable.  If <code>img</code> is <code>null</code>, specifies
     * that this <code>Alert</code> has no image.
     * If <code>img</code> is mutable, the effect is as if a snapshot is taken
     * of <code>img's</code> contents immediately prior to the call to
     * <code>setImage</code>.  This
     * snapshot is used whenever the contents of the
     * <code>Alert</code> are to be
     * displayed.  If <code>img</code> is already the
     * <code>Image</code> of this <code>Alert</code>, the effect
     * is as if a new snapshot of img's contents is taken.  Thus, after
     * painting into a mutable image contained by an <code>Alert</code>, the
     * application can call
     *
     * <TABLE BORDER="2">
     * <TR>
     * <TD ROWSPAN="1" COLSPAN="1">
     *    <pre><code>
     *    alert.setImage(alert.getImage());    </code></pre>
     * </TD>
     * </TR>
     * </TABLE>
     * <p>to refresh the <code>Alert's</code> snapshot of its
     * <code>Image</code>.</p>
     *
     * <p>If the <code>Alert</code> is visible on the display when its
     * contents are updated
     * through a call to <code>setImage</code>, the display will be
     * updated with the new
     * snapshot as soon as it is feasible for the implementation to do so.
     * </p>
     *
     * @param img the <code>Alert's</code> image, or <code>null</code>
     * if there is no image
     * @see #getImage
     */
    public void setImage(Image img) {
        synchronized (Display.LCDUILock) {
            setImageImpl(img);
            layout();
            if (isShown()) {
                repaintContents();
            }
        }
    }

    /**
     * Sets an activity indicator on this <code>Alert</code>.  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 <code>Alert</code>.
     * The restrictions
     * are listed <a href="#indicator">above</a>.  If the
     * <code>Gauge</code> object
     * violates any of these restrictions,
     * <code>IllegalArgumentException</code> is thrown.
     *
     * <p>If <code>indicator</code> is <code>null</code>, this removes any
     * activity indicator present on this <code>Alert</code>.</p>
     *
     * @param indicator the activity indicator for this <code>Alert</code>,
     * or <code>null</code> if 
     * there is to be none
     *
     * @throws IllegalArgumentException if <code>indicator</code> does not
     * meet the restrictions for its use in an <code>Alert</code>
     * @see #getIndicator
     * @since MIDP 2.0
     */
    public void setIndicator(Gauge indicator) {
        synchronized (Display.LCDUILock) {
            if (indicator == null) {
                if (this.indicator != null) {
                    // The Alert no longer owns this Gauge
                    this.indicator.setOwner(null);
                }
            } else {
                if (!isConformantIndicator(indicator)) {
                    throw new IllegalArgumentException("Gauge in wrong state");
                }
                indicator.setOwner(this);
            }

            if (this.indicator != null) {
                this.indicator.setOwner(null);
            }

            this.indicator = indicator;
            layout();
            if (isShown()) {
                repaintContents();
            }
        }
    }

    /**
     * Gets the activity indicator for this <code>Alert</code>.
     * 
     * @return a reference to this <code>Alert's</code> activity indicator,
     * or <code>null</code> if 
     * there is none
     * @see #setIndicator
     * @since MIDP 2.0
     */
    public Gauge getIndicator() {
        // SYNC NOTE: no locking necessary
        return indicator;
    }

    /**
     * Similar to {@link Displayable#addCommand}, however when the
     * application first adds a command to an <code>Alert</code>,
     * {@link #DISMISS_COMMAND} is implicitly removed.  Calling this
     * method with <code>DISMISS_COMMAND</code> as the parameter has
     * no effect.
     *
     * @param cmd the command to be added
     *
     * @throws NullPointerException if cmd is <code>null</code>
     */
    public void addCommand(Command cmd) {
        if (cmd == null) {
            throw new NullPointerException();
        }

        if (cmd == DISMISS_COMMAND) {
            return;
        }

        synchronized (Display.LCDUILock) {
            super.addCommandImpl(cmd);
        }
    }

    /**
     * Similar to {@link Displayable#removeCommand}, however when the
     * application removes the last command from an
     * <code>Alert</code>, {@link #DISMISS_COMMAND} is implicitly
     * added.  Calling this method with <code>DISMISS_COMMAND</code>
     * as the parameter has no effect.
     *
     * @param cmd the command to be removed
     */
    public void removeCommand(Command cmd) {
        if (cmd == DISMISS_COMMAND) {
            return;
        }

        synchronized (Display.LCDUILock) {
            super.removeCommandImpl(cmd);
        }
    }

    /**
     * The same as {@link Displayable#setCommandListener} but with the 
     * following additional semantics.  If the listener parameter is
     * <code>null</code>, the <em>default listener</em> is restored.
     * See <a href="#commands">Commands and Listeners</a> for the definition 
     * of the behavior of the default listener.
     *
     * @param l the new listener, or <code>null</code>
     */
    public void setCommandListener(CommandListener l) {
        synchronized (Display.LCDUILock) {
            userCommandListener = l;
        }
    }

// *****************************************************
//  Package private methods
// *****************************************************

    /**
     * Special CommandListener instance to handle execution of
     * the default "OK" Command
     */
    CommandListener implicitListener = new CommandListener() {
        /**
         * Handle the execution of the given Command and Displayable.
         *
         * @param c The Command to execute
         * @param s The Displayable from which the Command originated
         */
        public void commandAction(Command c, Displayable s) {
            // SYNC NOTE: We are protected by the calloutLock obtained
            //  previously. (either in Display or the timeout task)
            //  We do not need to re-aquire the calloutLock when
            //  calling the application's command listener.
            if (userCommandListener != null) {
                // Application has set its own listener
                if (c == OK) {
                    c = DISMISS_COMMAND; // translate 'OK' to 'DISMISS_COMMAND'
                }
                userCommandListener.commandAction(c, s);
            } else {
                // Treat all commands as if they were 'DISMISS'
                synchronized (Display.LCDUILock) {
                    currentDisplay.clearAlert(returnScreen);
                }
            }

        }
    };

    /**
     * Notify this Alert that is being displayed on the
     * given Display and wether it needs to initialize its
     * highlight
     *
     * @param d The Display this Alert will be shown on
     */
    void callShowNotify(Display d) {
        super.callShowNotify(d);

        if (type != null) {
            d.playAlertSound(type);
        }

        layout();

        int timeout = getTimeout();
        if (timeout == FOREVER) {
            if (getCommandCount() == 0) {
                // Add implicit command
                super.addCommandImpl(OK);
            }
        } else {
            if (timeoutTimer == null) {
                timeoutTimer = new Timer();
            }
            timerTask = new timeoutTask(this);
            timeoutTimer.schedule(timerTask, timeout);
        }
        super.setCommandListener(implicitListener);
    }

    /**
     * Notify this Alert that it will no longer be displayed
     * on the given Display
     *
     * @param d The Display showing this Alert
     */
    void callHideNotify(Display d) {
        super.callHideNotify(d);
        super.removeCommandImpl(OK);
        super.setCommandListener(null);
        if (timerTask != null) {
            try {
                timerTask.cancel();
                timerTask = null;
            } catch (Throwable t) { }
        }
    }

    /**
     * Set the Image for this Alert.
     *
     * @param img The img to use for this Alert
     */
    void setImageImpl(Image img) {
        if (img != null && img.isMutable()) {
            this.image = Image.createImage(img);   // use immutable copy of img
            this.mutableImage = img;