/*
 *   
 *
 * Copyright  1990-2009 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 com.sun.midp.lcdui;

import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Image;
import javax.microedition.lcdui.Displayable;

/**
 * Public interface for an object that is used to provide internal access
 * to a Display object, across package boundaries.  The object implements
 * this interface, and is created inside the same package as Display,  so
 * that it has access to private instance data of Display as necessary.
 */
public interface DisplayAccess {
    /**
     * Get the Display object that is associated with this DisplayAccess.
     * @return Display The Display object.
     */
    Display getDisplay();

    /**
     * Called to get current display width.
     * @return Display width.
     */
    public int getDisplayWidth();

    /**
     * Called to get current display height.
     * @return Display height.
     */
    public int getDisplayHeight();

    /** Called to get the display to request the foreground. */
    public void requestForeground();

    // API's for accessing Display from Games Package

    /**
     * Called to get key mask of all the keys that were pressed.
     * @return keyMask  The key mask of all the keys that were pressed.
     */
    int getKeyMask();

    /**
     * Flushes the entire off-screen buffer to the display.
     * @param screen The Displayable 
     * @param offscreen_buffer The image buffer 
     * @param x The left edge of the region to be flushed
     * @param y The top edge of the region to be flushed
     * @param width The width of the region to be flushed
     * @param height The height of the region to be flushed
     */
    void flush(Displayable screen, Image offscreen_buffer,
	       int x, int y, int width, int height);

    /**
     * Called when the system needs to temporarily prevent the application
     * from painting the screen.  The primary use of this method is to allow
     * a system service to temporarily utilize the screen, e.g. to provide
     * input method or abstract command processing.
     *
     * This method should prevent application-based paints (i.e. those
     * generated by Canvas.repaint(), Canvas.serviceRepaints() or some
     * internal paint method on another kind of Displayable) from changing
     * the contents of the screen in any way.
     */
    // void suspendPainting();

    /**
     * Called when the system is ready to give up its control over the
     * screen.  The application should receive a request for a full
     * repaint when this is called, and is subsequently free to process
     * paint events from Canvas.repaint(), Canvas.serviceRepaints() or
     * internal paint methods on Displayable.
     */
    // void resumePainting();

    /**
     * Get the object that owns this display.
     * DisplayAccess I/F method.
     *
     * @return object that owns this Display
     */
    public Object getOwner();

    /**
     * Get the ID of this display.
     *
     * @return Display ID
     */
    public int getDisplayId();

    /**
     * Get the display device object.
     *
     * @return Hardware display object
     */
    public DisplayDevice getDisplayDevice();

    /**
     * Sets the ID of this display.
     * Shall be called only from DisplayContainer.addDisplay() during 
     * Display construction and registration in the container.
     *
     * @param newId new ID for Display associated with this DisplayAccess
     */
    public void setDisplayId(int newId);

    /**
     * Get the DisplayEventConsumer associated with this display.
     *
     * @return Consumer of midlet events that go through this display
     */
    public DisplayEventConsumer getDisplayEventConsumer();

    /**
     * Get the ForegroundEventConsumer associated with this display.
     *
     * @return Consumer of foreground events that go through this display
     */
    public ForegroundEventConsumer getForegroundEventConsumer();
}