1 /*
   2  * Copyright (c) 1995, 2014, 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.ColorModel;
  31 import java.awt.image.ImageObserver;
  32 import java.awt.image.ImageProducer;
  33 import java.awt.image.VolatileImage;
  34 
  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 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 }