View Javadoc
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 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                          CausedFocusEvent.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 representaion
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      * @see Component.FlipBufferStrategy#createBuffers
462      */
463     void createBuffers(int numBuffers, BufferCapabilities caps)
464          throws AWTException;
465 
466     /**
467      * Returns the back buffer as image.
468      *
469      * @return the back buffer as image
470      *
471      * @see Component.FlipBufferStrategy#getBackBuffer
472      */
473     Image getBackBuffer();
474 
475     /**
476      * Move the back buffer to the front buffer.
477      *
478      * @param x1 the area to be flipped, upper left X coordinate
479      * @param y1 the area to be flipped, upper left Y coordinate
480      * @param x2 the area to be flipped, lower right X coordinate
481      * @param y2 the area to be flipped, lower right Y coordinate
482      * @param flipAction the flip action to perform
483      *
484      * @see Component.FlipBufferStrategy#flip
485      */
486     void flip(int x1, int y1, int x2, int y2, BufferCapabilities.FlipContents flipAction);
487 
488     /**
489      * Destroys all created buffers.
490      *
491      * @see Component.FlipBufferStrategy#destroyBuffers
492      */
493     void destroyBuffers();
494 
495     /**
496      * Reparents this peer to the new parent referenced by
497      * {@code newContainer} peer. Implementation depends on toolkit and
498      * container.
499      *
500      * @param newContainer peer of the new parent container
501      *
502      * @since 1.5
503      */
504     void reparent(ContainerPeer newContainer);
505 
506     /**
507      * Returns whether this peer supports reparenting to another parent without
508      * destroying the peer.
509      *
510      * @return true if appropriate reparent is supported, false otherwise
511      *
512      * @since 1.5
513      */
514     boolean isReparentSupported();
515 
516     /**
517      * Used by lightweight implementations to tell a ComponentPeer to layout
518      * its sub-elements.  For instance, a lightweight Checkbox needs to layout
519      * the box, as well as the text label.
520      *
521      * @see Component#validate()
522      */
523     void layout();
524 
525     /**
526      * Applies the shape to the native component window.
527      * @since 1.7
528      *
529      * @see Component#applyCompoundShape
530      */
531     void applyShape(Region shape);
532 
533     /**
534      * Lowers this component at the bottom of the above HW peer. If the above parameter
535      * is null then the method places this component at the top of the Z-order.
536      */
537     void setZOrder(ComponentPeer above);
538 
539     /**
540      * Updates internal data structures related to the component's GC.
541      *
542      * @return if the peer needs to be recreated for the changes to take effect
543      * @since 1.7
544      */
545     boolean updateGraphicsData(GraphicsConfiguration gc);
546 }