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 */ checkImage(Image img, int width, int height, ImageObserver ob)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 */ createImage(ImageProducer prod)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 */ createImage(int width, int height)102 Image createImage(int width, int height); 103 104 /** 105 * Disables the component. This is called by {@link Component#disable()}. 106 */ disable()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 */ dispose()113 void dispose(); 114 115 /** 116 * Enables the component. This is called by {@link Component#enable()}. 117 */ enable()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 */ getColorModel()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 */ getFontMetrics(Font f)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 */ getGraphics()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 */ getLocationOnScreen()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 */ getMinimumSize()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 */ getPreferredSize()179 Dimension getPreferredSize(); 180 181 /** 182 * Returns the toolkit that created this peer. 183 * 184 * @return the toolkit that created this peer 185 */ getToolkit()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 */ handleEvent(AWTEvent e)195 void handleEvent(AWTEvent e); 196 197 /** 198 * Makes the component invisible. This is called from 199 * {@link Component#hide()}. 200 */ hide()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 */ isFocusTraversable()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 */ isFocusable()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 */ minimumSize()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 */ preferredSize()231 Dimension preferredSize(); 232 paint(Graphics graphics)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 */ prepareImage(Image img, int width, int height, ImageObserver ob)249 boolean prepareImage(Image img, int width, int height, 250 ImageObserver ob); 251 print(Graphics graphics)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 */ repaint(long tm, int x, int y, int width, int height)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 */ requestFocus()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 */ requestFocus(Component request, boolean temporary, boolean allowWindowFocus, long time)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 */ reshape(int x, int y, int width, int height)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 */ setBackground(Color color)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 */ setBounds(int x, int y, int width, int height)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 */ setCursor(Cursor cursor)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 */ setEnabled(boolean enabled)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 */ setFont(Font font)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 */ setForeground(Color color)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 */ setVisible(boolean visible)365 void setVisible(boolean visible); 366 367 /** 368 * Makes the component visible. This is called by {@link Component#show()}. 369 */ show()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 */ getGraphicsConfiguration()378 GraphicsConfiguration getGraphicsConfiguration(); 379 380 /** 381 * Part of an older API, no longer needed. 382 */ setEventMask(long mask)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 */ isObscured()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 */ canDetermineObscurity()402 boolean canDetermineObscurity(); 403 404 /** 405 * Coalesces the specified paint event. 406 * 407 * @param e the paint event 408 */ coalescePaintEvent(PaintEvent e)409 void coalescePaintEvent(PaintEvent e); 410 411 /** 412 * Updates the cursor. 413 */ updateCursorImmediately()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 */ handlesWheelScrolling()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 */ createVolatileImage(int width, int height)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 */ createBuffers(int numBuffers, BufferCapabilities caps)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 */ getBackBuffer()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 */ flip(BufferCapabilities.FlipContents contents)471 void flip(BufferCapabilities.FlipContents contents); 472 473 /** 474 * Destroy the resources created by createBuffers. 475 * 476 * @since 1.2 477 */ destroyBuffers()478 void destroyBuffers(); 479 480 /** 481 * Get the bounds of this component peer. 482 * 483 * @return component peer bounds 484 * @since 1.5 485 */ getBounds()486 Rectangle getBounds(); 487 488 /** 489 * Reparent this component under another container. 490 * 491 * @param parent 492 * @since 1.5 493 */ reparent(ContainerPeer parent)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 */ setBounds(int x, int y, int width, int height, int z)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 */ isReparentSupported()515 boolean isReparentSupported(); 516 517 /** 518 * Layout this component peer. 519 * 520 * @since 1.5 521 */ layout()522 void layout(); 523 524 525 /** 526 * Requests the focus on the component. 527 */ requestFocus(Component lightweightChild, boolean temporary, boolean focusedWindowChangeAllowed, long time, CausedFocusEvent.Cause cause)528 boolean requestFocus(Component lightweightChild, boolean temporary, 529 boolean focusedWindowChangeAllowed, long time, 530 CausedFocusEvent.Cause cause); 531 532 } 533