/* ComponentPeer.java -- Toplevel component peer
   Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath 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 for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package java.awt.peer;

import java.awt.AWTEvent;
import java.awt.AWTException;
import java.awt.BufferCapabilities;
import java.awt.Color;
import java.awt.Component;
import java.awt.Cursor;
import java.awt.Dimension;
import java.awt.Font;
import java.awt.FontMetrics;
import java.awt.Graphics;
import java.awt.GraphicsConfiguration;
import java.awt.Image;
import java.awt.Point;
import java.awt.Rectangle;
import java.awt.Toolkit;
import java.awt.event.PaintEvent;
import java.awt.image.ColorModel;
import java.awt.image.ImageObserver;
import java.awt.image.ImageProducer;
import java.awt.image.VolatileImage;

/**
 * Defines the methods that a component peer is required to implement.
 */
public interface ComponentPeer
{
  /**
   * Returns the construction status of the specified image. This is called
   * by {@link Component#checkImage(Image, int, int, ImageObserver)}.
   *
   * @param img the image
   * @param width the width of the image
   * @param height the height of the image
   * @param ob the image observer to be notified of updates of the status
   *
   * @return a bitwise ORed set of ImageObserver flags
   */
  int checkImage(Image img, int width, int height, 
                 ImageObserver ob);

  /**
   * Creates an image by starting the specified image producer. This is called
   * by {@link Component#createImage(ImageProducer)}.
   *
   * @param prod the image producer to be used to create the image
   *
   * @return the created image
   */
  Image createImage(ImageProducer prod);

  /**
   * Creates an empty image with the specified <code>width</code> and
   * <code>height</code>.
   *
   * @param width the width of the image to be created
   * @param height the height of the image to be created
   *
   * @return the created image
   */
  Image createImage(int width, int height);

  /**
   * Disables the component. This is called by {@link Component#disable()}.
   */
  void disable();

  /**
   * Disposes the component peer. This should release all resources held by the
   * peer. This is called when the component is no longer in use.
   */
  void dispose();

  /**
   * Enables the component. This is called by {@link Component#enable()}.
   */
  void enable();

  /**
   * Returns the color model of the component. This is currently not used.
   *
   * @return the color model of the component
   */
  ColorModel getColorModel();

  /**
   * Returns the font metrics for the specified font. This is called by
   * {@link Component#getFontMetrics(Font)}.
   *
   * @param f the font for which to query the font metrics
   *
   * @return the font metrics for the specified font
   */
  FontMetrics getFontMetrics(Font f);

  /**
   * Returns a {@link Graphics} object suitable for drawing on this component.
   * This is called by {@link Component#getGraphics()}.
   *
   * @return a graphics object suitable for drawing on this component
   */
  Graphics getGraphics();

  /**
   * Returns the location of this component in screen coordinates. This is
   * called by {@link Component#getLocationOnScreen()}.
   *
   * @return the location of this component in screen coordinates
   */
  Point getLocationOnScreen();

  /**
   * Returns the minimum size for the component. This is called by
   * {@link Component#getMinimumSize()}.
   *
   * @return the minimum size for the component
   *
   * @specnote Presumably this method got added to replace minimumSize().
   *           However, testing shows that this is never called in the RI
   *           (tested with JDK5), but instead minimumSize() is called
   *           directly. It is advisable to implement this method to delegate
   *           to minimumSize() and put the real implementation in there.
   */
  Dimension getMinimumSize();

  /**
   * Returns the preferred size for the component. This is called by
   * {@link Component#getPreferredSize()}.
   *
   * @return the preferred size for the component
   *
   * @specnote Presumably this method got added to replace preferredSize().
   *           However, testing shows that this is never called in the RI
   *           (tested with JDK5), but instead preferredSize() is called
   *           directly. It is advisable to implement this method to delegate
   *           to preferredSize() and put the real implementation in there.
   */
  Dimension getPreferredSize();

  /**
   * Returns the toolkit that created this peer.
   *
   * @return the toolkit that created this peer
   */
  Toolkit getToolkit();

  /**
   * Handles the given event. This is called from
   * {@link Component#dispatchEvent(AWTEvent)} to give the peer a chance to 
   * react to events for the component.
   *
   * @param e the event
   */
  void handleEvent(AWTEvent e);

