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

    1   /*
    2    * Copyright (c) 1995, 2010, 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   package java.awt;
   26   
   27   import java.awt.image.BufferStrategy;
   28   import java.awt.peer.CanvasPeer;
   29   import javax.accessibility;
   30   
   31   /**
   32    * A <code>Canvas</code> component represents a blank rectangular
   33    * area of the screen onto which the application can draw or from
   34    * which the application can trap input events from the user.
   35    * <p>
   36    * An application must subclass the <code>Canvas</code> class in
   37    * order to get useful functionality such as creating a custom
   38    * component. The <code>paint</code> method must be overridden
   39    * in order to perform custom graphics on the canvas.
   40    *
   41    * @author      Sami Shaio
   42    * @since       JDK1.0
   43    */
   44   public class Canvas extends Component implements Accessible {
   45   
   46       private static final String base = "canvas";
   47       private static int nameCounter = 0;
   48   
   49       /*
   50        * JDK 1.1 serialVersionUID
   51        */
   52        private static final long serialVersionUID = -2284879212465893870L;
   53   
   54       /**
   55        * Constructs a new Canvas.
   56        */
   57       public Canvas() {
   58       }
   59   
   60       /**
   61        * Constructs a new Canvas given a GraphicsConfiguration object.
   62        *
   63        * @param config a reference to a GraphicsConfiguration object.
   64        *
   65        * @see GraphicsConfiguration
   66        */
   67       public Canvas(GraphicsConfiguration config) {
   68           this();
   69           setGraphicsConfiguration(config);
   70       }
   71   
   72       @Override
   73       void setGraphicsConfiguration(GraphicsConfiguration gc) {
   74           synchronized(getTreeLock()) {
   75               CanvasPeer peer = (CanvasPeer)getPeer();
   76               if (peer != null) {
   77                   gc = peer.getAppropriateGraphicsConfiguration(gc);
   78               }
   79               super.setGraphicsConfiguration(gc);
   80           }
   81       }
   82   
   83       /**
   84        * Construct a name for this component.  Called by getName() when the
   85        * name is null.
   86        */
   87       String constructComponentName() {
   88           synchronized (Canvas.class) {
   89               return base + nameCounter++;
   90           }
   91       }
   92   
   93       /**
   94        * Creates the peer of the canvas.  This peer allows you to change the
   95        * user interface of the canvas without changing its functionality.
   96        * @see     java.awt.Toolkit#createCanvas(java.awt.Canvas)
   97        * @see     java.awt.Component#getToolkit()
   98        */
   99       public void addNotify() {
  100           synchronized (getTreeLock()) {
  101               if (peer == null)
  102                   peer = getToolkit().createCanvas(this);
  103               super.addNotify();
  104           }
  105       }
  106   
  107       /**
  108        * Paints this canvas.
  109        * <p>
  110        * Most applications that subclass <code>Canvas</code> should
  111        * override this method in order to perform some useful operation
  112        * (typically, custom painting of the canvas).
  113        * The default operation is simply to clear the canvas.
  114        * Applications that override this method need not call
  115        * super.paint(g).
  116        *
  117        * @param      g   the specified Graphics context
  118        * @see        #update(Graphics)
  119        * @see        Component#paint(Graphics)
  120        */
  121       public void paint(Graphics g) {
  122           g.clearRect(0, 0, width, height);
  123       }
  124   
  125       /**
  126        * Updates this canvas.
  127        * <p>
  128        * This method is called in response to a call to <code>repaint</code>.
  129        * The canvas is first cleared by filling it with the background
  130        * color, and then completely redrawn by calling this canvas's
  131        * <code>paint</code> method.
  132        * Note: applications that override this method should either call
  133        * super.update(g) or incorporate the functionality described
  134        * above into their own code.
  135        *
  136        * @param g the specified Graphics context
  137        * @see   #paint(Graphics)
  138        * @see   Component#update(Graphics)
  139        */
  140       public void update(Graphics g) {
  141           g.clearRect(0, 0, width, height);
  142           paint(g);
  143       }
  144   
  145       boolean postsOldMouseEvents() {
  146           return true;
  147       }
  148   
  149       /**
  150        * Creates a new strategy for multi-buffering on this component.
  151        * Multi-buffering is useful for rendering performance.  This method
  152        * attempts to create the best strategy available with the number of
  153        * buffers supplied.  It will always create a <code>BufferStrategy</code>
  154        * with that number of buffers.
  155        * A page-flipping strategy is attempted first, then a blitting strategy
  156        * using accelerated buffers.  Finally, an unaccelerated blitting
  157        * strategy is used.
  158        * <p>
  159        * Each time this method is called,
  160        * the existing buffer strategy for this component is discarded.
  161        * @param numBuffers number of buffers to create, including the front buffer
  162        * @exception IllegalArgumentException if numBuffers is less than 1.
  163        * @exception IllegalStateException if the component is not displayable
  164        * @see #isDisplayable
  165        * @see #getBufferStrategy
  166        * @since 1.4
  167        */
  168       public void createBufferStrategy(int numBuffers) {
  169           super.createBufferStrategy(numBuffers);
  170       }
  171   
  172       /**
  173        * Creates a new strategy for multi-buffering on this component with the
  174        * required buffer capabilities.  This is useful, for example, if only
  175        * accelerated memory or page flipping is desired (as specified by the
  176        * buffer capabilities).
  177        * <p>
  178        * Each time this method
  179        * is called, the existing buffer strategy for this component is discarded.
  180        * @param numBuffers number of buffers to create
  181        * @param caps the required capabilities for creating the buffer strategy;
  182        * cannot be <code>null</code>
  183        * @exception AWTException if the capabilities supplied could not be
  184        * supported or met; this may happen, for example, if there is not enough
  185        * accelerated memory currently available, or if page flipping is specified
  186        * but not possible.
  187        * @exception IllegalArgumentException if numBuffers is less than 1, or if
  188        * caps is <code>null</code>
  189        * @see #getBufferStrategy
  190        * @since 1.4
  191        */
  192       public void createBufferStrategy(int numBuffers,
  193           BufferCapabilities caps) throws AWTException {
  194           super.createBufferStrategy(numBuffers, caps);
  195       }
  196   
  197       /**
  198        * Returns the <code>BufferStrategy</code> used by this component.  This
  199        * method will return null if a <code>BufferStrategy</code> has not yet
  200        * been created or has been disposed.
  201        *
  202        * @return the buffer strategy used by this component
  203        * @see #createBufferStrategy
  204        * @since 1.4
  205        */
  206       public BufferStrategy getBufferStrategy() {
  207           return super.getBufferStrategy();
  208       }
  209   
  210       /*
  211        * --- Accessibility Support ---
  212        *
  213        */
  214   
  215       /**
  216        * Gets the AccessibleContext associated with this Canvas.
  217        * For canvases, the AccessibleContext takes the form of an
  218        * AccessibleAWTCanvas.
  219        * A new AccessibleAWTCanvas instance is created if necessary.
  220        *
  221        * @return an AccessibleAWTCanvas that serves as the
  222        *         AccessibleContext of this Canvas
  223        * @since 1.3
  224        */
  225       public AccessibleContext getAccessibleContext() {
  226           if (accessibleContext == null) {
  227               accessibleContext = new AccessibleAWTCanvas();
  228           }
  229           return accessibleContext;
  230       }
  231   
  232       /**
  233        * This class implements accessibility support for the
  234        * <code>Canvas</code> class.  It provides an implementation of the
  235        * Java Accessibility API appropriate to canvas user-interface elements.
  236        * @since 1.3
  237        */
  238       protected class AccessibleAWTCanvas extends AccessibleAWTComponent
  239       {
  240           private static final long serialVersionUID = -6325592262103146699L;
  241   
  242           /**
  243            * Get the role of this object.
  244            *
  245            * @return an instance of AccessibleRole describing the role of the
  246            * object
  247            * @see AccessibleRole
  248            */
  249           public AccessibleRole getAccessibleRole() {
  250               return AccessibleRole.CANVAS;
  251           }
  252   
  253       } // inner class AccessibleAWTCanvas
  254   }

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