libjava/java/awt/Canvas.java

   1 /* Canvas.java --
   2    Copyright (C) 1999, 2000, 2002, 2004  Free Software Foundation
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt;
  40
  41 import java.awt.image.BufferStrategy;
  42 import java.awt.peer.ComponentPeer;
  43 import java.io.Serializable;
  44
  45 import javax.accessibility.Accessible;
  46 import javax.accessibility.AccessibleContext;
  47 import javax.accessibility.AccessibleRole;
  48
  49 /**
  50  * The <code>Canvas</code> component provides a blank rectangular
  51  * area, which the client application can use for drawing and for
  52  * capturing events.  By overriding the <code>paint()</code> method,
  53  * the canvas can be used for anything from simple line drawings to
  54  * full-scale custom components.
  55  *
  56  * @author Original author unknown
  57  * @author Tom Tromey  (tromey@redhat.com)
  58  * @author Andrew John Hughes  (gnu_andrew@member.fsf.org)
  59  * @since 1.0
  60  */
  61
  62 public class Canvas
  63   extends Component
  64   implements Serializable, Accessible
  65 {
  66
  67   /**
  68    * Compatible with Sun's JDK.
  69    */
  70   private static final long serialVersionUID = -2284879212465893870L;
  71
  72   /**
  73    * The graphics configuration associated with the canvas.
  74    */
  75   transient GraphicsConfiguration graphicsConfiguration;
  76
  77   /**
  78    * The buffer strategy associated with this canvas.
  79    */
  80   transient BufferStrategy bufferStrategy;
  81
  82   /**
  83    * Initializes a new instance of <code>Canvas</code>.
  84    */
  85   public Canvas()
  86   {
  87   }
  88
  89   /**
  90    * Initializes a new instance of <code>Canvas</code>
  91    * with the supplied graphics configuration.
  92    *
  93    * @param graphicsConfiguration the graphics configuration to use
  94    *        for this particular canvas.
  95    */
  96   public Canvas(GraphicsConfiguration graphicsConfiguration)
  97   {
  98     this.graphicsConfiguration = graphicsConfiguration;
  99   }
 100
 101   GraphicsConfiguration getGraphicsConfigurationImpl()
 102   {
 103     if (graphicsConfiguration != null)
 104       return graphicsConfiguration;
 105     return super.getGraphicsConfigurationImpl();
 106   }
 107
 108   /**
 109    * Creates the native peer for this object.
 110    */
 111   public void addNotify()
 112   {
 113     if (peer == null)
 114       peer = (ComponentPeer) getToolkit().createCanvas(this);
 115     super.addNotify();
 116   }
 117
 118   /**
 119    * Repaints the canvas window.  This method should be overridden by
 120    * a subclass to do something useful, as this method simply paints
 121    * the window with the background color.
 122    *
 123    * @param gfx the <code>Graphics</code> to use for painting
 124    */
 125   public void paint(Graphics gfx)
 126   {
 127     /* This implementation doesn't make much sense since the filling
 128       of background color is guaranteed for heavyweight components
 129       such as this.  But there's no need to worry, since paint() is
 130       usually overridden anyway.  */
 131     gfx.setColor(getBackground());
 132     Dimension size = getSize();
 133     gfx.fillRect(0, 0, size.width, size.height);
 134   }
 135
 136   /**
 137    * This class provides accessibility support for the canvas.
 138    */
 139   protected class AccessibleAWTCanvas
 140     extends AccessibleAWTComponent
 141   {
 142     /**
 143      * For compatability with Sun's JDK
 144      */
 145     private static final long serialVersionUID = -6325592262103146699L;
 146
 147     /**
 148      * Constructor for the accessible canvas.
 149      */
 150     protected AccessibleAWTCanvas()
 151     {
 152     }
 153
 154     /**
 155      * Returns the accessible role for the canvas.
 156      *
 157      * @return an instance of <code>AccessibleRole</code>, describing
 158      *         the role of the canvas.
 159      */
 160     public AccessibleRole getAccessibleRole()
 161     {
 162       return AccessibleRole.CANVAS;
 163     }
 164
 165   }
 166
 167   /**
 168    * Gets the AccessibleContext associated with this <code>Canvas</code>.
 169    * The context is created, if necessary.
 170    *
 171    * @return the associated context
 172    */
 173   public AccessibleContext getAccessibleContext()
 174   {
 175     /* Create the context if this is the first request */
 176     if (accessibleContext == null)
 177       accessibleContext = new AccessibleAWTCanvas();
 178     return accessibleContext;
 179   }
 180
 181   /**
 182    * Returns the buffer strategy used by the canvas.
 183    *
 184    * @return the buffer strategy.
 185    * @since 1.4
 186    */
 187   public BufferStrategy getBufferStrategy()
 188   {
 189     return bufferStrategy;
 190   }
 191
 192   /**
 193    * Updates the canvas in response to a request to
 194    * <code>repaint()</code> it.  The canvas is cleared
 195    * with the current background colour, before <code>paint()</code>
 196    * is called to add the new contents.  Subclasses
 197    * which override this method should either call this
 198    * method via <code>super.update(graphics)</code> or re-implement
 199    * this behaviour, so as to ensure that the canvas is
 200    * clear before painting takes place.
 201    *
 202    * @param graphics the graphics context.
 203    */
 204   public void update(Graphics graphics)
 205   {
 206     Dimension size;
 207
 208     /* Clear the canvas */
 209     size = getSize();
 210     graphics.clearRect(0, 0, size.width, size.height);
 211     /* Call the paint method */
 212     paint(graphics);
 213   }
 214
 215 }