1 /* 2 * Copyright (c) 1995, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.awt.peer; 27 28 import java.awt.*; 29 import java.awt.event.PaintEvent; 30 import java.awt.event.FocusEvent.Cause; 31 import java.awt.image.ColorModel; 32 import java.awt.image.ImageObserver; 33 import java.awt.image.ImageProducer; 34 import java.awt.image.VolatileImage; 35 36 import sun.java2d.pipe.Region; 37 38 39 /** 40 * The peer interface for {@link Component}. This is the top level peer 41 * interface for widgets and defines the bulk of methods for AWT component 42 * peers. Most component peers have to implement this interface (via one 43 * of the subinterfaces), except menu components, which implement 44 * {@link MenuComponentPeer}. 45 * 46 * The peer interfaces are intended only for use in porting 47 * the AWT. They are not intended for use by application 48 * developers, and developers should not implement peers 49 * nor invoke any of the peer methods directly on the peer 50 * instances. 51 */ 52 public interface ComponentPeer { 53 54 /** 55 * Operation for {@link #setBounds(int, int, int, int, int)}, indicating 56 * a change in the component location only. 57 * 58 * @see #setBounds(int, int, int, int, int) 59 */ 60 public static final int SET_LOCATION = 1; 61 62 /** 63 * Operation for {@link #setBounds(int, int, int, int, int)}, indicating 64 * a change in the component size only. 65 * 66 * @see #setBounds(int, int, int, int, int) 67 */ 68 public static final int SET_SIZE = 2; 69 70 /** 71 * Operation for {@link #setBounds(int, int, int, int, int)}, indicating 72 * a change in the component size and location. 73 * 74 * @see #setBounds(int, int, int, int, int) 75 */ 76 public static final int SET_BOUNDS = 3; 77 78 /** 79 * Operation for {@link #setBounds(int, int, int, int, int)}, indicating 80 * a change in the component client size. This is used for setting 81 * the 'inside' size of windows, without the border insets. 82 * 83 * @see #setBounds(int, int, int, int, int) 84 */ 85 public static final int SET_CLIENT_SIZE = 4; 86 87 /** 88 * Resets the setBounds() operation to DEFAULT_OPERATION. This is not 89 * passed into {@link #setBounds(int, int, int, int, int)}. 90 * 91 * TODO: This is only used internally and should probably be moved outside 92 * the peer interface. 93 * 94 * @see Component#setBoundsOp 95 */ 96 public static final int RESET_OPERATION = 5; 97 98 /** 99 * A flag that is used to suppress checks for embedded frames. 100 * 101 * TODO: This is only used internally and should probably be moved outside 102 * the peer interface. 103 */ 104 public static final int NO_EMBEDDED_CHECK = (1 << 14); 105 106 /** 107 * The default operation, which is to set size and location. 108 * 109 * TODO: This is only used internally and should probably be moved outside 110 * the peer interface. 111 * 112 * @see Component#setBoundsOp 113 */ 114 public static final int DEFAULT_OPERATION = SET_BOUNDS; 115 116 /** 117 * Determines if a component has been obscured, i.e. by an overlapping 118 * window or similar. This is used by JViewport for optimizing performance. 119 * This doesn't have to be implemented, when 120 * {@link #canDetermineObscurity()} returns {@code false}. 121 * 122 * @return {@code true} when the component has been obscured, 123 * {@code false} otherwise 124 * 125 * @see #canDetermineObscurity() 126 * @see javax.swing.JViewport#needsRepaintAfterBlit 127 */ 128 boolean isObscured(); 129 130 /** 131 * Returns {@code true} when the peer can determine if a component 132 * has been obscured, {@code false} false otherwise. 133 * 134 * @return {@code true} when the peer can determine if a component 135 * has been obscured, {@code false} false otherwise 136 * 137 * @see #isObscured() 138 * @see javax.swing.JViewport#needsRepaintAfterBlit 139 */ 140 boolean canDetermineObscurity(); 141 142 /** 143 * Makes a component visible or invisible. 144 * 145 * @param v {@code true} to make a component visible, 146 * {@code false} to make it invisible 147 * 148 * @see Component#setVisible(boolean) 149 */ 150 void setVisible(boolean v); 151 152 /** 153 * Enables or disables a component. Disabled components are usually grayed 154 * out and cannot be activated. 155 * 156 * @param e {@code true} to enable the component, {@code false} 157 * to disable it 158 * 159 * @see Component#setEnabled(boolean) 160 */ 161 void setEnabled(boolean e); 162 163 /** 164 * Paints the component to the specified graphics context. This is called 165 * by {@link Component#paintAll(Graphics)} to paint the component. 166 * 167 * @param g the graphics context to paint to 168 * 169 * @see Component#paintAll(Graphics) 170 */ 171 void paint(Graphics g); 172 173 /** 174 * Prints the component to the specified graphics context. This is called 175 * by {@link Component#printAll(Graphics)} to print the component. 176 * 177 * @param g the graphics context to print to 178 * 179 * @see Component#printAll(Graphics) 180 */ 181 void print(Graphics g); 182 183 /** 184 * Sets the location or size or both of the component. The location is 185 * specified relative to the component's parent. The {@code op} 186 * parameter specifies which properties change. If it is 187 * {@link #SET_LOCATION}, then only the location changes (and the size 188 * parameters can be ignored). If {@code op} is {@link #SET_SIZE}, 189 * then only the size changes (and the location can be ignored). If 190 * {@code op} is {@link #SET_BOUNDS}, then both change. There is a 191 * special value {@link #SET_CLIENT_SIZE}, which is used only for 192 * window-like components to set the size of the client (i.e. the 'inner' 193 * size, without the insets of the window borders). 194 * 195 * @param x the X location of the component 196 * @param y the Y location of the component 197 * @param width the width of the component 198 * @param height the height of the component 199 * @param op the operation flag 200 * 201 * @see #SET_BOUNDS 202 * @see #SET_LOCATION 203 * @see #SET_SIZE 204 * @see #SET_CLIENT_SIZE 205 */ 206 void setBounds(int x, int y, int width, int height, int op); 207 208 /** 209 * Called to let the component peer handle events. 210 * 211 * @param e the AWT event to handle 212 * 213 * @see Component#dispatchEvent(AWTEvent) 214 */ 215 void handleEvent(AWTEvent e); 216 217 /** 218 * Called to coalesce paint events. 219 * 220 * @param e the paint event to consider to coalesce 221 * 222 * @see EventQueue#coalescePaintEvent 223 */ 224 void coalescePaintEvent(PaintEvent e); 225 226 /** 227 * Determines the location of the component on the screen. 228 * 229 * @return the location of the component on the screen 230 * 231 * @see Component#getLocationOnScreen() 232 */ 233 Point getLocationOnScreen(); 234 235 /** 236 * Determines the preferred size of the component. 237 * 238 * @return the preferred size of the component 239 * 240 * @see Component#getPreferredSize() 241 */ 242 Dimension getPreferredSize(); 243 244 /** 245 * Determines the minimum size of the component. 246 * 247 * @return the minimum size of the component 248 * 249 * @see Component#getMinimumSize() 250 */ 251 Dimension getMinimumSize(); 252 253 /** 254 * Returns the color model used by the component. 255 * 256 * @return the color model used by the component 257 * 258 * @see Component#getColorModel() 259 */ 260 ColorModel getColorModel(); 261 262 /** 263 * Returns a graphics object to paint on the component. 264 * 265 * @return a graphics object to paint on the component 266 * 267 * @see Component#getGraphics() 268 */ 269 // TODO: Maybe change this to force Graphics2D, since many things will 270 // break with plain Graphics nowadays. 271 Graphics getGraphics(); 272 273 /** 274 * Returns a font metrics object to determine the metrics properties of 275 * the specified font. 276 * 277 * @param font the font to determine the metrics for 278 * 279 * @return a font metrics object to determine the metrics properties of 280 * the specified font 281 * 282 * @see Component#getFontMetrics(Font) 283 */ 284 FontMetrics getFontMetrics(Font font); 285 286 /** 287 * Disposes all resources held by the component peer. This is called 288 * when the component has been disconnected from the component hierarchy 289 * and is about to be garbage collected. 290 * 291 * @see Component#removeNotify() 292 */ 293 void dispose(); 294 295 /** 296 * Sets the foreground color of this component. 297 * 298 * @param c the foreground color to set 299 * 300 * @see Component#setForeground(Color) 301 */ 302 void setForeground(Color c); 303 304 /** 305 * Sets the background color of this component. 306 * 307 * @param c the background color to set 308 * 309 * @see Component#setBackground(Color) 310 */ 311 void setBackground(Color c); 312 313 /** 314 * Sets the font of this component. 315 * 316 * @param f the font of this component 317 * 318 * @see Component#setFont(Font) 319 */ 320 void setFont(Font f); 321 322 /** 323 * Updates the cursor of the component. 324 * 325 * @see Component#updateCursorImmediately 326 */ 327 void updateCursorImmediately(); 328 329 /** 330 * Requests focus on this component. 331 * 332 * @param lightweightChild the actual lightweight child that requests the 333 * focus 334 * @param temporary {@code true} if the focus change is temporary, 335 * {@code false} otherwise 336 * @param focusedWindowChangeAllowed {@code true} if changing the 337 * focus of the containing window is allowed or not 338 * @param time the time of the focus change request 339 * @param cause the cause of the focus change request 340 * 341 * @return {@code true} if the focus change is guaranteed to be 342 * granted, {@code false} otherwise 343 */ 344 boolean requestFocus(Component lightweightChild, boolean temporary, 345 boolean focusedWindowChangeAllowed, long time, 346 Cause cause); 347 348 /** 349 * Returns {@code true} when the component takes part in the focus 350 * traversal, {@code false} otherwise. 351 * 352 * @return {@code true} when the component takes part in the focus 353 * traversal, {@code false} otherwise 354 */ 355 boolean isFocusable(); 356 357 /** 358 * Creates an image using the specified image producer. 359 * 360 * @param producer the image producer from which the image pixels will be 361 * produced 362 * 363 * @return the created image 364 * 365 * @see Component#createImage(ImageProducer) 366 */ 367 Image createImage(ImageProducer producer); 368 369 /** 370 * Creates an empty image with the specified width and height. This is 371 * generally used as a non-accelerated backbuffer for drawing onto the 372 * component (e.g. by Swing). 373 * 374 * @param width the width of the image 375 * @param height the height of the image 376 * 377 * @return the created image 378 * 379 * @see Component#createImage(int, int) 380 */ 381 // TODO: Maybe make that return a BufferedImage, because some stuff will 382 // break if a different kind of image is returned. 383 Image createImage(int width, int height); 384 385 /** 386 * Creates an empty volatile image with the specified width and height. 387 * This is generally used as an accelerated backbuffer for drawing onto 388 * the component (e.g. by Swing). 389 * 390 * @param width the width of the image 391 * @param height the height of the image 392 * 393 * @return the created volatile image 394 * 395 * @see Component#createVolatileImage(int, int) 396 */ 397 // TODO: Include capabilities here and fix Component#createVolatileImage 398 VolatileImage createVolatileImage(int width, int height); 399 400 /** 401 * Prepare the specified image for rendering on this component. This should 402 * start loading the image (if not already loaded) and create an 403 * appropriate screen representation. 404 * 405 * @param img the image to prepare 406 * @param w the width of the screen representation 407 * @param h the height of the screen representation 408 * @param o an image observer to observe the progress 409 * 410 * @return {@code true} if the image is already fully prepared, 411 * {@code false} otherwise 412 * 413 * @see Component#prepareImage(Image, int, int, ImageObserver) 414 */ 415 boolean prepareImage(Image img, int w, int h, ImageObserver o); 416 417 /** 418 * Determines the status of the construction of the screen representation 419 * of the specified image. 420 * 421 * @param img the image to check 422 * @param w the target width 423 * @param h the target height 424 * @param o the image observer to notify 425 * 426 * @return the status as bitwise ORed ImageObserver flags 427 * 428 * @see Component#checkImage(Image, int, int, ImageObserver) 429 */ 430 int checkImage(Image img, int w, int h, ImageObserver o); 431 432 /** 433 * Returns the graphics configuration that corresponds to this component. 434 * 435 * @return the graphics configuration that corresponds to this component 436 * 437 * @see Component#getGraphicsConfiguration() 438 */ 439 GraphicsConfiguration getGraphicsConfiguration(); 440 441 /** 442 * Determines if the component handles wheel scrolling itself. Otherwise 443 * it is delegated to the component's parent. 444 * 445 * @return {@code true} if the component handles wheel scrolling, 446 * {@code false} otherwise 447 * 448 * @see Component#dispatchEventImpl(AWTEvent) 449 */ 450 boolean handlesWheelScrolling(); 451 452 /** 453 * Create {@code numBuffers} flipping buffers with the specified 454 * buffer capabilities. 455 * 456 * @param numBuffers the number of buffers to create 457 * @param caps the buffer capabilities 458 * 459 * @throws AWTException if flip buffering is not supported 460 */ 461 void createBuffers(int numBuffers, BufferCapabilities caps) 462 throws AWTException; 463 464 /** 465 * Returns the back buffer as image. 466 * 467 * @return the back buffer as image 468 */ 469 Image getBackBuffer(); 470 471 /** 472 * Move the back buffer to the front buffer. 473 * 474 * @param x1 the area to be flipped, upper left X coordinate 475 * @param y1 the area to be flipped, upper left Y coordinate 476 * @param x2 the area to be flipped, lower right X coordinate 477 * @param y2 the area to be flipped, lower right Y coordinate 478 * @param flipAction the flip action to perform 479 */ 480 void flip(int x1, int y1, int x2, int y2, BufferCapabilities.FlipContents flipAction); 481 482 /** 483 * Destroys all created buffers. 484 */ 485 void destroyBuffers(); 486 487 /** 488 * Reparents this peer to the new parent referenced by 489 * {@code newContainer} peer. Implementation depends on toolkit and 490 * container. 491 * 492 * @param newContainer peer of the new parent container 493 * 494 * @since 1.5 495 */ 496 void reparent(ContainerPeer newContainer); 497 498 /** 499 * Returns whether this peer supports reparenting to another parent without 500 * destroying the peer. 501 * 502 * @return true if appropriate reparent is supported, false otherwise 503 * 504 * @since 1.5 505 */ 506 boolean isReparentSupported(); 507 508 /** 509 * Used by lightweight implementations to tell a ComponentPeer to layout 510 * its sub-elements. For instance, a lightweight Checkbox needs to layout 511 * the box, as well as the text label. 512 * 513 * @see Component#validate() 514 */ 515 void layout(); 516 517 /** 518 * Applies the shape to the native component window. 519 * @param shape the shape to apply 520 * @since 1.7 521 * 522 * @see Component#applyCompoundShape 523 */ 524 void applyShape(Region shape); 525 526 /** 527 * Lowers this component at the bottom of the above HW peer. If the above parameter 528 * is null then the method places this component at the top of the Z-order. 529 * @param above the peer to lower this component with respect to 530 */ 531 void setZOrder(ComponentPeer above); 532 533 /** 534 * Updates internal data structures related to the component's GC. 535 * @param gc the reference graphics configuration 536 * @return if the peer needs to be recreated for the changes to take effect 537 * @since 1.7 538 */ 539 boolean updateGraphicsData(GraphicsConfiguration gc); 540 }