display.java

j2me设计的界面包

/*
 * Copyright 2008 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */
package com.sun.lwuit;

import com.sun.lwuit.animations.Animation;
import com.sun.lwuit.animations.CommonTransitions;
import com.sun.lwuit.animations.Transition;
import com.sun.lwuit.geom.Dimension;
import java.util.Enumeration;
import java.util.Vector;

/**
 * Central class for the API that manages rendering/events and is used to place top
 * level components ({@link Form}) on the "display". Before any Form is shown the Developer must
 * invoke Display.init(Object m) in order to register the current MIDlet.
 * <p>This class handles the main thread for the toolkit referenced here on as the EDT 
 * (Event Dispatch Thread) similar to the Swing EDT. This thread encapsulates the platform
 * specific event delivery and painting semantics and enables threading features such as
 * animations etc...
 * <p>The EDT should not be blocked since paint operations and events would also be blocked 
 * in much the same way as they would be in other platforms. In order to serialize calls back
 * into the EDT use the methods {@link Display#callSerially} &amp; {@link Display#callSeriallyAndWait}.
 * <p>Notice that all LWUIT calls occur on the EDT (events, painting, animations etc...), LWUIT 
 * should normally be manipulated on the EDT as well (hence the {@link Display#callSerially} &amp; 
 * {@link Display#callSeriallyAndWait} methods). Theoretically it should be possible to manipulate
 * some LWUIT features from other threads but this can't be guaranteed to work for all use cases.
 * 
 * @author Chen Fishbein, Shai Almog
 */
public final class Display {
    /**
     * Indicates whether this is a touch device
     */
    private boolean touchScreen;
    
    /**
     * Light mode allows the UI to adapt and show less visual effects/lighter versions
     * of these visual effects to work properly on low end devices.
     */
    private boolean lightMode;
    
    /**
     * Game action for fire
     */
    public static final int GAME_FIRE = 8;

    /**
     * Game action for left key
     */
    public static final int GAME_LEFT = 2;

    /**
     * Game action for right key
     */
    public static final int GAME_RIGHT = 5;

    /**
     * Game action for UP key
     */
    public static final int GAME_UP = 1;

    /**
     * Game action for left key
     */
    public static final int GAME_DOWN = 6;
    
    /**
     * An attribute that encapsulates '#' int value.
     */
    public static final int KEY_POUND = '#';

    private static final Display INSTANCE = new Display();
    
    /**
     * On some devices getKeyCode returns numeric values for game actions,
     * this breaks the code since we filter these values. We pick unused 
     * negative values for game keys and assign them to game keys for getKeyCode.
     */
    private static int[] portableKeyCodes;
    private static int[] portableKeyCodeValues;
    
    private Form current;
    
    private Implementation implementation = new Implementation();
    
    /**
     * Contains the call serially pending elements
     */
    private Vector pendingSerialCalls = new Vector();
    
    /**
     * This is the instance of the EDT used internally to indicate whether
     * we are executing on the EDT or some arbitrary thread
     */ 
    private Thread edt; 

    /**
     * Contains animations that must be played in full by the EDT before anything further
     * may be processed. This is useful for transitions/intro's etc... that animate without
     * user interaction.
     */
    private Vector animationQueue;

    /**
     * Indicates whether the 3rd softbutton should be supported on this device
     */
    private boolean thirdSoftButton = false;
    
    private boolean editingText;

    /**
     * Ignore all calls to show occuring during edit, they are discarded immediately
     */
    public static final int SHOW_DURING_EDIT_IGNORE = 1;

    /**
     * If show is called while editing text in the native text box an exception is thrown
     */
    public static final int SHOW_DURING_EDIT_EXCEPTION = 2;
    
    /**
     * Allow show to occur during edit and discard all user input at this moment
     */
    public static final int SHOW_DURING_EDIT_ALLOW_DISCARD = 3;

    /**
     * Allow show to occur during edit and save all user input at this moment
     */
    public static final int SHOW_DURING_EDIT_ALLOW_SAVE = 4;

    /**
     * Show will update the current form to which the OK button of the text box
     * will return
     */
    public static final int SHOW_DURING_EDIT_SET_AS_NEXT = 5;
     
