displayable.java

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

/*
 * @(#)Displayable.java	1.136 02/10/14 @(#)
 *
 * Copyright (c) 1999-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package javax.microedition.lcdui;

import java.util.TimerTask;
import java.util.Timer;

import com.sun.midp.lcdui.Text;

/**
 * An object that has the capability of being placed on the display.  A 
 * <code>Displayable</code> object may have a title, a ticker,
 * zero or more commands and a listener associated with it.  The
 * contents displayed and their interaction with the user are defined by 
 * subclasses.
 *
 * <p>The title string may contain
 * <A HREF="Form.html#linebreak">line breaks</a>.
 * The display of the title string must break accordingly.
 * For example, if only a single line is available for a
 * title and the string contains a line break then only the characters
 * up to the line break are displayed.</p>
 *
 * <p>Unless otherwise specified by a subclass, the default state of newly 
 * created <code>Displayable</code> objects is as follows:</p>
 *
 * <ul>
 * <li>it is not visible on the <code>Display</code>;</li>
 * <li>there is no <code>Ticker</code> associated with this
 * <code>Displayable</code>;</li>
 * <li>the title is <code>null</code>;</li>
 * <li>there are no <code>Commands</code> present; and</li>
 * <li>there is no <code>CommandListener</code> present.</li>
 * </ul>
 *
 * @since MIDP 1.0
 */

abstract public class Displayable {

// ************************************************************
//  public member variables
// ************************************************************

// ************************************************************
//  protected member variables
// ************************************************************

// ************************************************************
//  package private member variables
// ************************************************************

    /** The current Display object */
    Display currentDisplay;

    /** An array of Commands added to this Displayable */
    Command commands[];

    /** The number of Commands added to this Displayable */
    int numCommands;

    /** The CommandListener for Commands added to this Displayable */
    CommandListener listener;

    /** Used as an index into the viewport[], for the x origin */
    final static int X      = 0;

    /** Used as an index into the viewport[], for the y origin */
    final static int Y      = 1;

    /** Used as an index into the viewport[], for the width */
    final static int WIDTH  = 2;

    /** Used as an index into the viewport[], for the height */
    final static int HEIGHT = 3;

    /**
     * The viewport coordinates.
     * Index 0: x origin coordinate (in the Display's coordinate space)
     * Index 1: y origin coordinate (in the DIsplay's coordinate space)
     * Index 2: width
     * Index 3: height
     */
    int[] viewport;

    /** True, if this Displayable is in full screen mode */
    boolean fullScreenMode;

    /**
     * True, indicates that before being painted, this Displayable should
     * be notified that its size has changed via callSizeChanged()
     */
    boolean sizeChangeOccurred;

    /**
     * In some circumstances (such as List), we need to delegate the
     * paint ownership. For example: List uses an internal Form to
     * do its rendering. If the Form requests a repaint, it will get
     * denied because the Form is not actually current - the List is.
     * So, we introduce the delegate, so the List can set the delegate
     * to itself, and its internal Form can schedule repaints.
     */
    Displayable paintDelegate;

// ************************************************************
//  private member variables
// ************************************************************

    /** Special title font */
    private final static  Font TITLE_FONT =
        Font.getFont(Font.FACE_SYSTEM, Font.STYLE_BOLD, Font.SIZE_MEDIUM);

    /** Special title height */
    private final static int TITLE_HEIGHT = TITLE_FONT.getHeight() + 1;

    /** The title for this Displayable */
    private String title;

    /** The ticker that may be set for this Displayable */
    private Ticker ticker;

    /** A Timer which will handle firing repaints of the TickerPainter */
    private final static Timer tickerTimer;

    /** A TimerTask which will repaint the Ticker on a repeated basis */
    private TickerPainter tickerPainter;

    /** Convenience int to avoid garbage during repainting */
    private int tickerHeight;

    /** Convenience int to avoid garbage during repainting */
    private int totalHeight;

    /** The vertical scroll position */
    private int vScrollPosition     = 0;

    /** The vertical scroll proportion */
    private int vScrollProportion   = 100;


// ************************************************************
//  Static initializer, constructor
// ************************************************************

    static {
    	tickerTimer = new Timer();
    }

    /**
     * Create a new Displayable
     */
    Displayable() {
        setupViewport();
        translateViewport();
        paintDelegate = this;
    }

// ************************************************************
//  public methods
// ************************************************************

    /**
     * Gets the title of the <code>Displayable</code>. Returns
     * <code>null</code> if there is no title.
     * @return the title of the instance, or <code>null</code> if no title
     * @since MIDP 2.0
     * @see #setTitle
     */
    public String getTitle() {
        // SYNC NOTE: return of atomic value, no lock necessary
        return title;
    }

    /**
     * Sets the title of the <code>Displayable</code>. If
     * <code>null</code> is given,
     * removes the title. 
     *
     * <P>If the <code>Displayable</code> is actually visible on
     * the display,
     * the implementation should update 
     * the display as soon as it is feasible to do so.</P>
     * 
     * <P>The existence of a title  may affect the size
     * of the area available for <code>Displayable</code> content. 
     * Addition, removal, or the setting of the title text at runtime
     * may dynamically change the size of the content area.
     * This is most important to be aware of when using the
     * <code>Canvas</code> class.
     * If the available area does change, the application will be notified
     * via a call to {@link #sizeChanged(int, int) sizeChanged()}. </p>
     *
     * @param s the new title, or <code>null</code> for no title
     * @since MIDP 2.0
     * @see #getTitle
     */
    public void setTitle(String s) {
        synchronized (Display.LCDUILock) {
            setTitleImpl(s);
        }
    }

