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