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