    /**
     * Gets the ticker used by this <code>Displayable</code>.
     * @return ticker object used, or <code>null</code> if no
     * ticker is present
     * @since MIDP 2.0
     * @see #setTicker
     */
    public Ticker getTicker() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return ticker;
    }

    /**
     * Sets a ticker for use with this <code>Displayable</code>,
     * replacing any
     * previous ticker.
     * If <code>null</code>, removes the ticker object
     * from this <code>Displayable</code>. The same ticker may be shared by 
     * several <code>Displayable</code>
     * objects within an application. This is done by calling
     * <code>setTicker()</code>
     * with the same <code>Ticker</code> object on several
     * different <code>Displayable</code> objects.
     * If the <code>Displayable</code> is actually visible on the display,
     * the implementation should update 
     * the display as soon as it is feasible to do so.
     * 
     * <p>The existence of a ticker may affect the size
     * of the area available for <code>Displayable's</code> contents. 
     * Addition, removal, or the setting of the ticker at runtime
     * may dynamically change the size of the content area.
     * This is most important to be aware of when using the
     * <code>Canvas</code> class.
     * If the available area does change, the application will be notified
     * via a call to {@link #sizeChanged(int, int) sizeChanged()}. </p>
     *
     * @param ticker the ticker object used on this screen
     * @since MIDP 2.0
     * @see #getTicker
     */
    public void setTicker(Ticker ticker) {
        synchronized (Display.LCDUILock) {
            setTickerImpl(ticker);
        }
    }

    /**
     * Checks if the <code>Displayable</code> is actually visible
     * on the display.  In order
     * for a <code>Displayable</code> to be visible, all of the
     * following must be true:
     * the <code>Display's</code> <code>MIDlet</code> must be
     * running in the foreground, the <code>Displayable</code>
     * must be the <code>Display's</code> current screen, and the
     * <code>Displayable</code> must not be
     * obscured by a <a href="Display.html#systemscreens">
     * system screen</a>.
     *
     * @return <code>true</code> if the
     * <code>Displayable</code> is currently visible
     */
    public boolean isShown() {
        synchronized (Display.LCDUILock) {
            return (currentDisplay == null) ?
                false : currentDisplay.isShown(this);
        }
    }

    /**
     * Adds a command to the <code>Displayable</code>. The
     * implementation may choose,
     * for example,
     * to add the command to any of the available soft buttons or place it 
     * in a menu.
     * If the added command is already in the screen (tested by comparing the
     * object references), the method has no effect.
     * If the <code>Displayable</code> is actually visible on the
     * display, and this call
     * affects the set of visible commands, the implementation should update 
     * the display as soon as it is feasible to do so.
     * 
     * @param cmd the command to be added
     *
     * @throws NullPointerException if <code>cmd</code> is
     * <code>null</code>
     */
    public void addCommand(Command cmd) {
        if (cmd == null) {
            throw new NullPointerException();
        }

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

    /**
     * Removes a command from the <code>Displayable</code>.
     * If the command is not in the <code>Displayable</code>
     * (tested by comparing the
     * object references), the method has no effect.
     * If the <code>Displayable</code> is actually visible on the
     * display, and this call
     * affects the set of visible commands, the implementation should update 
     * the display as soon as it is feasible to do so.
     * If <code>cmd</code> is <code>null</code>, this method
     * does nothing.
     * 
     * @param cmd the command to be removed
     */
    public void removeCommand(Command cmd) {
        synchronized (Display.LCDUILock) {
            removeCommandImpl(cmd);
        }
    }

    /**
     * Sets a listener for {@link Command Commands} to this
     * <code>Displayable</code>,
     * replacing any previous <code>CommandListener</code>. A
     * <code>null</code> reference is
     * allowed and has the effect of removing any existing listener.
     *
     * @param l the new listener, or <code>null</code>.
     */
    public void setCommandListener(CommandListener l) {
        synchronized (Display.LCDUILock) {
            listener = l;
        }
    }

    /**
     * Gets the width in pixels of the displayable area available to the 
     * application.  The value returned is appropriate for the particular 
     * <code>Displayable</code> subclass.  This value may depend
     * on how the device uses the
     * display and may be affected by the presence of a title, a ticker, or 
     * commands.
     * This method returns the proper result at all times, even if the
     * <code>Displayable</code> object has not yet been shown.
     * 
     * @return width of the area available to the application
     * @since MIDP 2.0
     */
    public int getWidth() {
        // SYNC NOTE: return of atomic value
        return viewport[WIDTH];
    }

    /**
     * Gets the height in pixels of the displayable area available to the 
     * application.  The value returned is appropriate for the particular 
     * <code>Displayable</code> subclass.  This value may depend
     * on how the device uses the
     * display and may be affected by the presence of a title, a ticker, or 
     * commands.
     * This method returns the proper result at all times, even if the
     * <code>Displayable</code> object has not yet been shown.
     * 
     * @return height of the area available to the application
     * @since MIDP 2.0
     */
    public int getHeight() {
        // SYNC NOTE: return of atomic value
        return viewport[HEIGHT];
    }

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

    /**
     * The implementation calls this method when the available area of the
     * <code>Displayable</code> has been changed. 
     * The &quot;available area&quot; is the area of the display that
     * may be occupied by
     * the application's contents, such as <code>Items</code> in a
     * <code>Form</code> or graphics within
     * a <code>Canvas</code>.  It does not include space occupied
     * by a title, a ticker,
     * command labels, scroll bars, system status area, etc.  A size change