Source for java.awt.peer.ComponentPeer

   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: }