libjava/classpath/java/awt/peer/ComponentPeer.java

   1 /* ComponentPeer.java -- Toplevel component peer
   2    Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt.peer;
  40
  41 import java.awt.AWTEvent;
  42 import java.awt.AWTException;
  43 import java.awt.BufferCapabilities;
  44 import java.awt.Color;
  45 import java.awt.Component;
  46 import java.awt.Cursor;
  47 import java.awt.Dimension;
  48 import java.awt.Font;
  49 import java.awt.FontMetrics;
  50 import java.awt.Graphics;
  51 import java.awt.GraphicsConfiguration;
  52 import java.awt.Image;
  53 import java.awt.Point;
  54 import java.awt.Rectangle;
  55 import java.awt.Toolkit;
  56 import java.awt.event.PaintEvent;
  57 import java.awt.image.ColorModel;
  58 import java.awt.image.ImageObserver;
  59 import java.awt.image.ImageProducer;
  60 import java.awt.image.VolatileImage;
  61
  62 /**
  63  * Defines the methods that a component peer is required to implement.
  64  */
  65 public interface ComponentPeer
  66 {
  67   /**
  68    * Returns the construction status of the specified image. This is called
  69    * by {@link Component#checkImage(Image, int, int, ImageObserver)}.
  70    *
  71    * @param img the image
  72    * @param width the width of the image
  73    * @param height the height of the image
  74    * @param ob the image observer to be notified of updates of the status
  75    *
  76    * @return a bitwise ORed set of ImageObserver flags
  77    */
  78   int checkImage(Image img, int width, int height,
  79                  ImageObserver ob);
  80
  81   /**
  82    * Creates an image by starting the specified image producer. This is called
  83    * by {@link Component#createImage(ImageProducer)}.
  84    *
  85    * @param prod the image producer to be used to create the image
  86    *
  87    * @return the created image
  88    */
  89   Image createImage(ImageProducer prod);
  90
  91   /**
  92    * Creates an empty image with the specified <code>width</code> and
  93    * <code>height</code>.
  94    *
  95    * @param width the width of the image to be created
  96    * @param height the height of the image to be created
  97    *
  98    * @return the created image
  99    */
 100   Image createImage(int width, int height);
 101
 102   /**
 103    * Disables the component. This is called by {@link Component#disable()}.
 104    */
 105   void disable();
 106
 107   /**
 108    * Disposes the component peer. This should release all resources held by the
 109    * peer. This is called when the component is no longer in use.
 110    */
 111   void dispose();
 112
 113   /**
 114    * Enables the component. This is called by {@link Component#enable()}.
 115    */
 116   void enable();
 117
 118   /**
 119    * Returns the color model of the component. This is currently not used.
 120    *
 121    * @return the color model of the component
 122    */
 123   ColorModel getColorModel();
 124
 125   /**
 126    * Returns the font metrics for the specified font. This is called by
 127    * {@link Component#getFontMetrics(Font)}.
 128    *
 129    * @param f the font for which to query the font metrics
 130    *
 131    * @return the font metrics for the specified font
 132    */
 133   FontMetrics getFontMetrics(Font f);
 134
 135   /**
 136    * Returns a {@link Graphics} object suitable for drawing on this component.
 137    * This is called by {@link Component#getGraphics()}.
 138    *
 139    * @return a graphics object suitable for drawing on this component
 140    */
 141   Graphics getGraphics();
 142
 143   /**
 144    * Returns the location of this component in screen coordinates. This is
 145    * called by {@link Component#getLocationOnScreen()}.
 146    *
 147    * @return the location of this component in screen coordinates
 148    */
 149   Point getLocationOnScreen();
 150
 151   /**
 152    * Returns the minimum size for the component. This is called by
 153    * {@link Component#getMinimumSize()}.
 154    *
 155    * @return the minimum size for the component
 156    */
 157   Dimension getMinimumSize();
 158
 159   /**
 160    * Returns the preferred size for the component. This is called by
 161    * {@link Component#getPreferredSize()}.
 162    *
 163    * @return the preferred size for the component
 164    */
 165   Dimension getPreferredSize();
 166
 167   /**
 168    * Returns the toolkit that created this peer.
 169    *
 170    * @return the toolkit that created this peer
 171    */
 172   Toolkit getToolkit();
 173
 174   /**
 175    * Handles the given event. This is called from
 176    * {@link Component#dispatchEvent(AWTEvent)} to give the peer a chance to
 177    * react to events for the component.
 178    *
 179    * @param e the event
 180    */
 181   void handleEvent(AWTEvent e);
 182
 183   /**
 184    * Makes the component invisible. This is called from
 185    * {@link Component#hide()}.
 186    */
 187   void hide();
 188
 189   /**
 190    * Returns <code>true</code> if the component can receive keyboard input
 191    * focus. This is called from {@link Component#isFocusTraversable()}.
 192    *
 193    * @specnote Part of the earlier 1.1 API, replaced by isFocusable().
 194    */
 195   boolean isFocusTraversable();
 196
 197   /**
 198    * Returns <code>true</code> if the component can receive keyboard input
 199    * focus. This is called from {@link Component#isFocusable()}.
 200    */
 201   boolean isFocusable();
 202
 203   /**
 204    * Returns the minimum size for the component. This is called by
 205    * {@link Component#minimumSize()}.
 206    *
 207    * @return the minimum size for the component
 208    */
 209   Dimension minimumSize();
 210
 211   /**
 212    * Returns the preferred size for the component. This is called by
 213    * {@link Component#getPreferredSize()}.
 214    *
 215    * @return the preferred size for the component
 216    */
 217   Dimension preferredSize();
 218
 219   void paint(Graphics graphics);
 220
 221   /**
 222    * Prepares an image for rendering on this component. This is called by
 223    * {@link Component#prepareImage(Image, int, int, ImageObserver)}.
 224    *
 225    * @param img the image to prepare
 226    * @param width the desired width of the rendered image
 227    * @param height the desired height of the rendered image
 228    * @param ob the image observer to be notified of updates in the preparation
 229    *        process
 230    *
 231    * @return <code>true</code> if the image has been fully prepared,
 232    *         <code>false</code> otherwise (in which case the image observer
 233    *         receives updates)
 234    */
 235   boolean prepareImage(Image img, int width, int height,
 236                               ImageObserver ob);
 237
 238   void print(Graphics graphics);
 239
 240   /**
 241    * Repaints the specified rectangle of this component. This is called from
 242    * {@link Component#repaint(long, int, int, int, int)}.
 243    *
 244    * @param tm number of milliseconds to wait with repainting
 245    * @param x the X coordinate of the upper left corner of the damaged rectangle
 246    * @param y the Y coordinate of the upper left corner of the damaged rectangle
 247    * @param width the width of the damaged rectangle
 248    * @param height the height of the damaged rectangle
 249    */
 250   void repaint(long tm, int x, int y, int width, int height);
 251
 252   /**
 253    * Requests that this component receives the focus. This is called from
 254    * {@link Component#requestFocus()}.
 255    *
 256    * @specnote Part of the earlier 1.1 API, apparently replaced by argument
 257    *           form of the same method.
 258    */
 259   void requestFocus();
 260
 261   /**
 262    * Requests that this component receives the focus. This is called from
 263    * {@link Component#requestFocus()}.
 264    *
 265    * @param source TODO
 266    * @param bool1 TODO
 267    * @param bool2 TODO
 268    * @param x TODO
 269    */
 270   boolean requestFocus(Component source, boolean bool1, boolean bool2, long x);
 271
 272   /**
 273    * Notifies the peer that the bounds of this component have changed. This
 274    * is called by {@link Component#reshape(int, int, int, int)}.
 275    *
 276    * @param x the X coordinate of the upper left corner of the component
 277    * @param y the Y coordinate of the upper left corner of the component
 278    * @param width the width of the component
 279    * @param height the height of the component
 280    */
 281   void reshape(int x, int y, int width, int height);
 282
 283   /**
 284    * Sets the background color of the component. This is called by
 285    * {@link Component#setBackground(Color)}.
 286    *
 287    * @param color the background color to set
 288    */
 289   void setBackground(Color color);
 290
 291   /**
 292    * Notifies the peer that the bounds of this component have changed. This
 293    * is called by {@link Component#setBounds(int, int, int, int)}.
 294    *
 295    * @param x the X coordinate of the upper left corner of the component
 296    * @param y the Y coordinate of the upper left corner of the component
 297    * @param width the width of the component
 298    * @param height the height of the component
 299    */
 300   void setBounds(int x, int y, int width, int height);
 301
 302   /**
 303    * Sets the cursor of the component. This is called by
 304    * {@link Component#setCursor(Cursor)}.
 305    *
 306    * @specnote Part of the earlier 1.1 API, apparently no longer needed.
 307    */
 308   void setCursor(Cursor cursor);
 309
 310   /**
 311    * Sets the enabled/disabled state of this component. This is called by
 312    * {@link Component#setEnabled(boolean)}.
 313    *
 314    * @param enabled <code>true</code> to enable the component,
 315    *        <code>false</code> to disable it
 316    */
 317   void setEnabled(boolean enabled);
 318
 319   /**
 320    * Sets the font of the component. This is called by
 321    * {@link Component#setFont(Font)}.
 322    *
 323    * @param font the font to set
 324    */
 325   void setFont(Font font);
 326
 327   /**
 328    * Sets the foreground color of the component. This is called by
 329    * {@link Component#setForeground(Color)}.
 330    *
 331    * @param color the foreground color to set
 332    */
 333   void setForeground(Color color);
 334
 335   /**
 336    * Sets the visibility state of the component. This is called by
 337    * {@link Component#setVisible(boolean)}.
 338    *
 339    * @param visible <code>true</code> to make the component visible,
 340    *        <code>false</code> to make it invisible
 341    */
 342   void setVisible(boolean visible);
 343
 344   /**
 345    * Makes the component visible. This is called by {@link Component#show()}.
 346    */
 347   void show();
 348
 349   /**
 350    * Get the graphics configuration of the component. The color model
 351    * of the component can be derived from the configuration.
 352    *
 353    * @return the graphics configuration of the component
 354    */
 355   GraphicsConfiguration getGraphicsConfiguration();
 356
 357   /**
 358    * Part of an older API, no longer needed.
 359    */
 360   void setEventMask(long mask);
 361
 362   /**
 363    * Returns <code>true</code> if this component has been obscured,
 364    * <code>false</code> otherwise. This will only work if
 365    * {@link #canDetermineObscurity()} also returns <code>true</code>.
 366    *
 367    * @return <code>true</code> if this component has been obscured,
 368    *         <code>false</code> otherwise.
 369    */
 370   boolean isObscured();
 371
 372   /**
 373    * Returns <code>true</code> if this component peer can determine if the
 374    * component has been obscured, <code>false</code> otherwise.
 375    *
 376    * @return <code>true</code> if this component peer can determine if the
 377    *         component has been obscured, <code>false</code> otherwise
 378    */
 379   boolean canDetermineObscurity();
 380
 381   /**
 382    * Coalesces the specified paint event.
 383    *
 384    * @param e the paint event
 385    */
 386   void coalescePaintEvent(PaintEvent e);
 387
 388   /**
 389    * Updates the cursor.
 390    */
 391   void updateCursorImmediately();
 392
 393   /**
 394    * Returns true, if this component can handle wheel scrolling,
 395    * <code>false</code> otherwise.
 396    *
 397    * @return true, if this component can handle wheel scrolling,
 398    *         <code>false</code> otherwise
 399    */
 400   boolean handlesWheelScrolling();
 401
 402   /**
 403    * A convenience method that creates a volatile image.  The volatile
 404    * image is created on the screen device on which this component is
 405    * displayed, in the device's current graphics configuration.
 406    *
 407    * @param width width of the image
 408    * @param height height of the image
 409    *
 410    * @see VolatileImage
 411    *
 412    * @since 1.2
 413    */
 414   VolatileImage createVolatileImage(int width, int height);
 415
 416   /**
 417    * Create a number of image buffers that implement a buffering
 418    * strategy according to the given capabilities.
 419    *
 420    * @param numBuffers the number of buffers
 421    * @param caps the buffering capabilities
 422    *
 423    * @throws AWTException if the specified buffering strategy is not
 424    * implemented
 425    *
 426    * @since 1.2
 427    */
 428   void createBuffers(int numBuffers, BufferCapabilities caps)
 429     throws AWTException;
 430
 431   /**
 432    * Return the back buffer of this component.
 433    *
 434    * @return the back buffer of this component.
 435    *
 436    * @since 1.2
 437    */
 438   Image getBackBuffer();
 439
 440   /**
 441    * Perform a page flip, leaving the contents of the back buffer in
 442    * the specified state.
 443    *
 444    * @param contents the state in which to leave the back buffer
 445    *
 446    * @since 1.2
 447    */
 448   void flip(BufferCapabilities.FlipContents contents);
 449
 450   /**
 451    * Destroy the resources created by createBuffers.
 452    *
 453    * @since 1.2
 454    */
 455   void destroyBuffers();
 456
 457   /**
 458    * Get the bounds of this component peer.
 459    *
 460    * @return component peer bounds
 461    * @since 1.5
 462    */
 463   Rectangle getBounds();
 464
 465   /**
 466    * Reparent this component under another container.
 467    *
 468    * @param parent
 469    * @since 1.5
 470    */
 471   void reparent(ContainerPeer parent);
 472
 473   /**
 474    * Set the bounds of this component peer.
 475    *
 476    * @param x the new x co-ordinate
 477    * @param y the new y co-ordinate
 478    * @param width the new width
 479    * @param height the new height
 480    * @param z the new stacking level
 481    * @since 1.5
 482    */
 483   void setBounds (int x, int y, int width, int height, int z);
 484
 485   /**
 486    * Check if this component supports being reparented.
 487    *
 488    * @return true if this component can be reparented,
 489    * false otherwise.
 490    * @since 1.5
 491    */
 492   boolean isReparentSupported();
 493
 494   /**
 495    * Layout this component peer.
 496    *
 497    * @since 1.5
 498    */
 499   void layout();
 500 }