display.java

用于移动设备上的java虚拟机源代码

     * foreground.  This method MUST perform no action
     * and return <CODE>false</CODE> if the
     * <code>Display</code> is in the background.
     *
     * <p>The device MAY limit or override the duration. For devices
     * that do not include a controllable backlight, calls to this
     * method return <CODE>false</CODE>.
     *
     * @param duration the number of milliseconds the backlight should be
     * flashed, or zero if the flashing should be stopped
     *
     * @return <CODE>true</CODE> if the backlight can be controlled
     *           by the application and this display is in the foreground,
     *          <CODE>false</CODE> otherwise
     *
     * @throws IllegalArgumentException if <code>duration</code> is negative
     *
     * @since MIDP 2.0
     */
    public boolean flashBacklight(int duration) {

        if (!hasForeground) {
            return false;
        }

        return deviceAccess.flashBacklight(duration);
    }
    
    /**
     * Requests operation of the device's vibrator.  The vibrator is
     * intended to be used to attract the user's attention or as a
     * special effect for games.  The return value indicates if the
     * vibrator can be controlled by the application.
     *
     * <p>This method switches on the vibrator for the requested
     * duration, or switches it off if the requested duration is zero.
     * If this method is called while the vibrator is still activated
     * from a previous call, the request is interpreted as setting a
     * new duration. It is not interpreted as adding additional time
     * to the original request. This method returns immediately; that
     * is, it must not block the caller while the vibrator is
     * running. </p>
     *
     * <p>Calls to this method are honored only if the
     * <code>Display</code> is in the foreground.  This method MUST
     * perform no action and return <CODE>false</CODE> if the
     * <code>Display</code> is in the background.</p>
     *
     * <p>The device MAY limit or override the duration.  For devices
     * that do not include a controllable vibrator, calls to this
     * method return <CODE>false</CODE>.</p>
     *
     * @param duration the number of milliseconds the vibrator should be run,
     * or zero if the vibrator should be turned off
     *
     * @return <CODE>true</CODE> if the vibrator can be controlled by the
     *           application and this display is in the foreground,
     *          <CODE>false</CODE> otherwise
     *
     * @throws IllegalArgumentException if <code>duration</code> is negative
     *
     * @since MIDP 2.0
     */
    public boolean vibrate(int duration) {

        if (!hasForeground) {
            return false;
        }

        if (duration < 0) {
            throw new IllegalArgumentException();
        }
        
        if (nVibrate(duration) <= 0) {
            return false;
        } else {
            return true;
        }

    }

    /**
     * Returns the best image width for a given image type.
     * The image type must be one of
     * {@link #LIST_ELEMENT},
     * {@link #CHOICE_GROUP_ELEMENT}, or
     * {@link #ALERT}.
     * 
     * @param imageType the image type
     * @return the best image width for the image type, may be zero if
     * there is no best size; must not be negative
     * @throws IllegalArgumentException if <code>imageType</code> is illegal
     * @since MIDP 2.0
     */
    public int getBestImageWidth(int imageType) {
        switch (imageType) {
        case LIST_ELEMENT:
        case CHOICE_GROUP_ELEMENT:
            return ChoiceGroup.PREFERRED_IMG_W;
        case ALERT:
            return Display.WIDTH;
        default:
            throw new IllegalArgumentException();
        }
    }

    /**
     * Returns the best image height for a given image type.
     * The image type must be one of
     * {@link #LIST_ELEMENT},
     * {@link #CHOICE_GROUP_ELEMENT}, or
     * {@link #ALERT}.
     * 
     * @param imageType the image type
     * @return the best image height for the image type, may be zero if
     * there is no best size; must not be negative
     * @throws IllegalArgumentException if <code>imageType</code> is illegal
     * @since MIDP 2.0
     */
    public int getBestImageHeight(int imageType) {
        switch (imageType) {
        case LIST_ELEMENT:
        case CHOICE_GROUP_ELEMENT:
            return ChoiceGroup.PREFERRED_IMG_H;
        case ALERT:
            // return max height ignoring title and ticker and
            // allow for 2 lines of Text to be visible without scrolling
            return Display.ADORNEDHEIGHT - 2 * Screen.CONTENT_HEIGHT;
        default:
            throw new IllegalArgumentException();
        }
    }


/*
 * ************* protected methods
 */