  /**
   * Makes the component invisible. This is called from
   * {@link Component#hide()}.
   */
  void hide();

  /**
   * Returns <code>true</code> if the component can receive keyboard input
   * focus. This is called from {@link Component#isFocusTraversable()}.
   * 
   * @specnote Part of the earlier 1.1 API, replaced by isFocusable().
   */
  boolean isFocusTraversable();

  /**
   * Returns <code>true</code> if the component can receive keyboard input
   * focus. This is called from {@link Component#isFocusable()}.
   */
  boolean isFocusable();

  /**
   * Returns the minimum size for the component. This is called by
   * {@link Component#minimumSize()}.
   *
   * @return the minimum size for the component
   */
  Dimension minimumSize();

  /**
   * Returns the preferred size for the component. This is called by
   * {@link Component#getPreferredSize()}.
   *
   * @return the preferred size for the component
   */
  Dimension preferredSize();

  void paint(Graphics graphics);

  /**
   * Prepares an image for rendering on this component. This is called by
   * {@link Component#prepareImage(Image, int, int, ImageObserver)}.
   *
   * @param img the image to prepare
   * @param width the desired width of the rendered image
   * @param height the desired height of the rendered image
   * @param ob the image observer to be notified of updates in the preparation
   *        process
   *
   * @return <code>true</code> if the image has been fully prepared,
   *         <code>false</code> otherwise (in which case the image observer
   *         receives updates)
   */
  boolean prepareImage(Image img, int width, int height,
			      ImageObserver ob);

  void print(Graphics graphics);

  /**
   * Repaints the specified rectangle of this component. This is called from
   * {@link Component#repaint(long, int, int, int, int)}.
   *
   * @param tm number of milliseconds to wait with repainting
   * @param x the X coordinate of the upper left corner of the damaged rectangle
   * @param y the Y coordinate of the upper left corner of the damaged rectangle
   * @param width the width of the damaged rectangle
   * @param height the height of the damaged rectangle
   */
  void repaint(long tm, int x, int y, int width, int height);

  /**
   * Requests that this component receives the focus. This is called from
   * {@link Component#requestFocus()}.
   * 
   * @specnote Part of the earlier 1.1 API, apparently replaced by argument 
   *           form of the same method.
   */
  void requestFocus();

  /**
   * Requests that this component receives the focus. This is called from
   * {@link Component#requestFocus()}.
   *
   * This method is only called for heavyweight component's peers. Lightweight
   * components ask their nearest heavyweight component to request focus.
   * It's up to the heavyweight peer to decide if any of it's lightweight
   * descendants are allowed to receive keyboard input focus or not. If the
   * focus request is finally approved, then the peer must post a FOCUS_GAINED
   * event for the requested component.
   *
   * @param request the component for which the focus is requested
   * @param temporary indicates if the focus change is temporary (true) or
   *        permanent (false)
   * @param allowWindowFocus indicates if it's allowed to change window focus
   * @param time the timestamp
   */
  boolean requestFocus(Component request, boolean temporary,
                       boolean allowWindowFocus, long time);

  /**
   * Notifies the peer that the bounds of this component have changed. This
   * is called by {@link Component#reshape(int, int, int, int)}.
   *
   * @param x the X coordinate of the upper left corner of the component
   * @param y the Y coordinate of the upper left corner of the component
   * @param width the width of the component
   * @param height the height of the component
   */
  void reshape(int x, int y, int width, int height);

  /**
   * Sets the background color of the component. This is called by
   * {@link Component#setBackground(Color)}.
   *
   * @param color the background color to set
   */
  void setBackground(Color color);

  /**
   * Notifies the peer that the bounds of this component have changed. This
   * is called by {@link Component#setBounds(int, int, int, int)}.
   *
   * @param x the X coordinate of the upper left corner of the component
   * @param y the Y coordinate of the upper left corner of the component
   * @param width the width of the component
   * @param height the height of the component
   */
  void setBounds(int x, int y, int width, int height);

  /**
   * Sets the cursor of the component. This is called by
   * {@link Component#setCursor(Cursor)}.
   *
   * @specnote Part of the earlier 1.1 API, apparently no longer needed.
   */
  void setCursor(Cursor cursor);

  /**
   * Sets the enabled/disabled state of this component. This is called by
   * {@link Component#setEnabled(boolean)}.
   *
   * @param enabled <code>true</code> to enable the component,
   *        <code>false</code> to disable it
   */
  void setEnabled(boolean enabled);

