1 /*
   2  * Copyright (c) 1995, 2007, 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 }