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