1/*
2 * Copyright (c) 1995, 2015, 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 */
25package java.awt;
26
27import java.awt.image.BufferStrategy;
28import java.awt.peer.CanvasPeer;
29import javax.accessibility.*;
30
31/**
32 * A {@code Canvas} 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} class in
37 * order to get useful functionality such as creating a custom
38 * component. The {@code paint} method must be overridden
39 * in order to perform custom graphics on the canvas.
40 *
41 * @author      Sami Shaio
42 * @since       1.0
43 */
44public 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. If null is
62     * passed, then the default GraphicsConfiguration will be used.
63     *
64     * @param config a reference to a GraphicsConfiguration object or null
65     *
66     * @see GraphicsConfiguration
67     * @see Component#getGraphicsConfiguration()
68     */
69    public Canvas(GraphicsConfiguration config) {
70        this();
71        setGraphicsConfiguration(config);
72    }
73
74    @Override
75    void setGraphicsConfiguration(GraphicsConfiguration gc) {
76        synchronized(getTreeLock()) {
77            CanvasPeer peer = (CanvasPeer) this.peer;
78            if (peer != null) {
79                gc = peer.getAppropriateGraphicsConfiguration(gc);
80            }
81            super.setGraphicsConfiguration(gc);
82        }
83    }
84
85    /**
86     * Construct a name for this component.  Called by getName() when the
87     * name is null.
88     */
89    String constructComponentName() {
90        synchronized (Canvas.class) {
91            return base + nameCounter++;
92        }
93    }
94
95    /**
96     * Creates the peer of the canvas.  This peer allows you to change the
97     * user interface of the canvas without changing its functionality.
98     * @see     java.awt.Component#getToolkit()
99     */
100    public void addNotify() {
101        synchronized (getTreeLock()) {
102            if (peer == null)
103                peer = getComponentFactory().createCanvas(this);
104            super.addNotify();
105        }
106    }
107
108    /**
109     * Paints this canvas.
110     * <p>
111     * Most applications that subclass {@code Canvas} should
112     * override this method in order to perform some useful operation
113     * (typically, custom painting of the canvas).
114     * The default operation is simply to clear the canvas.
115     * Applications that override this method need not call
116     * super.paint(g).
117     *
118     * @param      g   the specified Graphics context
119     * @see        #update(Graphics)
120     * @see        Component#paint(Graphics)
121     */
122    public void paint(Graphics g) {
123        g.clearRect(0, 0, width, height);
124    }
125
126    /**
127     * Updates this canvas.
128     * <p>
129     * This method is called in response to a call to {@code repaint}.
130     * The canvas is first cleared by filling it with the background
131     * color, and then completely redrawn by calling this canvas's
132     * {@code paint} method.
133     * Note: applications that override this method should either call
134     * super.update(g) or incorporate the functionality described
135     * above into their own code.
136     *
137     * @param g the specified Graphics context
138     * @see   #paint(Graphics)
139     * @see   Component#update(Graphics)
140     */
141    public void update(Graphics g) {
142        g.clearRect(0, 0, width, height);
143        paint(g);
144    }
145
146    boolean postsOldMouseEvents() {
147        return true;
148    }
149
150    /**
151     * Creates a new strategy for multi-buffering on this component.
152     * Multi-buffering is useful for rendering performance.  This method
153     * attempts to create the best strategy available with the number of
154     * buffers supplied.  It will always create a {@code BufferStrategy}
155     * with that number of buffers.
156     * A page-flipping strategy is attempted first, then a blitting strategy
157     * using accelerated buffers.  Finally, an unaccelerated blitting
158     * strategy is used.
159     * <p>
160     * Each time this method is called,
161     * the existing buffer strategy for this component is discarded.
162     * @param numBuffers number of buffers to create, including the front buffer
163     * @exception IllegalArgumentException if numBuffers is less than 1.
164     * @exception IllegalStateException if the component is not displayable
165     * @see #isDisplayable
166     * @see #getBufferStrategy
167     * @since 1.4
168     */
169    public void createBufferStrategy(int numBuffers) {
170        super.createBufferStrategy(numBuffers);
171    }
172
173    /**
174     * Creates a new strategy for multi-buffering on this component with the
175     * required buffer capabilities.  This is useful, for example, if only
176     * accelerated memory or page flipping is desired (as specified by the
177     * buffer capabilities).
178     * <p>
179     * Each time this method
180     * is called, the existing buffer strategy for this component is discarded.
181     * @param numBuffers number of buffers to create
182     * @param caps the required capabilities for creating the buffer strategy;
183     * cannot be {@code null}
184     * @exception AWTException if the capabilities supplied could not be
185     * supported or met; this may happen, for example, if there is not enough
186     * accelerated memory currently available, or if page flipping is specified
187     * but not possible.
188     * @exception IllegalArgumentException if numBuffers is less than 1, or if
189     * caps is {@code null}
190     * @see #getBufferStrategy
191     * @since 1.4
192     */
193    public void createBufferStrategy(int numBuffers,
194        BufferCapabilities caps) throws AWTException {
195        super.createBufferStrategy(numBuffers, caps);
196    }
197
198    /**
199     * Returns the {@code BufferStrategy} used by this component.  This
200     * method will return null if a {@code BufferStrategy} has not yet
201     * been created or has been disposed.
202     *
203     * @return the buffer strategy used by this component
204     * @see #createBufferStrategy
205     * @since 1.4
206     */
207    public BufferStrategy getBufferStrategy() {
208        return super.getBufferStrategy();
209    }
210
211    /*
212     * --- Accessibility Support ---
213     *
214     */
215
216    /**
217     * Gets the AccessibleContext associated with this Canvas.
218     * For canvases, the AccessibleContext takes the form of an
219     * AccessibleAWTCanvas.
220     * A new AccessibleAWTCanvas instance is created if necessary.
221     *
222     * @return an AccessibleAWTCanvas that serves as the
223     *         AccessibleContext of this Canvas
224     * @since 1.3
225     */
226    public AccessibleContext getAccessibleContext() {
227        if (accessibleContext == null) {
228            accessibleContext = new AccessibleAWTCanvas();
229        }
230        return accessibleContext;
231    }
232
233    /**
234     * This class implements accessibility support for the
235     * {@code Canvas} class.  It provides an implementation of the
236     * Java Accessibility API appropriate to canvas user-interface elements.
237     * @since 1.3
238     */
239    protected class AccessibleAWTCanvas extends AccessibleAWTComponent
240    {
241        private static final long serialVersionUID = -6325592262103146699L;
242
243        /**
244         * Get the role of this object.
245         *
246         * @return an instance of AccessibleRole describing the role of the
247         * object
248         * @see AccessibleRole
249         */
250        public AccessibleRole getAccessibleRole() {
251            return AccessibleRole.CANVAS;
252        }
253
254    } // inner class AccessibleAWTCanvas
255}
256