form.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.geom.Rectangle;
import com.sun.lwuit.geom.Dimension;
import com.sun.lwuit.plaf.Style;
import com.sun.lwuit.animations.Transition;
import com.sun.lwuit.events.ActionEvent;
import com.sun.lwuit.events.ActionListener;
import com.sun.lwuit.list.ListCellRenderer;
import com.sun.lwuit.layouts.BorderLayout;
import com.sun.lwuit.layouts.FlowLayout;
import com.sun.lwuit.layouts.GridLayout;
import com.sun.lwuit.layouts.Layout;
import com.sun.lwuit.plaf.LookAndFeel;
import com.sun.lwuit.plaf.UIManager;
import java.util.Hashtable;
import java.util.Vector;

/**
 * Top level component that serves as the root for the UI, this {@link Container}
 * handles the menus and title while placing content between them. By default a 
 * forms central content (the content pane) is scrollable.
 *
 * Form contains Title bar, MenuBar and a ContentPane.
 * Calling to addComponent on the Form is delegated to the contenPane.addComponent
 * 
 * *<pre>
 *
 *       **************************
 *       *         Title          *
 *       **************************
 *       *                        *
 *       *                        *
 *       *      ContentPane       *
 *       *                        *
 *       *                        *
 *       **************************
 *       *         MenuBar        *
 *       **************************
 *</pre> 
 * @author Chen Fishbein
 */
public class Form extends Container {

    private Painter glassPane;
    private Container contentPane = new Container(new FlowLayout());
    private Label title = new Label("", "Title");
    private MenuBar menuBar = new MenuBar();
    private Popup current;
    private Command selectCommand;
    private Command defaultCommand;
    /**
     * Indicates the command that is defined as the back commnand out of this form.
     * A back command can be used both to map to a hardware button (e.g. on the Sony Ericsson devices)
     * and by elements such as transitions etc. to change the behavior based on 
     * direction (e.g. slide to the left to enter screen and slide to the right to exit with back).
     */
    private Command backCommand;
    /**
     * Indicates the command that is defined as the clear commnand out of this form similar
     * in spirit to the back command
     */
    private Command clearCommand;
    /**
     * Contains a list of components that would like to animate their state
     */
    private Vector animatableComponents;
    /**
     * This member holds the left soft key value
     */
    static int leftSK = -6;
    /**
     * This member holds the right soft key value
     */
    static int rightSK = -7;
    /**
     * This member holds the 2nd right soft key value
     * this is used for different BB devices
     */
    static int rightSK2 = -7;
    /**
     * This member holds the back command key value
     */
    static int backSK = -11;
    /**
     * This member holds the clear command key value
     */
    static int clearSK = -8;
    //private FormSwitcher formSwitcher;
    private Component lastFocused;
    private Component focused;
    private Component focusCycleRoot;
    private Vector mediaComponents;
    /**
     * This member allows us to define an animation that will draw the transition for
     * entering this form. A transition is an animation that would occur when 
     * switching from one form to another.
     */
    private Transition transitionInAnimator;
    /**
     * This member allows us to define a an animation that will draw the transition for
     * exiting this form. A transition is an animation that would occur when 
     * switching from one form to another.
     */
    private Transition transitionOutAnimator;
    /**
     * a listener that is invoked when a command is clicked allowing multiple commands
     * to be handled by a single block
     */
    private ActionListener commandListener;
    /**
     * Relevant for modal forms where the previous form should be rendered underneath
     */
    private Form previousForm;
    /**
     * Indicates that this form should be tinted when painted
     */
    private boolean tint;
    /**
     * Default color for the screen tint when a dialog or a menu is shown
     */
    private int tintColor;
    /**
     * Allows us to cache the next focus component ordered from top to down, this
     * vector is guaranteed to have all focusable children in it.
     */
    private Vector focusDownSequence;
    /**
     * Allows us to cache the next focus component ordered from left to right, this
     * vector is guaranteed to have all focusable children in it.
     */
    private Vector focusRightSequence;
    /**
     * Listeners for key release events 
     */
    private Hashtable keyListeners;
    /**
     * Listeners for game key release events 
     */
    private Hashtable gameKeyListeners;

    /**
     * Default constructor creates a simple form
     */
    public Form() {
        super(new BorderLayout());

        // forms/dialogs are not visible by default
        setVisible(false);

        setWidth(Display.getInstance().getDisplayWidth());
        setHeight(Display.getInstance().getDisplayHeight());
        setPreferredSize(new Dimension(Display.getInstance().getDisplayWidth(),
                Display.getInstance().getDisplayHeight()));

        super.addComponent(BorderLayout.NORTH, title);
        super.addComponent(BorderLayout.CENTER, contentPane);
        super.addComponent(BorderLayout.SOUTH, menuBar);
        contentPane.setScrollableY(true);
        focusCycleRoot = contentPane;
        LookAndFeel laf = UIManager.getInstance().getLookAndFeel();
        initLaf(laf);
        tintColor = laf.getDefaultFormTintColor();

        // hardcoded, anything else is just pointless...
        getStyle().setBgTransparency(0xFF);
    }

