Home » openjdk-7 » java » awt » peer » [javadoc | source]

    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 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   }

Home » openjdk-7 » java » awt » peer » [javadoc | source]