1 /*
2 * Copyright (c) 1995, 2013, 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.image.ImageProducer;
31 import java.awt.image.ImageObserver;
32 import java.awt.image.ColorModel;
33 import java.awt.image.VolatileImage;
34 import java.awt.GraphicsConfiguration;
35 import sun.awt.CausedFocusEvent;
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 the toolkit that is responsible for the component.
264 *
265 * @return the toolkit that is responsible for the component
266 *
267 * @see Component#getToolkit()
268 */
269 Toolkit getToolkit();
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 CausedFocusEvent.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 image using the specified image producer.
368 *
369 * @param producer the image producer from which the image pixels will be
370 * produced
371 *
372 * @return the created image
373 *
374 * @see Component#createImage(ImageProducer)
375 */
376 Image createImage(ImageProducer producer);
377
378 /**
379 * Creates an empty image with the specified width and height. This is
380 * generally used as a non-accelerated backbuffer for drawing onto the
381 * component (e.g. by Swing).
382 *
383 * @param width the width of the image
384 * @param height the height of the image
385 *
386 * @return the created image
387 *
388 * @see Component#createImage(int, int)
389 */
390 // TODO: Maybe make that return a BufferedImage, because some stuff will
391 // break if a different kind of image is returned.
392 Image createImage(int width, int height);
393
394 /**
395 * Creates an empty volatile image with the specified width and height.
396 * This is generally used as an accelerated backbuffer for drawing onto
397 * the component (e.g. by Swing).
398 *
399 * @param width the width of the image
400 * @param height the height of the image
401 *
402 * @return the created volatile image
403 *
404 * @see Component#createVolatileImage(int, int)
405 */
406 // TODO: Include capabilities here and fix Component#createVolatileImage
407 VolatileImage createVolatileImage(int width, int height);
408
409 /**
410 * Prepare the specified image for rendering on this component. This should
411 * start loading the image (if not already loaded) and create an
412 * appropriate screen representation.
413 *
414 * @param img the image to prepare
415 * @param w the width of the screen representation
416 * @param h the height of the screen representation
417 * @param o an image observer to observe the progress
418 *
419 * @return {@code true} if the image is already fully prepared,
420 * {@code false} otherwise
421 *
422 * @see Component#prepareImage(Image, int, int, ImageObserver)
423 */
424 boolean prepareImage(Image img, int w, int h, ImageObserver o);
425
426 /**
427 * Determines the status of the construction of the screen representaion
428 * of the specified image.
429 *
430 * @param img the image to check
431 * @param w the target width
432 * @param h the target height
433 * @param o the image observer to notify
434 *
435 * @return the status as bitwise ORed ImageObserver flags
436 *
437 * @see Component#checkImage(Image, int, int, ImageObserver)
438 */
439 int checkImage(Image img, int w, int h, ImageObserver o);
440
441 /**
442 * Returns the graphics configuration that corresponds to this component.
443 *
444 * @return the graphics configuration that corresponds to this component
445 *
446 * @see Component#getGraphicsConfiguration()
447 */
448 GraphicsConfiguration getGraphicsConfiguration();
449
450 /**
451 * Determines if the component handles wheel scrolling itself. Otherwise
452 * it is delegated to the component's parent.
453 *
454 * @return {@code true} if the component handles wheel scrolling,
455 * {@code false} otherwise
456 *
457 * @see Component#dispatchEventImpl(AWTEvent)
458 */
459 boolean handlesWheelScrolling();
460
461 /**
462 * Create {@code numBuffers} flipping buffers with the specified
463 * buffer capabilities.
464 *
465 * @param numBuffers the number of buffers to create
466 * @param caps the buffer capabilities
467 *
468 * @throws AWTException if flip buffering is not supported
469 *
470 * @see Component.FlipBufferStrategy#createBuffers
471 */
472 void createBuffers(int numBuffers, BufferCapabilities caps)
473 throws AWTException;
474
475 /**
476 * Returns the back buffer as image.
477 *
478 * @return the back buffer as image
479 *
480 * @see Component.FlipBufferStrategy#getBackBuffer
481 */
482 Image getBackBuffer();
483
484 /**
485 * Move the back buffer to the front buffer.
486 *
487 * @param x1 the area to be flipped, upper left X coordinate
488 * @param y1 the area to be flipped, upper left Y coordinate
489 * @param x2 the area to be flipped, lower right X coordinate
490 * @param y2 the area to be flipped, lower right Y coordinate
491 * @param flipAction the flip action to perform
492 *
493 * @see Component.FlipBufferStrategy#flip
494 */
495 void flip(int x1, int y1, int x2, int y2, BufferCapabilities.FlipContents flipAction);
496
497 /**
498 * Destroys all created buffers.
499 *
500 * @see Component.FlipBufferStrategy#destroyBuffers
501 */
502 void destroyBuffers();
503
504 /**
505 * Reparents this peer to the new parent referenced by
506 * {@code newContainer} peer. Implementation depends on toolkit and
507 * container.
508 *
509 * @param newContainer peer of the new parent container
510 *
511 * @since 1.5
512 */
513 void reparent(ContainerPeer newContainer);
514
515 /**
516 * Returns whether this peer supports reparenting to another parent without
517 * destroying the peer.
518 *
519 * @return true if appropriate reparent is supported, false otherwise
520 *
521 * @since 1.5
522 */
523 boolean isReparentSupported();
524
525 /**
526 * Used by lightweight implementations to tell a ComponentPeer to layout
527 * its sub-elements. For instance, a lightweight Checkbox needs to layout
528 * the box, as well as the text label.
529 *
530 * @see Component#validate()
531 */
532 void layout();
533
534 /**
535 * Applies the shape to the native component window.
536 * @since 1.7
537 *
538 * @see Component#applyCompoundShape
539 */
540 void applyShape(Region shape);
541
542 /**
543 * Lowers this component at the bottom of the above HW peer. If the above parameter
544 * is null then the method places this component at the top of the Z-order.
545 */
546 void setZOrder(ComponentPeer above);
547
548 /**
549 * Updates internal data structures related to the component's GC.
550 *
551 * @return if the peer needs to be recreated for the changes to take effect
552 * @since 1.7
553 */
554 boolean updateGraphicsData(GraphicsConfiguration gc);
555 }