/*
 * ************* package private methods
 */

    /**
     * Set the current Displayable and notify the display manager if
     * the has current state has changed.
     *
     * @param nextDisplayable The next Displayable to display
     */
    void setCurrentImpl(Displayable nextDisplayable) {
        boolean previousWantsForeground = wantsForeground;

        /*
         * note: this method handles the setCurrent(null) then
         * setCurrent(getCurrent()) case
         */

        wantsForeground = nextDisplayable != null;

        if (wantsForeground) {
            if (nextDisplayable != current) {
                if (hasForeground) {
                    // If a call to setCurrent() is coming in while in a
                    // suspended state, notify the event handler to dismiss
                    // the system screen
                    if (paintSuspended) {
                        eventHandler.clearSystemScreen();
                        paintSuspended = false;
                    }

                    eventHandler.scheduleScreenChange(this, nextDisplayable);

                    /*
                     * have the foreground, no need to notify the display
                     * manager
                     */
                    return;
                }

                // set current before we notify the display manager
                current = nextDisplayable;
            }
        }

        if (wantsForeground != previousWantsForeground) {
            // only notify the display manager on a change
            displayManagerImpl.notifyWantsForeground(this.accessor,
                                                     wantsForeground);
        }
    }

    /**
     * Change the current screen to the given displayable.
     *
     * @param d The Displayable to make current
     */
    void screenChange(Displayable d) {
        synchronized (LCDUILock) {
            if (current == d && !paintSuspended) {
                return;
            } else if (paintSuspended) {
                // If we happen to be suspended, simply update our current
                // screen to be the new Displayable and return. When we are
                // resumed, registerNewCurrent() will be called with the
                // newly set screen
                current = d;
                return;
            }
        }

        // Its ok to ignore the foreground/paintSuspended state from here
        // on, the last thing registerNewCurrent() will do is try to do
        // a repaint(), which will not occur if the
        // foreground/paintSuspended status has changed in the meantime.
        registerNewCurrent(d, false);
    }

    /**
     * Called by Alert when a modal alert has exited.
     *
     * @param returnScreen The Displayable to return to after this
     *                     Alert is cleared.
     */
    void clearAlert(Displayable returnScreen) {
        eventHandler.scheduleScreenChange(this, returnScreen);
    }

    /**
     * play a sound.
     * @param t type of alert
     * @return true, if sound was played.
     */
    boolean playAlertSound(AlertType t) {

        if (!paintSuspended && hasForeground) {
            try {
                // SYNC NOTE: playAlertSound is a native method, no locking
                // necessary
                return playAlertSound(t.getType());
            } catch (Exception e) {}
        }

        return false;
    }

    /**
     * Schedule a Form invalidation based on the given Item.
     * The item may be null.
     *
     * @param item The Item which caused the invalidation
     */
    void invalidate(Item item) {
        eventHandler.scheduleInvalidate(item);
    }

    /**
     * Schedule the notificaton of an ItemStateListener due to
     * a change in the given item.
     *
     * @param item The Item which has changed
     */
    void itemStateChanged(Item item) {
        eventHandler.scheduleItemStateChanged(item);
    }

    /**
     * get the associated MIDlet from the current display.
     * @return MIDlet that is associated with the current Display.
     */
    MIDlet getMIDlet() {
        return midlet;
    }

    /**
     * Request a repaint for the given Displayable.  The rectangle to be
     * painted is in x,y,w,h.  If delay is greater than zero, the repaint
     * may be deferred until that interval (in milliseconds) has elapsed.
     *
     * If the given Displayable is not current, the request is ignored.
     * This is safe because whenever a Displayable becomes current, it gets
     * a full repaint anyway.
     *
     * The target Object is optional. It will be packaged along with the
     * repaint request and arrive later when the repaint is serviced in
     * the callPaint() routine - IF this paint request has not been
     * coalesced with other repaints.
     *
     * @param d displayable object to be drawn
     * @param x upper left corner x-coordinate
     * @param y upper left corner y-coordinate
     * @param w horizontal width
     * @param h vertical height
     * @param target an optional paint target
     */
    void repaintImpl(Displayable d, int x, int y, int w, int h,
                     Object target) {

        synchronized (LCDUILock) {
            if (paintSuspended || !hasForeground || d != current) {
                return;
            }
        }

        eventHandler.scheduleRepaint(x, y, w, h, target);
    }

    /**
     * Process any pending repaint requests immediately.
     *
     * @param d The Displayable which is requesting the repaint
     *          (Used to determine if the Displayable making the
     *           request is currently being shown)
     *
     * SYNC NOTE: this method performs its own locking of
     * LCDUILock.  Therefore, callers
     * must not hold any locks when they call this method.
     */
    void serviceRepaints(Displayable d) {

        synchronized (LCDUILock) {
            if (paintSuspended || !hasForeground || d != current) {
                return;
            }
        }

        eventHandler.serviceRepaints();
    }

    /**
     * Process the specified repaint request immediately.
     *
     * @param x1 The x origin of the paint bounds
     * @param y1 The y origin of the paint bounds
     * @param x2 The x coordinate of the lower right bounds
     * @param y2 The y coordinate of the lower right bounds
     * @param target The optional paint target
     *
     * SYNC NOTE: this method performs its own locking of
     * LCDUILock and calloutLock.  Therefore, callers
     * must not hold any locks when they call this method.
     */
    void repaint(int x1, int y1, int x2, int y2, Object target) {
        Displayable currentCopy = null;

        synchronized (LCDUILock) {
            if (paintSuspended || !hasForeground) {
                return;
            }
            currentCopy = current;
        }

        if (currentCopy == null) {
            return;