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: }
| 