Canvas


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