001 /*
002 * Copyright 1995-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.awt;
026
027 import java.awt.image.BufferStrategy;
028 import javax.accessibility.*;
029
030 /**
031 * A <code>Canvas</code> component represents a blank rectangular
032 * area of the screen onto which the application can draw or from
033 * which the application can trap input events from the user.
034 * <p>
035 * An application must subclass the <code>Canvas</code> class in
036 * order to get useful functionality such as creating a custom
037 * component. The <code>paint</code> method must be overridden
038 * in order to perform custom graphics on the canvas.
039 *
040 * @version 1.48 06/05/07
041 * @author Sami Shaio
042 * @since JDK1.0
043 */
044 public class Canvas extends Component implements Accessible {
045
046 private static final String base = "canvas";
047 private static int nameCounter = 0;
048
049 /*
050 * JDK 1.1 serialVersionUID
051 */
052 private static final long serialVersionUID = -2284879212465893870L;
053
054 /**
055 * Constructs a new Canvas.
056 */
057 public Canvas() {
058 }
059
060 /**
061 * Constructs a new Canvas given a GraphicsConfiguration object.
062 *
063 * @param config a reference to a GraphicsConfiguration object.
064 *
065 * @see GraphicsConfiguration
066 */
067 public Canvas(GraphicsConfiguration config) {
068 this ();
069 graphicsConfig = config;
070 }
071
072 /**
073 * Construct a name for this component. Called by getName() when the
074 * name is null.
075 */
076 String constructComponentName() {
077 synchronized (Canvas.class) {
078 return base + nameCounter++;
079 }
080 }
081
082 /**
083 * Creates the peer of the canvas. This peer allows you to change the
084 * user interface of the canvas without changing its functionality.
085 * @see java.awt.Toolkit#createCanvas(java.awt.Canvas)
086 * @see java.awt.Component#getToolkit()
087 */
088 public void addNotify() {
089 synchronized (getTreeLock()) {
090 if (peer == null)
091 peer = getToolkit().createCanvas(this );
092 super .addNotify();
093 }
094 }
095
096 /**
097 * Paints this canvas.
098 * <p>
099 * Most applications that subclass <code>Canvas</code> should
100 * override this method in order to perform some useful operation
101 * (typically, custom painting of the canvas).
102 * The default operation is simply to clear the canvas.
103 * Applications that override this method need not call
104 * super.paint(g).
105 *
106 * @param g the specified Graphics context
107 * @see #update(Graphics)
108 * @see Component#paint(Graphics)
109 */
110 public void paint(Graphics g) {
111 g.clearRect(0, 0, width, height);
112 }
113
114 /**
115 * Updates this canvas.
116 * <p>
117 * This method is called in response to a call to <code>repaint</code>.
118 * The canvas is first cleared by filling it with the background
119 * color, and then completely redrawn by calling this canvas's
120 * <code>paint</code> method.
121 * Note: applications that override this method should either call
122 * super.update(g) or incorporate the functionality described
123 * above into their own code.
124 *
125 * @param g the specified Graphics context
126 * @see #paint(Graphics)
127 * @see Component#update(Graphics)
128 */
129 public void update(Graphics g) {
130 g.clearRect(0, 0, width, height);
131 paint(g);
132 }
133
134 boolean postsOldMouseEvents() {
135 return true;
136 }
137
138 /**
139 * Creates a new strategy for multi-buffering on this component.
140 * Multi-buffering is useful for rendering performance. This method
141 * attempts to create the best strategy available with the number of
142 * buffers supplied. It will always create a <code>BufferStrategy</code>
143 * with that number of buffers.
144 * A page-flipping strategy is attempted first, then a blitting strategy
145 * using accelerated buffers. Finally, an unaccelerated blitting
146 * strategy is used.
147 * <p>
148 * Each time this method is called,
149 * the existing buffer strategy for this component is discarded.
150 * @param numBuffers number of buffers to create, including the front buffer
151 * @exception IllegalArgumentException if numBuffers is less than 1.
152 * @exception IllegalStateException if the component is not displayable
153 * @see #isDisplayable
154 * @see #getBufferStrategy
155 * @since 1.4
156 */
157 public void createBufferStrategy(int numBuffers) {
158 super .createBufferStrategy(numBuffers);
159 }
160
161 /**
162 * Creates a new strategy for multi-buffering on this component with the
163 * required buffer capabilities. This is useful, for example, if only
164 * accelerated memory or page flipping is desired (as specified by the
165 * buffer capabilities).
166 * <p>
167 * Each time this method
168 * is called, the existing buffer strategy for this component is discarded.
169 * @param numBuffers number of buffers to create
170 * @param caps the required capabilities for creating the buffer strategy;
171 * cannot be <code>null</code>
172 * @exception AWTException if the capabilities supplied could not be
173 * supported or met; this may happen, for example, if there is not enough
174 * accelerated memory currently available, or if page flipping is specified
175 * but not possible.
176 * @exception IllegalArgumentException if numBuffers is less than 1, or if
177 * caps is <code>null</code>
178 * @see #getBufferStrategy
179 * @since 1.4
180 */
181 public void createBufferStrategy(int numBuffers,
182 BufferCapabilities caps) throws AWTException {
183 super .createBufferStrategy(numBuffers, caps);
184 }
185
186 /**
187 * Returns the <code>BufferStrategy</code> used by this component. This
188 * method will return null if a <code>BufferStrategy</code> has not yet
189 * been created or has been disposed.
190 *
191 * @return the buffer strategy used by this component
192 * @see #createBufferStrategy
193 * @since 1.4
194 */
195 public BufferStrategy getBufferStrategy() {
196 return super .getBufferStrategy();
197 }
198
199 /*
200 * --- Accessibility Support ---
201 *
202 */
203
204 /**
205 * Gets the AccessibleContext associated with this Canvas.
206 * For canvases, the AccessibleContext takes the form of an
207 * AccessibleAWTCanvas.
208 * A new AccessibleAWTCanvas instance is created if necessary.
209 *
210 * @return an AccessibleAWTCanvas that serves as the
211 * AccessibleContext of this Canvas
212 * @since 1.3
213 */
214 public AccessibleContext getAccessibleContext() {
215 if (accessibleContext == null) {
216 accessibleContext = new AccessibleAWTCanvas();
217 }
218 return accessibleContext;
219 }
220
221 /**
222 * This class implements accessibility support for the
223 * <code>Canvas</code> class. It provides an implementation of the
224 * Java Accessibility API appropriate to canvas user-interface elements.
225 * @since 1.3
226 */
227 protected class AccessibleAWTCanvas extends AccessibleAWTComponent {
228 private static final long serialVersionUID = -6325592262103146699L;
229
230 /**
231 * Get the role of this object.
232 *
233 * @return an instance of AccessibleRole describing the role of the
234 * object
235 * @see AccessibleRole
236 */
237 public AccessibleRole getAccessibleRole() {
238 return AccessibleRole.CANVAS;
239 }
240
241 } // inner class AccessibleAWTCanvas
242 }
|