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