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 import sun.awt.CausedFocusEvent;
  63
  64 /**
  65  * Defines the methods that a component peer is required to implement.
  66  */
  67 public interface ComponentPeer
  68 {
  69   /**
  70    * Returns the construction status of the specified image. This is called
  71    * by {@link Component#checkImage(Image, int, int, ImageObserver)}.
  72    *
  73    * @param img the image
  74    * @param width the width of the image
  75    * @param height the height of the image
  76    * @param ob the image observer to be notified of updates of the status
  77    *
  78    * @return a bitwise ORed set of ImageObserver flags
  79    */
  80   int checkImage(Image img, int width, int height,
  81                  ImageObserver ob);
  82
  83   /**
  84    * Creates an image by starting the specified image producer. This is called
  85    * by {@link Component#createImage(ImageProducer)}.
  86    *
  87    * @param prod the image producer to be used to create the image
  88    *
  89    * @return the created image
  90    */
  91   Image createImage(ImageProducer prod);
  92
  93   /**
  94    * Creates an empty image with the specified <code>width</code> and
  95    * <code>height</code>.
  96    *
  97    * @param width the width of the image to be created
  98    * @param height the height of the image to be created
  99    *
 100    * @return the created image
 101    */
 102   Image createImage(int width, int height);
 103
 104   /**
 105    * Disables the component. This is called by {@link Component#disable()}.
 106    */
 107   void disable();
 108
 109   /**
 110    * Disposes the component peer. This should release all resources held by the
 111    * peer. This is called when the component is no longer in use.
 112    */
 113   void dispose();
 114
 115   /**
 116    * Enables the component. This is called by {@link Component#enable()}.
 117    */
 118   void enable();
 119
 120   /**
 121    * Returns the color model of the component. This is currently not used.
 122    *
 123    * @return the color model of the component
 124    */
 125   ColorModel getColorModel();
 126
 127   /**
 128    * Returns the font metrics for the specified font. This is called by
 129    * {@link Component#getFontMetrics(Font)}.
 130    *
 131    * @param f the font for which to query the font metrics
 132    *
 133    * @return the font metrics for the specified font
 134    */
 135   FontMetrics getFontMetrics(Font f);
 136
 137   /**
 138    * Returns a {@link Graphics} object suitable for drawing on this component.
 139    * This is called by {@link Component#getGraphics()}.
 140    *
 141    * @return a graphics object suitable for drawing on this component
 142    */
 143   Graphics getGraphics();
 144
 145   /**
 146    * Returns the location of this component in screen coordinates. This is
 147    * called by {@link Component#getLocationOnScreen()}.
 148    *
 149    * @return the location of this component in screen coordinates
 150    */
 151   Point getLocationOnScreen();
 152
 153   /**
 154    * Returns the minimum size for the component. This is called by
 155    * {@link Component#getMinimumSize()}.
 156    *
 157    * @return the minimum size for the component
 158    *
 159    * @specnote Presumably this method got added to replace minimumSize().
 160    *           However, testing shows that this is never called in the RI
 161    *           (tested with JDK5), but instead minimumSize() is called
 162    *           directly. It is advisable to implement this method to delegate
 163    *           to minimumSize() and put the real implementation in there.
 164    */
 165   Dimension getMinimumSize();
 166
 167   /**
 168    * Returns the preferred size for the component. This is called by
 169    * {@link Component#getPreferredSize()}.
 170    *
 171    * @return the preferred size for the component
 172    *
 173    * @specnote Presumably this method got added to replace preferredSize().
 174    *           However, testing shows that this is never called in the RI
 175    *           (tested with JDK5), but instead preferredSize() is called
 176    *           directly. It is advisable to implement this method to delegate
 177    *           to preferredSize() and put the real implementation in there.
 178    */
 179   Dimension getPreferredSize();
 180
 181   /**
 182    * Returns the toolkit that created this peer.
 183    *
 184    * @return the toolkit that created this peer
 185    */
 186   Toolkit getToolkit();
 187
 188   /**
 189    * Handles the given event. This is called from
 190    * {@link Component#dispatchEvent(AWTEvent)} to give the peer a chance to
 191    * react to events for the component.
 192    *
 193    * @param e the event
 194    */
 195   void handleEvent(AWTEvent e);
 196
 197   /**
 198    * Makes the component invisible. This is called from
 199    * {@link Component#hide()}.
 200    */
 201   void hide();
 202
 203   /**
 204    * Returns <code>true</code> if the component can receive keyboard input
 205    * focus. This is called from {@link Component#isFocusTraversable()}.
 206    *
 207    * @specnote Part of the earlier 1.1 API, replaced by isFocusable().
 208    */
 209   boolean isFocusTraversable();
 210
 211   /**
 212    * Returns <code>true</code> if the component can receive keyboard input
 213    * focus. This is called from {@link Component#isFocusable()}.
 214    */
 215   boolean isFocusable();
 216
 217   /**
 218    * Returns the minimum size for the component. This is called by
 219    * {@link Component#minimumSize()}.
 220    *
 221    * @return the minimum size for the component
 222    */
 223   Dimension minimumSize();
 224
 225   /**
 226    * Returns the preferred size for the component. This is called by
 227    * {@link Component#getPreferredSize()}.
 228    *
 229    * @return the preferred size for the component
 230    */
 231   Dimension preferredSize();
 232
 233   void paint(Graphics graphics);
 234
 235   /**
 236    * Prepares an image for rendering on this component. This is called by
 237    * {@link Component#prepareImage(Image, int, int, ImageObserver)}.
 238    *
 239    * @param img the image to prepare
 240    * @param width the desired width of the rendered image
 241    * @param height the desired height of the rendered image
 242    * @param ob the image observer to be notified of updates in the preparation
 243    *        process
 244    *
 245    * @return <code>true</code> if the image has been fully prepared,
 246    *         <code>false</code> otherwise (in which case the image observer
 247    *         receives updates)
 248    */
 249   boolean prepareImage(Image img, int width, int height,
 250                               ImageObserver ob);
 251
 252   void print(Graphics graphics);
 253
 254   /**
 255    * Repaints the specified rectangle of this component. This is called from
 256    * {@link Component#repaint(long, int, int, int, int)}.
 257    *
 258    * @param tm number of milliseconds to wait with repainting
 259    * @param x the X coordinate of the upper left corner of the damaged rectangle
 260    * @param y the Y coordinate of the upper left corner of the damaged rectangle
 261    * @param width the width of the damaged rectangle
 262    * @param height the height of the damaged rectangle
 263    */
 264   void repaint(long tm, int x, int y, int width, int height);
 265
 266   /**
 267    * Requests that this component receives the focus. This is called from
 268    * {@link Component#requestFocus()}.
 269    *
 270    * @specnote Part of the earlier 1.1 API, apparently replaced by argument
 271    *           form of the same method.
 272    */
 273   void requestFocus();
 274
 275   /**
 276    * Requests that this component receives the focus. This is called from
 277    * {@link Component#requestFocus()}.
 278    *
 279    * This method is only called for heavyweight component's peers. Lightweight
 280    * components ask their nearest heavyweight component to request focus.
 281    * It's up to the heavyweight peer to decide if any of it's lightweight
 282    * descendants are allowed to receive keyboard input focus or not. If the
 283    * focus request is finally approved, then the peer must post a FOCUS_GAINED
 284    * event for the requested component.
 285    *
 286    * @param request the component for which the focus is requested
 287    * @param temporary indicates if the focus change is temporary (true) or
 288    *        permanent (false)
 289    * @param allowWindowFocus indicates if it's allowed to change window focus
 290    * @param time the timestamp
 291    */
 292   boolean requestFocus(Component request, boolean temporary,
 293                        boolean allowWindowFocus, long time);
 294
 295   /**
 296    * Notifies the peer that the bounds of this component have changed. This
 297    * is called by {@link Component#reshape(int, int, int, int)}.
 298    *
 299    * @param x the X coordinate of the upper left corner of the component
 300    * @param y the Y coordinate of the upper left corner of the component
 301    * @param width the width of the component
 302    * @param height the height of the component
 303    */
 304   void reshape(int x, int y, int width, int height);
 305
 306   /**
 307    * Sets the background color of the component. This is called by
 308    * {@link Component#setBackground(Color)}.
 309    *
 310    * @param color the background color to set
 311    */
 312   void setBackground(Color color);
 313
 314   /**
 315    * Notifies the peer that the bounds of this component have changed. This
 316    * is called by {@link Component#setBounds(int, int, int, int)}.
 317    *
 318    * @param x the X coordinate of the upper left corner of the component
 319    * @param y the Y coordinate of the upper left corner of the component
 320    * @param width the width of the component
 321    * @param height the height of the component
 322    */
 323   void setBounds(int x, int y, int width, int height);
 324
 325   /**
 326    * Sets the cursor of the component. This is called by
 327    * {@link Component#setCursor(Cursor)}.
 328    *
 329    * @specnote Part of the earlier 1.1 API, apparently no longer needed.
 330    */
 331   void setCursor(Cursor cursor);
 332
 333   /**
 334    * Sets the enabled/disabled state of this component. This is called by
 335    * {@link Component#setEnabled(boolean)}.
 336    *
 337    * @param enabled <code>true</code> to enable the component,
 338    *        <code>false</code> to disable it
 339    */
 340   void setEnabled(boolean enabled);
 341
 342   /**
 343    * Sets the font of the component. This is called by
 344    * {@link Component#setFont(Font)}.
 345    *
 346    * @param font the font to set
 347    */
 348   void setFont(Font font);
 349
 350   /**
 351    * Sets the foreground color of the component. This is called by
 352    * {@link Component#setForeground(Color)}.
 353    *
 354    * @param color the foreground color to set
 355    */
 356   void setForeground(Color color);
 357
 358   /**
 359    * Sets the visibility state of the component. This is called by
 360    * {@link Component#setVisible(boolean)}.
 361    *
 362    * @param visible <code>true</code> to make the component visible,
 363    *        <code>false</code> to make it invisible
 364    */
 365   void setVisible(boolean visible);
 366
 367   /**
 368    * Makes the component visible. This is called by {@link Component#show()}.
 369    */
 370   void show();
 371
 372   /**
 373    * Get the graphics configuration of the component. The color model
 374    * of the component can be derived from the configuration.
 375    *
 376    * @return the graphics configuration of the component
 377    */
 378   GraphicsConfiguration getGraphicsConfiguration();
 379
 380   /**
 381    * Part of an older API, no longer needed.
 382    */
 383   void setEventMask(long mask);
 384
 385   /**
 386    * Returns <code>true</code> if this component has been obscured,
 387    * <code>false</code> otherwise. This will only work if
 388    * {@link #canDetermineObscurity()} also returns <code>true</code>.
 389    *
 390    * @return <code>true</code> if this component has been obscured,
 391    *         <code>false</code> otherwise.
 392    */
 393   boolean isObscured();
 394
 395   /**
 396    * Returns <code>true</code> if this component peer can determine if the
 397    * component has been obscured, <code>false</code> otherwise.
 398    *
 399    * @return <code>true</code> if this component peer can determine if the
 400    *         component has been obscured, <code>false</code> otherwise
 401    */
 402   boolean canDetermineObscurity();
 403
 404   /**
 405    * Coalesces the specified paint event.
 406    *
 407    * @param e the paint event
 408    */
 409   void coalescePaintEvent(PaintEvent e);
 410
 411   /**
 412    * Updates the cursor.
 413    */
 414   void updateCursorImmediately();
 415
 416   /**
 417    * Returns true, if this component can handle wheel scrolling,
 418    * <code>false</code> otherwise.
 419    *
 420    * @return true, if this component can handle wheel scrolling,
 421    *         <code>false</code> otherwise
 422    */
 423   boolean handlesWheelScrolling();
 424
 425   /**
 426    * A convenience method that creates a volatile image.  The volatile
 427    * image is created on the screen device on which this component is
 428    * displayed, in the device's current graphics configuration.
 429    *
 430    * @param width width of the image
 431    * @param height height of the image
 432    *
 433    * @see VolatileImage
 434    *
 435    * @since 1.2
 436    */
 437   VolatileImage createVolatileImage(int width, int height);
 438
 439   /**
 440    * Create a number of image buffers that implement a buffering
 441    * strategy according to the given capabilities.
 442    *
 443    * @param numBuffers the number of buffers
 444    * @param caps the buffering capabilities
 445    *
 446    * @throws AWTException if the specified buffering strategy is not
 447    * implemented
 448    *
 449    * @since 1.2
 450    */
 451   void createBuffers(int numBuffers, BufferCapabilities caps)
 452     throws AWTException;
 453
 454   /**
 455    * Return the back buffer of this component.
 456    *
 457    * @return the back buffer of this component.
 458    *
 459    * @since 1.2
 460    */
 461   Image getBackBuffer();
 462
 463   /**
 464    * Perform a page flip, leaving the contents of the back buffer in
 465    * the specified state.
 466    *
 467    * @param contents the state in which to leave the back buffer
 468    *
 469    * @since 1.2
 470    */
 471   void flip(BufferCapabilities.FlipContents contents);
 472
 473   /**
 474    * Destroy the resources created by createBuffers.
 475    *
 476    * @since 1.2
 477    */
 478   void destroyBuffers();
 479
 480   /**
 481    * Get the bounds of this component peer.
 482    *
 483    * @return component peer bounds
 484    * @since 1.5
 485    */
 486   Rectangle getBounds();
 487
 488   /**
 489    * Reparent this component under another container.
 490    *
 491    * @param parent
 492    * @since 1.5
 493    */
 494   void reparent(ContainerPeer parent);
 495
 496   /**
 497    * Set the bounds of this component peer.
 498    *
 499    * @param x the new x co-ordinate
 500    * @param y the new y co-ordinate
 501    * @param width the new width
 502    * @param height the new height
 503    * @param z the new stacking level
 504    * @since 1.5
 505    */
 506   void setBounds (int x, int y, int width, int height, int z);
 507
 508   /**
 509    * Check if this component supports being reparented.
 510    *
 511    * @return true if this component can be reparented,
 512    * false otherwise.
 513    * @since 1.5
 514    */
 515   boolean isReparentSupported();
 516
 517   /**
 518    * Layout this component peer.
 519    *
 520    * @since 1.5
 521    */
 522   void layout();
 523
 524
 525   /**
 526    * Requests the focus on the component.
 527    */
 528   boolean requestFocus(Component lightweightChild, boolean temporary,
 529                        boolean focusedWindowChangeAllowed, long time,
 530                        CausedFocusEvent.Cause cause);
 531
 532 }