/* * @(#)Screen.java	1.124 01/08/21  * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information").  You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING * THIS SOFTWARE OR ITS DERIVATIVES. */package javax.microedition.lcdui;import java.util.TimerTask;import java.util.Timer;/** * <P>The common superclass of all high-level user interface classes.  Adds * optional title and ticker-tape output to the Displayable class.  The * contents displayed and their interaction with the user are defined by  * subclasses.</P> * * <P>Using subclass-defined methods, the application may change the contents * of a Screen object while it is shown to the user.  If this occurs, and the * Screen object is visible, the display will be updated automatically.  That * is, the implementation will refresh the display in a timely fashion without * waiting for any further action by the application.  For example, suppose a * List object is currently displayed, and every element of the List is * visible.  If the application inserts a new element at the beginning of the * List, it is displayed immediately, and the other elements will be * rearranged appropriately.  There is no need for the application to call * another method to refresh the display.</P> * * <P>It is recommended that applications change the contents of a Screen only * while it is not visible (that is, while another Displayable is current). * Changing the contents of a Screen while it is visible may result in * performance problems on some devices, and it may also be confusing if the * Screen's contents changes while the user is interacting with it.</P> */public abstract class Screen extends Displayable  {    /** The Ticker which may be set on this Screen */    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;    /** Renders the title for this Screen */    private Layout screenTitle;    /**     * Whether or not this Screen is currently displayed on the physical     * device     */    private boolean visible;         // = false;    /**     * Whether or not the Ticker (if there is one) is part of the display     * of this Screen (ie, not being optimized out of the layout for space)     */    private boolean tickerIsVisible; // = false;    /** this variable is set to true once layout was done */    private boolean layoutDoneOnce;  // = false;    /** 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();    /** Special content font, shared amongst the LCDUI package */    final static Font CONTENT_FONT  = Font.getDefaultFont();    /** Special content height, shared amongst the LCDUI package */    final static int CONTENT_HEIGHT = CONTENT_FONT.getHeight();    /** height of the child that is shown in the viewport */    private int childHeight;        // = 0;    /**     * When hasBorder is true there is a pixel border painted around     * content and viewPort is reduced by 4 pixels. This is used by     * subclasses such as TextBox which need a pixel border around them.     */    boolean hasBorder;             // = false;    /** view port X position (in Sreen coordinates) */    private int globalViewPortX;    /** view port Y position (in Sreen coordinates) */    private int globalViewPortY;    /** view port position (in child coordinates) */    private int viewPortY;    /** view port width */    int viewPortWidth;    /** view port height */    int viewPortHeight;    /**     * Creates a new Screen object with no title and no ticker.     */    Screen() {        this(null);    }    /**     * Creates a new Screen object with the given title and with no ticker.     *     * @param title the Screen's title, or null for no title     */    Screen(String title) {        // SYNC NOTE: since subclasses can't protect their call to super()        // we'll sync it here        synchronized (Display.LCDUILock) {            if (title != null) {                screenTitle = new StringLayout(title, TITLE_FONT);            }        }    }    /**     * Gets the title of the Screen.      *      * @return a String representing the title value, or null if there      *         is no title     *      * @see #setTitle          */    public String getTitle() {        synchronized (Display.LCDUILock) {            return getTitleImpl();        }    }    /**     * Sets the title of the Screen. If null is given, removes the title. <p>     *     * If the Screen is physically visible, the visible effect     * should take place no later than immediately     * after the callback or     * {@link javax.microedition.midlet.MIDlet#startApp startApp}     * returns back to the implementation.     *     * @param s the new title, or null for no title     *     * @see #getTitle     */    public void setTitle(String s) {        synchronized (Display.LCDUILock) {            String oldTitle = getTitleImpl();            if ((oldTitle == null && s == null) ||                    (oldTitle != null && s != null && oldTitle.equals(s))) {                return;            }	    int deltaHeight = 0;            if (screenTitle != null) {                deltaHeight = ((StringLayout)screenTitle).setString(s);            } else if (s != null) {                screenTitle = new StringLayout(s, TITLE_FONT);                if (layoutDoneOnce) {                    deltaHeight = screenTitle.setWidth(Display.WIDTH);                }            }	    // if layout was done yet there is no need to repaint	    // nor to re-layout	    if (!layoutDoneOnce) {		return;	    }	    // repaint only the title area if title height did not change            if (deltaHeight == 0) {                if (visible) {                    int y = 0;                    if (tickerIsVisible) {                        y = ticker.PREFERRED_HEIGHT;                    }                    repaint(0, y, Display.WIDTH, screenTitle.getHeight());                }                return;            }            // layoutChanged will take care of layout            // then do repaint if this screen is visible            layoutChanged();        } // sychronized    }    /**     * Set a ticker for use with this Screen, replacing any previous ticker.     * If null, removes the ticker object     * from this screen. The same ticker is may be shared by several Screen     * objects within an application. This is done by calling setTicker() on     * different screens with the same Ticker object.     * If the Screen is physically visible, the visible effect     * should take place no later than immediately     * after the callback or     * {@link javax.microedition.midlet.MIDlet#startApp startApp}     * returns back to the implementation.     * @param ticker the ticker object used on this screen     *      * @see #getTicker     */    public void setTicker(Ticker ticker) {        synchronized (Display.LCDUILock) {            // Return early if there's nothing to do            if (this.ticker == ticker) {                return;            }            // Stop any currently running Ticker.            stopTicker();            // We initialize the new ticker to start its message display            // from the right side of the screen. This is important for new            // tickers as well as tickers which may have already been running            // and are making a subsequent appearance to the screen.            // (Easier to add this here than attempt to fold into the            // if-else below)            if (ticker != null) {                ticker.reset();            }            // CASES:            // 1. Had an invisible non-null ticker, setting a null ticker            //    - We need to set the new ticker. There's no need to re-layout            //      or start the new ticker            // 2. Had an invisible non-null ticker, setting a non-null ticker            //    - We need to set the new ticker. There's no need to re-layout            //      or start the new ticker            // 3. Had a visible non-null ticker, setting a null ticker            //    - We need to set the new ticker and re-layout. There's no            //      need to start the new ticker.            // 4. Had a null ticker, setting a non-null ticker            //    - We need to set the new ticker, re-layout, and possibly            //      start up the new ticker            // 5. Had a visible non-null ticker, setting a non-null ticker            //    - We need to set the new ticker. There's no need to re-layout            //      but we do have to start the new ticker            Ticker oldTicker = this.ticker;            this.ticker = ticker;            // This 'if' test covers conditions 3 & 4. Note we don't need the            // test for case 4 to be 'this.ticker == null && ticker != null'	    // because            // we're guaranteed that 'ticker != null' above where we test for            // 'this.ticker == ticker'; so 'this.ticker == null' is enough to            // satisfy case 4.            if ((tickerIsVisible && ticker == null) ||                oldTicker == null)            {                layoutChanged(); // takes care of setting tickerIsVisible            }            // We know from cases 4 & 5 that we may need to start the new            // ticker, we do the 'if' test to avoid a blanket call to            // startTicker(), ie in cases 1 & 3. The added test for            // tickerIsVisible shortcircuits the method call to startTicker()            // which will simply return anyway (case 2).            if (ticker != null && tickerIsVisible) {                startTicker();            }        } // synchronized    }    /**     * Gets the ticker used by this Screen.     * @return ticker object used, or null if no ticker is present     *     * @see #setTicker          */    public Ticker getTicker() {        // SYNC NOTE: return of atomic value, no locking necessary        return ticker;    }    // package private ********************************************    /**     * Paint the content of this Screen     *     * @param g The Graphics to paint to     */    abstract void paintContent(Graphics g);    /**     * Layout the content of this Screen     *     * @param w The width of the layout     * @param h The height of the Layout     * @return int The new height of the Screen     */    abstract int layoutContent(int w, int h);    /**     * Get the minimum height for this Screen     *     * @param width The maximum width     * @param height The maximum height     * @return int The minimum content height to display this Screen