/*
 * 	
 *
 * Copyright  1990-2006 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program 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. 
 * 
 * This program 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 at /legal/license.txt). 
 * 
 * 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 or visit www.sun.com if you need additional
 * information or have any questions. 
 */

package javax.microedition.lcdui;

/**
 * Look and Feel interface used by Displayable.
 * <p>
 * See <a href="doc-files/naming.html">Naming Conventions</a>
 * for information about method naming conventions.
 */
interface DisplayableLF {

/*
 * Interface to Displayable
 */
    /**
     * Implement the public API isShown().
     * @return true if the DisplayableLF is interactive with user.
     */
    boolean lIsShown();

    /**
     * Returns the width of the area available to the application.
     *
     * @return width of the area available to the application
     */
    int lGetWidth();
    
    /**
     * Returns the height of the area available to the application.
     *
     * @return height of the area available to the application
     */
    int lGetHeight();

    /**
     * Notifies Displayable's look & feel object of a title change.
     *
     * @param oldTitle the old title, or <code>null</code> for no title
     * @param newTitle the new title, or <code>null</code> for no title
     */
    void lSetTitle(String oldTitle, String newTitle);

    /**
     * Notifies Displayable's look & feel object of a ticker change.
     *
     * @param oldTicker the old ticker, or <code>null</code> for no ticker
     * @param newTicker the new ticker, or <code>null</code> for no ticker
     */
    void lSetTicker(Ticker oldTicker, Ticker newTicker);

    /**
     * Notifies look&feel object of a command addition 
     * to the <code>Displayable</code>.
     * 
     * @param cmd the command that was added
     * @param i the index of the added command in Displayable.commands[] 
     *        array
     */
    void lAddCommand(Command cmd, int i);

    /**
     * Notifies look&feel object of a command removal 
     * from the <code>Displayable</code>.
     * 
     * @param cmd the command that was removed
     * @param i the index of the removed command in Displayable.commands[] 
     *        array
     */
    void lRemoveCommand(Command cmd, int i);

    /**
     * Notifies look&feel object of commandset being updated.
     */
    void updateCommandSet();

    /**
     * Return in which Display instance the LF is visible.
     *
     * @return the current display.
     */
    Display lGetCurrentDisplay();

    /**
     * Notify the full screen mode of this LF.
     *
     * If true, this DisplayableLF will take up as much screen
     * real estate as possible. Any subclass of Displayable 
     * should be prepared to do their job to accommodate the
     * change.
     * Note that it can call into the app code.
     *
     * @param fullScreenMode true if full screen mode should be turned on
     */
    void uSetFullScreenMode(boolean fullScreenMode);

/*
 * Interface to Display
 */

    /**
     * Return the associated Displayable object.
     *
     * @return the Displayable object.
     */
    Displayable lGetDisplayable();

    /**
     * Prepare to show this LF on physical screen. This is the
     * internal version of showNotify() function as defined in MIDP spec.
     * It is called immediately prior to this LF being made visible
     * on the display. The LF should load any resource that is
     * needed, layout. App's paint() should NOT be called in this function.
     * Instead, it should be in the dsPaint() that will be called on this
     * LF shortly after.
     */
    void uCallShow();

    /**
     * Remove this displayable from physical screen.
     * The displayable should unload any resource that was allocated. It's not
     * required to clean the physical screen before this function returns.
     * This function could be called while a LF is in "freeze" mode.
     */
    void uCallHide();

    /**
     * Set the display instance the Displayable is associated with.
     * Caller should hold LCDUILock around this call.
     *
     * @param d Display instance in which this DisplayableLF is visible.
     *		null if this DisplayableLF is no longer visible.
     */
    void lSetDisplay(Display d);

    /**
     * While UI resources of this LF are created and visible already, stop any
     * further updates to physical screen because some "system modal dialog"
     * takes over physical screen buffer and user input now.
     * Repaint and invalidate requests from this DisplayableLF will be really 
     * scheduled into event queue. Instead, only dirty flag is set.
     * After a LF enters "freeze" mode, it can be resumed of visibility or 
     * directly replaced by a new Displayable.
     */
    void uCallFreeze();

    /**
     * Handle key events.
     *
     * @param type defined in EventConstants.
     * @param keyCode the key involved in this event.
     */
    void uCallKeyEvent(int type, int keyCode);

    /**
     * Handle pointer events.
     * @param type kind of event, defined in EventConstants.
     * @param x    x-coordinate of pointer event
     * @param y    y-coordinate of pointer event
     */
    void uCallPointerEvent(int type, int x, int y);

    /**
     * Relayout and repaint now. Called by the event handler to perform an
     * invalidation of this Displayable.
     */
    void uCallInvalidate();

    /**
     * Repaint now. Display calls this method on it's current Displayable.
     * Displayable uses this opportunity to do necessary stuff
     * on the Graphics context, this includes,
     * paint Ticker, paint Title, translate as necessary.
     *
     * <p>The target Object of this repaint may be some Object
     * initially set by this Displayable when the repaint was
     * requested - allowing this Displayable to know exactly
     * which Object it needs to call to service this repaint,
     * rather than potentially querying all of its Objects to
     * determine the one(s) which need painting.
     *
     * SYNC NOTE: The caller of this method handles synchronization.
     *
     * @param g the graphics context to paint into.
     * @param target the target Object of this repaint
     */
    void uCallPaint(Graphics g, Object target);

    /**
     * Called to commit any pending user interaction for the current
     * item before an abstract command is fired.
     * Caller should hold LCDUILock around this call.
     */
    void lCommitPendingInteraction();

    /**
     * This method is used int repaint, int order to determine the
     * translation of the draw coordinates.
     * @return true if the scroll responsibility is of the native platform.
     * false - if the scroll is done in the Java level.     
     */
    boolean uIsScrollNative();

    /**
     * This method calls Displayable.sizeChanged method.
     * 
     * @param w the new width
     * @param h the new height
     */    
    void uCallSizeChanged(int w, int h);

    /**
     * This method notify displayable to scroll its content 
     *
     * @param scrollType scrollType
     * @param thumbPosition
     */
    void uCallScrollContent(int scrollType, int thumbPosition);

    boolean uSetRotatedStatus (boolean newStatus);

    /**
     * Get the current vertical scroll position
     *
     * @return int The vertical scroll position on a scale of 0-100
     */
    int getVerticalScrollPosition();

    /**
     * Get the current vertical scroll proportion
     *
     * @return ing The vertical scroll proportion on a scale of 0-100
     */
    int getVerticalScrollProportion();

}