    private int showDuringEdit;
    
    static final Object lock = new Object();
    
    
    /** 
     * Private constructor to prevent instanciation
     */
    private Display() {
    }

    Vector getAnimationQueue() {
        return animationQueue;
    }
    
    /**
     * This is the Display initalization method.
     * This method must be called before any Form is shown
     * 
     * @param m the main running MIDlet
     */
    public static void init(Object m) {
        INSTANCE.implementation.init(m);
        
        int width = INSTANCE.getDisplayWidth();
        int height = INSTANCE.getDisplayHeight();
        int colors = INSTANCE.numColors();
        
        // if the resolution is very high and the amount of memory is very low while the device 
        // itself has many colors (requiring 32 bits per pixel) then we should concerve memory
        // by activating light mode.
        INSTANCE.lightMode = colors > 65536 && width * height * 30 > Runtime.getRuntime().totalMemory();
        
        // this can happen on some cases where an application was restarted etc...
        // generally its probably a bug but we can let it slide...
        if(INSTANCE.edt == null) {
            INSTANCE.touchScreen = INSTANCE.implementation.hasPointerEvents();
            // initialize the JWT EDT which from now on will take all responsibility
            // for the event delivery.
            INSTANCE.edt = new Thread(INSTANCE.implementation, "EDT");
            INSTANCE.edt.start();
        }
    }
    
    /**
     * Return the Display instance
     * 
     * @return the Display instance
     */
    public static Display getInstance(){
        return INSTANCE;
    }

    /**
     * Indicates the maximum frames the API will try to draw every second
     * by defult this is set to 10. The advantage of limiting
     * framerate is to allow the CPU to perform other tasks besides drawing.
     * Notice that when no change is occuring on the screen no frame is drawn and
     * so a high/low FPS will have no effect then.
     * 10FPS would be very reasonable for a business application.
     * 
     * @param rate the frame rate
     */
    public void setFramerate(int rate) {
        implementation.setFramerate(rate);
    }
    
    /**
     * Vibrates the device for the given length of time
     * 
     * @param duration length of time to vibrate
     */
    public void vibrate(int duration) {
        implementation.vibrate(duration);
    }
    
    /**
     * Flash the backlight of the device for the given length of time
     * 
     * @param duration length of time to flash the backlight
     */
    public void flashBacklight(int duration) {
        implementation.flashBacklight(duration);
    }

    void blockEvents(boolean block){
        implementation.blockEvents(block);
    }
    /**
     * Invoking the show() method of a form/dialog while the user is editing
     * text in the native text box can have several behaviors: SHOW_DURING_EDIT_IGNORE, 
     * SHOW_DURING_EDIT_EXCEPTION, SHOW_DURING_EDIT_ALLOW_DISCARD, 
     * SHOW_DURING_EDIT_ALLOW_SAVE, SHOW_DURING_EDIT_SET_AS_NEXT
     * 
     * @param showDuringEdit one of the following: SHOW_DURING_EDIT_IGNORE, 
     * SHOW_DURING_EDIT_EXCEPTION, SHOW_DURING_EDIT_ALLOW_DISCARD, 
     * SHOW_DURING_EDIT_ALLOW_SAVE, SHOW_DURING_EDIT_SET_AS_NEXT
     */
    public void setShowDuringEditBehavior(int showDuringEdit) {
        this.showDuringEdit = showDuringEdit;
    }

    /**
     * Returns the status of the show during edit flag
     * 
     * @return one of the following: SHOW_DURING_EDIT_IGNORE, 
     * SHOW_DURING_EDIT_EXCEPTION, SHOW_DURING_EDIT_ALLOW_DISCARD, 
     * SHOW_DURING_EDIT_ALLOW_SAVE, SHOW_DURING_EDIT_SET_AS_NEXT
     */
    public int getShowDuringEditBehavior() {
        return showDuringEdit;
    }

    /**
     * Indicates the maximum frames the API will try to draw every second
     * 
     * @return the frame rate
     */
    public int getFrameRate() {
        return implementation.getFrameRate();
    }
        
    /**
     * Returns true if we are currently in the event dispatch thread.
     * This is useful for generic code that can be used both with the
     * EDT and outside of it.
     *