    /**
     * Sets the style of the menu bar programmatically
     * 
     * @param s new style
     * @deprecated use setSoftButtonStyle instead
     */
    public void setMenuStyle(Style s) {
        menuBar.setStyle(s);
    }

    /**
     * Sets the style of the menu bar programmatically
     * 
     * @param s new style
     */
    public void setSoftButtonStyle(Style s) {
        menuBar.setStyle(s);
    }

    /**
     * Retrieves the style of the menu bar programmatically
     */
    public Style getSoftButtonStyle() {
        return menuBar.getStyle();
    }

    /**
     * This method is only invoked when the underlying canvas for the form is hidden
     * this method isn't called for form based events and is generally usable for
     * suspend/resume based behavior
     */
    protected void hideNotify() {
    }

    /**
     * This method is only invoked when the underlying canvas for the form is shown
     * this method isn't called for form based events and is generally usable for
     * suspend/resume based behavior
     */
    protected void showNotify() {
    }

    /**
     * This method is only invoked when the underlying canvas for the form gets
     * a size changed event.
     * This method will trigger a relayout of the Form.
     * This method will get the callback only if this Form is the Current Form
     * @param w the new width of the Form
     * @param h the new height of the Form
     */
    protected void sizeChanged(int w, int h) {
        setSize(new Dimension(w, h));
        setShouldCalcPreferredSize(true);
        doLayout();
        repaint();
    }

    /**
     * Allows a developer that doesn't derive from the form to draw on top of the 
     * form regardless of underlying changes or animations. This is useful for
     * watermarks or special effects (such as tinting) it is also useful for generic
     * drawing of validation errors etc... A glass pane is generally 
     * transparent or translucent and allows the the UI bellow to be seen.
     * 
     * @param glassPane a new glass pane to install. It is generally recommended to
     * use a painter chain if more than one painter is required.
     */
    public void setGlassPane(Painter glassPane) {
        this.glassPane = glassPane;
        repaint();
    }

    /**
     * Allows a developer that doesn't derive from the form to draw on top of the 
     * form regardless of underlying changes or animations. This is useful for
     * watermarks or special effects (such as tinting) it is also useful for generic
     * drawing of validation errors etc... A glass pane is generally 
     * transparent or translucent and allows the the UI bellow to be seen.
     * 
     * @return the instance of the glass pane for this form
     * @see com.sun.lwuit.painter.PainterChain#installGlassPane(Form, com.sun.lwuit.Painter) 
     */
    public Painter getGlassPane() {
        return glassPane;
    }

    /**
     * Sets the style of the title programmatically
     * 
     * @param s new style
     */
    public void setTitleStyle(Style s) {
        title.setStyle(s);
    }

    /**
     * Allows modifying the title attributes beyond style (e.g. setting icon/alignment etc.)
     * 
     * @return the component representing the title for the form
     */
    public Label getTitleComponent() {
        return title;
    }

    /**
     * Add a key listener to the given keycode for a callback when the key is released
     * 
     * @param keyCode code on which to send the event
     * @param listener listener to invoke when the key code released.
     */
    public void addKeyListener(int keyCode, ActionListener listener) {
        if (keyListeners == null) {
            keyListeners = new Hashtable();
        }
        addKeyListener(keyCode, listener, keyListeners);
    }

    /**
     * Removes a key listener from the given keycode 
     * 
     * @param keyCode code on which the event is sent
     * @param listener listener instance to remove
     */
    public void removeKeyListener(int keyCode, ActionListener listener) {
        if (keyListeners == null) {
            return;
        }
        removeKeyListener(keyCode, listener, keyListeners);
    }

    /**
     * Removes a game key listener from the given game keycode 
     * 
     * @param keyCode code on which the event is sent
     * @param listener listener instance to remove
     */
    public void removeGameKeyListener(int keyCode, ActionListener listener) {
        if (gameKeyListeners == null) {
            return;
        }
        removeKeyListener(keyCode, listener, gameKeyListeners);
    }

    private void addKeyListener(int keyCode, ActionListener listener, Hashtable keyListeners) {
        if (keyListeners == null) {
            keyListeners = new Hashtable();
        }
        Integer code = new Integer(keyCode);
        Vector vec = (Vector) keyListeners.get(code);
        if (vec == null) {
            vec = new Vector();
            vec.addElement(listener);
            keyListeners.put(code, vec);
            return;
        }
        if (!vec.contains(listener)) {
            vec.addElement(listener);
        }
    }

    private void removeKeyListener(int keyCode, ActionListener listener, Hashtable keyListeners) {
        if (keyListeners == null) {
            return;
        }
        Integer code = new Integer(keyCode);
        Vector vec = (Vector) keyListeners.get(code);
        if (vec == null) {
            return;
        }
        vec.removeElement(listener);
        if (vec.size() == 0) {
            keyListeners.remove(code);
        }
    }

    /**
     * Add a game key listener to the given gamekey for a callback when the 
     * key is released
     * 
     * @param keyCode code on which to send the event
     * @param listener listener to invoke when the key code released.
     */
    public void addGameKeyListener(int keyCode, ActionListener listener) {
        if (gameKeyListeners == null) {
            gameKeyListeners = new Hashtable();
        }
        addKeyListener(keyCode, listener, gameKeyListeners);
    }

    /**