  /**
   * Sets the font of the component. This is called by
   * {@link Component#setFont(Font)}.
   *
   * @param font the font to set
   */
  void setFont(Font font);

  /**
   * Sets the foreground color of the component. This is called by
   * {@link Component#setForeground(Color)}.
   *
   * @param color the foreground color to set
   */
  void setForeground(Color color);

  /**
   * Sets the visibility state of the component. This is called by
   * {@link Component#setVisible(boolean)}.
   *
   * @param visible <code>true</code> to make the component visible,
   *        <code>false</code> to make it invisible
   */
  void setVisible(boolean visible);

  /**
   * Makes the component visible. This is called by {@link Component#show()}.
   */
  void show();

  /** 
   * Get the graphics configuration of the component. The color model
   * of the component can be derived from the configuration.
   *
   * @return the graphics configuration of the component
   */
  GraphicsConfiguration getGraphicsConfiguration();

  /**
   * Part of an older API, no longer needed.
   */
  void setEventMask(long mask);

  /**
   * Returns <code>true</code> if this component has been obscured,
   * <code>false</code> otherwise. This will only work if
   * {@link #canDetermineObscurity()} also returns <code>true</code>.
   *
   * @return <code>true</code> if this component has been obscured,
   *         <code>false</code> otherwise.
   */
  boolean isObscured();

  /**
   * Returns <code>true</code> if this component peer can determine if the
   * component has been obscured, <code>false</code> otherwise.
   *
   * @return <code>true</code> if this component peer can determine if the
   *         component has been obscured, <code>false</code> otherwise
   */
  boolean canDetermineObscurity();

  /**
   * Coalesces the specified paint event.
   *
   * @param e the paint event
   */
  void coalescePaintEvent(PaintEvent e);

  /**
   * Updates the cursor.
   */
  void updateCursorImmediately();

  /**
   * Returns true, if this component can handle wheel scrolling,
   * <code>false</code> otherwise.
   *
   * @return true, if this component can handle wheel scrolling,
   *         <code>false</code> otherwise
   */
  boolean handlesWheelScrolling();

  /**
   * A convenience method that creates a volatile image.  The volatile
   * image is created on the screen device on which this component is
   * displayed, in the device's current graphics configuration.
   *
   * @param width width of the image
   * @param height height of the image
   *
   * @see VolatileImage
   *
   * @since 1.2
   */
  VolatileImage createVolatileImage(int width, int height);

  /**
   * Create a number of image buffers that implement a buffering
   * strategy according to the given capabilities.
   *
   * @param numBuffers the number of buffers
   * @param caps the buffering capabilities
   *
   * @throws AWTException if the specified buffering strategy is not
   * implemented
   *
   * @since 1.2
   */
  void createBuffers(int numBuffers, BufferCapabilities caps)
    throws AWTException;

  /**
   * Return the back buffer of this component.
   *
   * @return the back buffer of this component.
   *
   * @since 1.2
   */
  Image getBackBuffer();

  /**
   * Perform a page flip, leaving the contents of the back buffer in
   * the specified state.
   *
   * @param contents the state in which to leave the back buffer
   *
   * @since 1.2
   */
  void flip(BufferCapabilities.FlipContents contents);

  /**
   * Destroy the resources created by createBuffers.
   *
   * @since 1.2
   */
  void destroyBuffers();
  
  /**
   * Get the bounds of this component peer.
   * 
   * @return component peer bounds
   * @since 1.5
   */
  Rectangle getBounds();

  /**
   * Reparent this component under another container.
   * 
   * @param parent
   * @since 1.5
   */
  void reparent(ContainerPeer parent);
  
  /**
   * Set the bounds of this component peer.
   * 
   * @param x the new x co-ordinate
   * @param y the new y co-ordinate
   * @param width the new width
   * @param height the new height
   * @param z the new stacking level
   * @since 1.5
   */
  void setBounds (int x, int y, int width, int height, int z);
  
  /**
   * Check if this component supports being reparented.
   * 
   * @return true if this component can be reparented,
   * false otherwise.
   * @since 1.5
   */
  boolean isReparentSupported();

  /**
   * Layout this component peer.
   *
   * @since 1.5
   */
  void layout();
}