001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package jsx.ui.vect;
021 
022 import js.NumberLike;
023 import js.user.JsCanvasGradient;
024 import js.user.JsCanvasPattern;
025 import js.user.JsCanvasRenderingContext2D;
026 import js.user.JsHTMLCanvasElement;
027 import js.user.JsHTMLElement;
028 import js.user.JsHTMLImageElement;
029 import jsx.client.Document;
030 import jsx.client.Win;
031 import jsx.ui.Component;
032 import jsx.ui.Widget;
033 
034 /**
035  * <p>Defines a canvas widget.</p>
036  * <p>A {@link Canvas} is a {@link Widget} that wraps a {@link Component} that 
037  * wraps an HTML <tt>&lt;canvas&gt;</tt> element.</p>
038  * 
039  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
040  */
041 public class Canvas extends Widget
042 {
043     private final JsCanvasRenderingContext2D context;
044 
045     /**
046      * <p>A typical constructor forcing constructors of subclasses to pass a component.</p>
047      * @param e The underlying component that must wrap an HTML <tt>&lt;canvas&gt;</tt> 
048      * element.
049      * @since 1.0
050      */
051     protected Canvas(Component e) {
052         super(e);
053         context = new JsHTMLCanvasElement(
054                 Component.getHTMLElement(e)
055         ).getContext("2d");
056     }
057 
058     /**
059      * <p>Gets a canvas widget from an HTML <tt>&lt;canvas&gt;</tt> element.</p>
060      * @param e An HTML <tt>&lt;canvas&gt;</tt> element.
061      * @return A canvas widget that wraps a component that wraps the HTML 
062      * <tt>&lt;canvas&gt;</tt> element.
063      * @since 1.0
064      */
065     public static final Canvas get(JsHTMLElement e) {
066         Component c = Component.get(e);
067         if (!Component.tagName(c, "canvas")) {
068             return null;
069         }
070         return new Canvas(c);
071     }
072 
073     /**
074      * <p>Creates a canvas widget the HTML <tt>&lt;body&gt;</tt> element of the current 
075      * HTML document.</p>
076      * @return A canvas widget that wraps a component that wraps the newly created HTML 
077      * <tt>&lt;canvas&gt;</tt> element.
078      * @since 1.0
079      */
080     public static final Canvas create() {
081         return create(Document.body.var());
082     }
083 
084     /**
085      * <p>Creates a canvas widget whose HTML <tt>&lt;canvas&gt;</tt> element is a child of 
086      * an existing HTML element.</p>
087      * @return A canvas widget that wraps a component that wraps the newly created HTML 
088      * <tt>&lt;canvas&gt;</tt> element.
089      * @since 1.0
090      */
091     public static final Canvas create(JsHTMLElement parent) {
092         JsHTMLElement e = new JsHTMLElement(
093                 Win.document.var().createElement("canvas")
094         );
095         parent.appendChild(e);
096         return get(e);
097     }
098 
099     /**
100      * <p>Gets the content width of a canvas widget.</p>
101      * <p>This method simply calls the {@link Component#contentWidth(Component)} method with 
102      * the underlying HTML <tt>&lt;canvas&gt;</tt> element of the current canvas widget </p>
103      * @param c The current canvas widget.
104      * @return The content width of the underlying HTML <tt>&lt;canvas&gt;</tt> element of 
105      * the current canvas widget.
106      * @since 1.0
107      */
108     public static final double width(Canvas c) {
109         return Component.contentWidth(c.unwrap());
110     }
111 
112     /**
113      * <p>Gets the content height of a canvas widget.</p>
114      * <p>This method simply calls the {@link Component#contentHeight(Component)} method with 
115      * the underlying HTML <tt>&lt;canvas&gt;</tt> element of the current canvas widget </p>
116      * @param c The current canvas height.
117      * @return The content height of the underlying HTML <tt>&lt;canvas&gt;</tt> element of 
118      * the current canvas widget.
119      * @since 1.0
120      */
121     public static final double height(Canvas c) {
122         return Component.contentHeight(c.unwrap());
123     }
124 
125     /**
126      * <p>Sets the width of a canvas widget.</p>
127      * <p>This method sets the {@link JsHTMLCanvasElement#width} property of the underlying 
128      * HTML <tt>&lt;canvas&gt;</tt> element of the current canvas widget to the specified 
129      * style value.</p>
130      * @param c The current canvas widget.
131      * @param w The <tt>width</tt> style to set.
132      * @since 1.0
133      */
134     public static final void width(Canvas c, Object w) {
135         JsHTMLCanvasElement.width.with(Component.getHTMLElement(c.unwrap()), w);
136     }
137 
138     /**
139      * <p>Sets the height of a canvas widget.</p>
140      * <p>This method sets the {@link JsHTMLCanvasElement#height} property of the underlying 
141      * HTML <tt>&lt;canvas&gt;</tt> element of the current canvas widget to the specified 
142      * style value.</p>
143      * @param c The current canvas widget.
144      * @param h The <tt>height</tt> style to set.
145      * @since 1.0
146      */
147     public static final void height(Canvas c, Object h) {
148         JsHTMLCanvasElement.height.with(Component.getHTMLElement(c.unwrap()), h);
149     }
150 
151     /**
152      * <p>Gets the {@link JsCanvasRenderingContext2D#fillStyle} property of a canvas widget.</p>
153      * @param c The current canvas widget.
154      * @return The {@link JsCanvasRenderingContext2D#fillStyle} property of the underlying 
155      * {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
156      * <tt>&lt;canvas&gt;</tt> element.
157      * @since 1.0
158      */
159     public static final Object fillStyle(Canvas c) {
160         return JsCanvasRenderingContext2D.fillStyle.with(c.context);
161     }
162 
163     /**
164      * <p>Sets the {@link JsCanvasRenderingContext2D#fillStyle} property of a canvas widget.</p>
165      * <p>This method sets the {@link JsCanvasRenderingContext2D#fillStyle} property of the 
166      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
167      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
168      * @param c The current canvas widget.
169      * @param o The new property value.
170      * @since 1.0
171      */
172     public static final void fillStyle(Canvas c, Object o) {
173         JsCanvasRenderingContext2D.fillStyle.with(c.context, o);
174     }
175 
176     /**
177      * <p>Sets the {@link JsCanvasRenderingContext2D#globalAlpha} property of a canvas widget.</p>
178      * <p>This method sets the {@link JsCanvasRenderingContext2D#globalAlpha} property of the 
179      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
180      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
181      * @param c The current canvas widget.
182      * @param a The new property value.
183      * @since 1.0
184      */
185     public static final void globalAlpha(Canvas c, Number a) {
186         JsCanvasRenderingContext2D.globalAlpha.with(c.context, a);
187     }
188 
189     /**
190      * <p>Gets the {@link JsCanvasRenderingContext2D#globalCompositeOperation} property of a canvas widget.</p>
191      * @param c The current canvas widget.
192      * @return The {@link JsCanvasRenderingContext2D#globalCompositeOperation} property of the underlying 
193      * {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
194      * <tt>&lt;canvas&gt;</tt> element.
195      * @since 1.0
196      */
197     public static final String globalCompositeOperation(Canvas c) {
198         return JsCanvasRenderingContext2D.globalCompositeOperation.with(c.context);
199     }
200 
201     /**
202      * <p>Sets the {@link JsCanvasRenderingContext2D#globalCompositeOperation} property of a canvas widget.</p>
203      * <p>This method sets the {@link JsCanvasRenderingContext2D#globalCompositeOperation} property of the 
204      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
205      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
206      * @param c The current canvas widget.
207      * @param co The new property value.
208      * @since 1.0
209      */
210     public static final void globalCompositeOperation(Canvas c, String co) {
211         JsCanvasRenderingContext2D.globalCompositeOperation.with(c.context, co);
212     }
213 
214     /**
215      * <p>Sets the {@link JsCanvasRenderingContext2D#lineCap} property of a canvas widget.</p>
216      * <p>This method sets the {@link JsCanvasRenderingContext2D#lineCap} property of the 
217      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
218      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
219      * @param c The current canvas widget.
220      * @param lc The new property value.
221      * @since 1.0
222      */
223     public static final void lineCap(Canvas c, String lc) {
224         JsCanvasRenderingContext2D.lineCap.with(c.context, lc);
225     }
226 
227     /**
228      * <p>Sets the {@link JsCanvasRenderingContext2D#lineJoin} property of a canvas widget.</p>
229      * <p>This method sets the {@link JsCanvasRenderingContext2D#lineJoin} property of the 
230      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
231      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
232      * @param c The current canvas widget.
233      * @param lj The new property value.
234      * @since 1.0
235      */
236     public static final void lineJoin(Canvas c, String lj) {
237         JsCanvasRenderingContext2D.lineJoin.with(c.context, lj);
238     }
239 
240     /**
241      * <p>Gets the {@link JsCanvasRenderingContext2D#lineWidth} property of a canvas widget.</p>
242      * @param c The current canvas widget.
243      * @return The {@link JsCanvasRenderingContext2D#lineWidth} property of the underlying 
244      * {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
245      * <tt>&lt;canvas&gt;</tt> element.
246      * @since 1.0
247      */
248     public static final double lineWidth(Canvas c) {
249         return JsCanvasRenderingContext2D.lineWidth.with(c.context).doubleValue();
250     }
251 
252     /**
253      * <p>Sets the {@link JsCanvasRenderingContext2D#lineWidth} property of a canvas widget.</p>
254      * <p>This method sets the {@link JsCanvasRenderingContext2D#lineWidth} property of the 
255      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
256      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
257      * @param c The current canvas widget.
258      * @param w The new property value.
259      * @since 1.0
260      */
261     public static final void lineWidth(Canvas c, Number w) {
262         JsCanvasRenderingContext2D.lineWidth.with(c.context, w);
263     }
264 
265     /**
266      * <p>Sets the {@link JsCanvasRenderingContext2D#miterLimit} property of a canvas widget.</p>
267      * <p>This method sets the {@link JsCanvasRenderingContext2D#miterLimit} property of the 
268      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
269      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
270      * @param c The current canvas widget.
271      * @param m The new property value.
272      * @since 1.0
273      */
274     public static final void miterLimit(Canvas c, Number m) {
275         JsCanvasRenderingContext2D.miterLimit.with(c.context, m);
276     }
277 
278     /**
279      * <p>Sets the {@link JsCanvasRenderingContext2D#shadowBlur} property of a canvas widget.</p>
280      * <p>This method sets the {@link JsCanvasRenderingContext2D#shadowBlur} property of the 
281      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
282      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
283      * @param c The current canvas widget.
284      * @param b The new property value.
285      * @since 1.0
286      */
287     public static final void shadowBlur(Canvas c, Number b) {
288         JsCanvasRenderingContext2D.shadowBlur.with(c.context, b);
289     }
290 
291     /**
292      * <p>Sets the {@link JsCanvasRenderingContext2D#shadowColor} property of a canvas widget.</p>
293      * <p>This method sets the {@link JsCanvasRenderingContext2D#shadowColor} property of the 
294      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
295      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
296      * @param c The current canvas widget.
297      * @param cssColor The new property value.
298      * @since 1.0
299      */
300     public static final void shadowColor(Canvas c, String cssColor) {
301         JsCanvasRenderingContext2D.shadowColor.with(c.context, cssColor);
302     }
303 
304     /**
305      * <p>Sets the {@link JsCanvasRenderingContext2D#shadowOffsetX} property of a canvas widget.</p>
306      * <p>This method sets the {@link JsCanvasRenderingContext2D#shadowOffsetX} property of the 
307      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
308      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
309      * @param c The current canvas widget.
310      * @param x The new property value.
311      * @since 1.0
312      */
313     public static final void shadowOffsetX(Canvas c, Number x) {
314         JsCanvasRenderingContext2D.shadowOffsetX.with(c.context, x);
315     }
316 
317     /**
318      * <p>Sets the {@link JsCanvasRenderingContext2D#shadowOffsetY} property of a canvas widget.</p>
319      * <p>This method sets the {@link JsCanvasRenderingContext2D#shadowOffsetY} property of the 
320      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
321      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
322      * @param c The current canvas widget.
323      * @param y The new property value.
324      * @since 1.0
325      */
326     public static final void shadowOffsetY(Canvas c, Number y) {
327         JsCanvasRenderingContext2D.shadowOffsetY.with(c.context, y);
328     }
329 
330     /**
331      * <p>Gets the {@link JsCanvasRenderingContext2D#strokeStyle} property of a canvas widget.</p>
332      * @param c The current canvas widget.
333      * @return The {@link JsCanvasRenderingContext2D#strokeStyle} property of the underlying 
334      * {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
335      * <tt>&lt;canvas&gt;</tt> element.
336      * @since 1.0
337      */
338     public static final Object strokeStyle(Canvas c) {
339         return JsCanvasRenderingContext2D.strokeStyle.with(c.context);
340     }
341 
342     /**
343      * <p>Sets the {@link JsCanvasRenderingContext2D#strokeStyle} property of a canvas widget.</p>
344      * <p>This method sets the {@link JsCanvasRenderingContext2D#strokeStyle} property of the 
345      * underlying {@link JsCanvasRenderingContext2D} object created from the wrapped HTML 
346      * <tt>&lt;canvas&gt;</tt> element to the specified value.</p>
347      * @param c The current canvas widget.
348      * @param o The new property value.
349      * @since 1.0
350      */
351     public static final void strokeStyle(Canvas c, Object o) {
352         JsCanvasRenderingContext2D.strokeStyle.with(c.context, o);
353     }
354 
355     /**
356      * <p>Adds an arc to the current sub-path of a canvas, using a center point and radius.</p>
357      * <p>The first five arguments to this method specify a start point and an end point 
358      * on the circumference of a circle. Invoking this method adds a straight line 
359      * between the current point and the start point to the current sub-path. Next it 
360      * adds the arc along the circumference of the circle between the start and end 
361      * points to the sub-path. The final argument specifies the direction in which the 
362      * circle should be traversed to connect the start and end points. This method 
363      * leaves the current point set to the end point of the arc.</p>
364      * @param c The current canvas widget.
365      * @param x The X coordinate of the center of the circle describing the arc.
366      * @param y The Y coordinate of the center of the circle describing the arc.
367      * @param r The radius of the circle that defines the arc.
368      * @param a1 Specifies the start point of the arc along the circle. The angles is 
369      * measured in radians. The three o'clock position along the positive X axis is an 
370      * angle of 0, and angles increase in the clockwise direction.
371      * @param a2 Specifies the end point of the arc along the circle. The angle is 
372      * measured in radians. The three o'clock position along the positive X axis is an 
373      * angle of 0, and angles increase in the clockwise direction.
374      * @param ccw Whether the arc is traversed counterclockwise (<tt>true</tt>) 
375      * or clockwise (<tt>false</tt>) along the circle's circumference.
376      * @since 1.0
377      * @see #arcTo(Canvas, Number, Number, Number, Number, Number)
378      * @see #beginPath(Canvas)
379      * @see #closePath(Canvas)
380      */
381     public static final void arc(Canvas c, Number x, Number y, Number r, Number a1, Number a2, Boolean ccw) {
382         c.context.arc(x, y, r, a1, a2, ccw);
383     }
384 
385     /**
386      * <p>Adds an arc to the current sub-path, using tangent points and a radius.</p>
387      * <p>This method adds an arc to the current sub-path but describes that arc much 
388      * differently than the {@link #arc(Canvas, Number, Number, Number, Number, Number, Boolean)} 
389      * method does. The arc that is added to the path by this method is a portion of a 
390      * circle with the specified radius. The arc has one point tangent to the line from 
391      * the current position to the point <tt>(x1, y1)</tt> and one point that is tangent 
392      * to the line from the point <tt>(x1, y1)</tt> to the point <tt>(x2, y2)</tt>. The 
393      * arc begins and ends at these two tangent points and is drawn in the direction 
394      * that connects those two points with the shortest arc.</p>
395      * <p>In many common uses, the arc begins at the current position and ends at 
396      * the point <tt>(x2, y2)</tt>, but this is not always the case. If the current 
397      * position is not the same as the starting point of the arc, this method adds a 
398      * straight line from the current position to the start position of the arc. This 
399      * method always leaves the current position set to the end point of the arc.</p>
400      * @param c The current canvas widget.
401      * @param x1 The X coordinate of the control point associated with the arc's start point.
402      * @param y1 The Y coordinate of the control point associated with the arc's start point.
403      * @param x2 The X coordinate of the control point associated with the arc's end point.
404      * @param y2 The Y coordinate of the control point associated with the arc's end point.
405      * @param r The radius of the circle that defines the arc.
406      * @since 1.0
407      * @see #arc(Canvas, Number, Number, Number, Number, Number, Boolean)
408      */
409     public static final void arcTo(Canvas c, Number x1, Number y1, Number x2, Number y2, Number r) {
410         c.context.arcTo(x1, y1, x2, y2, r);
411     }
412 
413     /**
414      * <p>Starts a new path (or a collection of sub-paths) in a canvas.</p>
415      * <p>This method discards any currently defined path and begins a new one. It sets 
416      * the current point to (0,0).</p>
417      * <p>When the context for a canvas is first created, this method is implicitly 
418      * called.</p>
419      * @param c The current canvas widget.
420      * @since 1.0
421      * @see #closePath(Canvas)
422      * @see #fill(Canvas)
423      * @see #stroke(Canvas)
424      */
425     public static final void beginPath(Canvas c) {
426         c.context.beginPath();
427     }
428 
429     /**
430      * <p>Adds a cubic Bézier curve to the current sub-path.</p>
431      * <p>The start point of the curve is the current point of the canvas, and the end 
432      * point is <tt>(x,y)</tt>. The two Bezier control points <tt>(x1, y1)</tt> and 
433      * <tt>(x2, y2)</tt> define the shape of the curve. When this method returns, the 
434      * current position is <tt>(x,y)</tt>.</p>
435      * @param c The current canvas widget.
436      * @param x1 The X coordinate of the control point associated with the curve's 
437      * start point (the current position).
438      * @param y1 The Y coordinate of the control point associated with the curve's 
439      * start point (the current position).
440      * @param x2 The X coordinate of the control point associated with the curve's end point.
441      * @param y2 The Y coordinate of the control point associated with the curve's end point.
442      * @param x The X coordinate of the curve's end point.
443      * @param y The Y coordinate of the curve's end point.
444      * @since 1.0
445      * @see #quadraticCurveTo(Canvas, Number, Number, Number, Number)
446      */
447     public static final void bezierCurveTo(Canvas c, Number x1, Number y1, Number x2, Number y2, Number x, Number y) {
448         c.context.bezierCurveTo(x1, y1, x2, y2, x, y);
449     }
450 
451     /**
452      * <p>Erases the pixels in a rectangular area of a canvas.</p>
453      * <p>This method erases the specified rectangle, filling it with a transparent color.</p>
454      * @param c The current canvas widget.
455      * @param x The X coordinate of the upper-left corner of the rectangle.
456      * @param y The Y coordinate of the upper-left corner of the rectangle.
457      * @param w The X dimension of the rectangle.
458      * @param h The Y dimension of the rectangle.
459      * @since 1.0
460      */
461     public static final void clearRect(Canvas c, Number x, Number y, Number w, Number h) {
462         c.context.clearRect(x, y, w, h);
463     }
464 
465     /**
466      * <p>Uses the current path as the clipping region for subsequent drawing operations.</p>
467      * <p>This method clips the current path using the current clipping path and then 
468      * uses the clipped path as the new clipping path. Note that there is no way to 
469      * enlarge the clipping path. If you want a temporary clipping path, you should 
470      * first call {@link #save(Canvas)} in order to use {@link #restore(Canvas)} to restore the 
471      * original clipping path. The default clipping path for a canvas is the canvas 
472      * rectangle itself.</p>
473      * <p>This method resets the current path so that it is empty.</p>
474      * @param c The current canvas widget.
475      * @since 1.0
476      */
477     public static final void clip(Canvas c) {
478         c.context.clip();
479     }
480 
481     /**
482      * <p>Closes the current sub-path if it's open.</p>
483      * <p>If the current sub-path of the canvas is open, this method closes it by adding 
484      * a line connecting the current point to the sub-path's starting point. If the 
485      * sub-path is already closed, this method does nothing. Once a sub-path is closed, 
486      * no more lines or curves can be added to it. To continue adding to the path, 
487      * you must begin a new sub-path by calling {@link #moveTo(Canvas, Number, Number)}.</p>
488      * <p>You do not need to call {@link #closePath(Canvas)} before stroking or filling a path. 
489      * Paths are implicitly closed when filled (and also when you call {@link #clip(Canvas)}).</p>
490      * @param c The current canvas widget.
491      * @since 1.0
492      * @see #beginPath(Canvas)
493      * @see #moveTo(Canvas, Number, Number)
494      * @see #stroke(Canvas)
495      * @see #fill(Canvas)
496      */
497     public static final void closePath(Canvas c) {
498         c.context.closePath();
499     }
500 
501     /**
502      * <p>Returns a {@link JsCanvasGradient} object that represents a linear color 
503      * gradient.</p>
504      * <p>This method creates and returns a new {@link JsCanvasGradient} object that 
505      * linearly interpolates colors between the specified start point and end point. 
506      * Note that this method does not specify any colors for the gradient. Use the 
507      * {@link JsCanvasGradient#addColorStop(Number, String)} method of the returned 
508      * object to do that. To stroke lines or fill areas using a gradient, assign a 
509      * {@link JsCanvasGradient} object to the {@link JsCanvasRenderingContext2D#strokeStyle} 
510      * or {@link JsCanvasRenderingContext2D#fillStyle} properties.</p>
511      * @param c The current canvas widget.
512      * @param x1 The X coordinate of the gradient's start point.
513      * @param y1 The Y coordinate of the gradient's start point.
514      * @param x2 The X coordinate of the gradient's end point.
515      * @param y2 The Y coordinate of the gradient's end point.
516      * @return A {@link JsCanvasGradient} object representing the linear color gradient.
517      * @since 1.0
518      * @see #createRadialGradient(Canvas, Number, Number, Number, Number, Number, Number)
519      */
520     public static final JsCanvasGradient createLinearGradient(Canvas c, Number x1, Number y1,
521             Number x2, Number y2) {
522         return c.context.createLinearGradient(x1, y1, x2, y2);
523     }
524 
525     /**
526      * <p>Returns a {@link JsCanvasPattern} object that represents a tiled image.</p>
527      * <p>This method creates and returns a new {@link JsCanvasPattern} object that 
528      * represents the pattern defined by a tiled image. To use a pattern for stroking 
529      * lines or filling areas, use a {@link JsCanvasPattern} object as the value of the 
530      * {@link JsCanvasRenderingContext2D#strokeStyle} or {@link JsCanvasRenderingContext2D#fillStyle} 
531      * properties.</p>
532      * @param c The current canvas widget.
533      * @param image The image to be tiled. This argument is typically 
534      * {@link JsHTMLImageElement} object, but you may also use a {@link JsHTMLCanvasElement} 
535      * element (see {@link #createPattern(Canvas, JsHTMLCanvasElement, String)}).
536      * @param repeat Specifies how the image is tiled. The possible values are the following:
537      * <ul>
538      * <li>"repeat": Tile the image in both directions. This is the default.</li>
539      * <li>"repeat-x": Tile the image in the X dimension only.</li>
540      * <li>"repeat-y": Tile the image in the Y dimension only.</li>
541      * <li>"no-repeat": Do not tile the image; use it a single time only.</li>
542      * </ul>
543      * @return A {@link JsCanvasPattern} object representing the pattern.
544      * @since 1.0
545      * @see #createPattern(Canvas, JsHTMLCanvasElement, String)
546      */
547     public static final JsCanvasPattern createPattern(Canvas c, JsHTMLImageElement image, String repeat) {
548         return c.context.createPattern(image, repeat);
549     }
550 
551     /**
552      * <p>Returns a {@link JsCanvasPattern} object that represents a tiled image.</p>
553      * <p>This method creates and returns a new {@link JsCanvasPattern} object that 
554      * represents the pattern defined by a tiled image. To use a pattern for stroking 
555      * lines or filling areas, use a {@link JsCanvasPattern} object as the value of the 
556      * {@link JsCanvasRenderingContext2D#strokeStyle} or {@link JsCanvasRenderingContext2D#fillStyle} 
557      * properties.</p>
558      * @param c The current canvas widget.
559      * @param image The image to be tiled. This argument is typically 
560      * {@link JsHTMLImageElement} object, but you may also use a {@link JsHTMLCanvasElement} 
561      * element (see {@link #createPattern(Canvas, JsHTMLCanvasElement, String)}).
562      * @param repeat Specifies how the image is tiled. The possible values are the following:
563      * <ul>
564      * <li>"repeat": Tile the image in both directions. This is the default.</li>
565      * <li>"repeat-x": Tile the image in the X dimension only.</li>
566      * <li>"repeat-y": Tile the image in the Y dimension only.</li>
567      * <li>"no-repeat": Do not tile the image; use it a single time only.</li>
568      * </ul>
569      * @return A {@link JsCanvasPattern} object representing the pattern.
570      * @since 1.0
571      * @see #createPattern(Canvas, JsHTMLCanvasElement, String)
572      */
573     public static final JsCanvasPattern createPattern(Canvas c, JsHTMLCanvasElement image, String repeat) {
574         return c.context.createPattern(image, repeat);
575     }
576 
577     /**
578      * <p>Returns a {@link JsCanvasGradient} object that represents a radial color 
579      * gradient.</p>
580      * <p>This method creates and returns a new {@link JsCanvasGradient} object that 
581      * radially interpolates colors between the circumferences of the two specified 
582      * circles. Note that this method does not specify any colors for the gradient. 
583      * Use the {@link JsCanvasGradient#addColorStop(Number, String)} method of the 
584      * returned object to do that. To stroke lines or fill areas using a gradient, 
585      * assign a {@link JsCanvasGradient} object to the {@link JsCanvasRenderingContext2D#strokeStyle} 
586      * or {@link JsCanvasRenderingContext2D#fillStyle} properties.</p>
587      * @param c The current canvas widget.
588      * @param x1 The X coordinate of the center of the starting circle.
589      * @param y1 The Y coordinate of the center of the starting circle.
590      * @param r1 The radius of the starting circle.
591      * @param x2 The X coordinate of the center of the ending circle.
592      * @param y2 The Y coordinate of the center of the starting circle.
593      * @param r2 The radius of the ending circle.
594      * @return A {@link JsCanvasGradient} object representing the radial color gradient.
595      * @since 1.0
596      * @see #createLinearGradient(Canvas, Number, Number, Number, Number)
597      */
598     public static final JsCanvasGradient createRadialGradient(Canvas c, Number x1, Number y1, Number r1, Number x2, Number y2, Number r2) {
599         return c.context.createRadialGradient(x1, y1, r1, x2, y2, r2);
600     }
601 
602     /**
603      * <p>Draws an image.</p>
604      * <p>This method copies the entire image to the canvas, placing its upper-left 
605      * corner at the specified point and mapping each image pixel to one unit in the 
606      * canvas coordinate system.</p>
607      * @param c The current canvas widget.
608      * @param image The image to be drawn. This argument may also be a 
609      * {@link JsHTMLCanvasElement} object.
610      * @param x The X coordinate of the point at which the upper-left corner of the 
611      * image is drawn.
612      * @param y The Y coordinate of the point at which the upper-left corner of the 
613      * image is drawn.
614      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number)
615      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number, Number, Number)
616      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number, Number, Number, Number, Number, Number, Number)
617      * @since 1.0
618      */
619     public static final void drawImage(Canvas c, JsHTMLImageElement image, Number x, Number y) {
620         c.context.drawImage(image, x, y);
621     }
622 
623     /**
624      * <p>Draws an image.</p>
625      * <p>This method copies the entire image to the canvas, placing its upper-left 
626      * corner at the specified point and mapping each image pixel to one unit in the 
627      * canvas coordinate system.</p>
628      * @param c The current canvas widget.
629      * @param image The image to be drawn. This argument may also be an {@link JsHTMLImageElement} 
630      * object representing an <tt>&lt;img&gt;</tt> tag, or an offscreen image.
631      * @param x The X coordinate of the point at which the upper-left corner of the 
632      * image is drawn.
633      * @param y The Y coordinate of the point at which the upper-left corner of the 
634      * image is drawn.
635      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number)
636      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number, Number, Number)
637      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number, Number, Number, Number, Number, Number, Number)
638      * @since 1.0
639      */
640     public static final void drawImage(Canvas c, JsHTMLCanvasElement image, Number x, Number y) {
641         c.context.drawImage(image, x, y);
642     }
643 
644     /**
645      * <p>Draws an image.</p>
646      * <p>This method copies the entire image to the canvas and allows you to specify 
647      * the desired width and height of the image in canvas units.</p>
648      * @param c The current canvas widget.
649      * @param image The image to be drawn. This argument may also be an 
650      * {@link JsHTMLCanvasElement} object.
651      * @param x The X coordinate of the point at which the upper-left corner of the 
652      * image is drawn.
653      * @param y The Y coordinate of the point at which the upper-left corner of the 
654      * image is drawn.
655      * @param w The width at which the image should be drawn. Specifying this argument 
656      * causes the image to be scaled.
657      * @param h The height at which the image should be drawn. Specifying this argument 
658      * causes the image to be scaled.
659      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number, Number, Number)
660      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number)
661      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number, Number, Number, Number, Number, Number, Number)
662      * @since 1.0
663      */
664     public static final void drawImage(
665             Canvas c, JsHTMLImageElement image, Number x, Number y, Number w, Number h) {
666         c.context.drawImage(image, x, y, w, h);
667     }
668     /**
669      * <p>Draws an image.</p>
670      * <p>This method allows you to specify any rectangular region of the image and 
671      * copy it, with arbitrary scaling to any position within the canvas.</p>
672      * @param c The current canvas widget.
673      * @param image The image to be drawn. This argument may also be an 
674      * {@link JsHTMLCanvasElement} object.
675      * @param x1 The X coordinate of the upper-left corner of the region of the image 
676      * that is to be drawn. This argument must be an integer measured in image pixels.
677      * @param y1 The X coordinate of the upper-left corner of the region of the image 
678      * that is to be drawn. This argument must be an integer measured in image pixels.
679      * @param w1 The X dimension, in image pixels, of the region of the image that is 
680      * to be drawn.
681      * @param h1 The Y dimension, in image pixels, of the region of the image that is 
682      * to be drawn.
683      * @param x2 The canvas X coordinate at which the upper-left corner of the image 
684      * region is to be drawn.
685      * @param y2 The canvas Y coordinate at which the upper-left corner of the image 
686      * region is to be drawn.
687      * @param w2 The canvas X dimension at which the image region should be drawn.
688      * @param h2 The canvas Y dimension at which the image region should be drawn.
689      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number, Number, Number, Number, Number, Number, Number)
690      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number)
691      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number, Number, Number)
692      * @since 1.0
693      */
694     public static final void drawImage(Canvas c, JsHTMLImageElement image, 
695             Number x1, Number y1, Number w1, Number h1,
696             Number x2, Number y2, Number w2, Number h2) {
697         c.context.drawImage(image, x1, y1, w1, h1, x2, y2, w2, h2);
698     }
699     /**
700      * <p>Draws an image.</p>
701      * <p>This method copies the entire image to the canvas and allows you to specify 
702      * the desired width and height of the image in canvas units.</p>
703      * @param c The current canvas widget.
704      * @param image The image to be drawn. This argument may also be an {@link JsHTMLImageElement} 
705      * object representing an <tt>&lt;img&gt;</tt> tag, or an offscreen image.
706      * @param x The X coordinate of the point at which the upper-left corner of the 
707      * image is drawn.
708      * @param y The Y coordinate of the point at which the upper-left corner of the 
709      * image is drawn.
710      * @param w The width at which the image should be drawn. Specifying this argument 
711      * causes the image to be scaled.
712      * @param h The height at which the image should be drawn. Specifying this argument 
713      * causes the image to be scaled.
714      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number, Number, Number)
715      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number)
716      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number, Number, Number, Number, Number, Number, Number)
717      * @since 1.0
718      */
719     public static final void drawImage(
720             Canvas c, JsHTMLCanvasElement image, Number x, Number y, Number w, Number h) {
721         c.context.drawImage(image, x, y, w, h);
722     }
723     /**
724      * <p>Draws an image.</p>
725      * <p>This method allows you to specify any rectangular region of the image and 
726      * copy it, with arbitrary scaling to any position within the canvas.</p>
727      * @param c The current canvas widget.
728      * @param image The image to be drawn. This argument may also be an {@link JsHTMLImageElement} 
729      * object representing an <tt>&lt;img&gt;</tt> tag, or an offscreen image.
730      * @param x1 The X coordinate of the upper-left corner of the region of the image 
731      * that is to be drawn. This argument must be an integer measured in image pixels.
732      * @param y1 The X coordinate of the upper-left corner of the region of the image 
733      * that is to be drawn. This argument must be an integer measured in image pixels.
734      * @param w1 The X dimension, in image pixels, of the region of the image that is 
735      * to be drawn.
736      * @param h1 The Y dimension, in image pixels, of the region of the image that is 
737      * to be drawn.
738      * @param x2 The canvas X coordinate at which the upper-left corner of the image 
739      * region is to be drawn.
740      * @param y2 The canvas Y coordinate at which the upper-left corner of the image 
741      * region is to be drawn.
742      * @param w2 The canvas X dimension at which the image region should be drawn.
743      * @param h2 The canvas Y dimension at which the image region should be drawn.
744      * @see #drawImage(Canvas, JsHTMLImageElement, Number, Number, Number, Number, Number, Number, Number, Number)
745      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number)
746      * @see #drawImage(Canvas, JsHTMLCanvasElement, Number, Number, Number, Number)
747      * @since 1.0
748      */
749     public static final void drawImage(Canvas c, JsHTMLCanvasElement image, 
750             Number x1, Number y1, Number w1, Number h1,
751             Number x2, Number y2, Number w2, Number h2) {
752         c.context.drawImage(image, x1, y1, w1, h1, x2, y2, w2, h2);
753     }
754 
755     /**
756      * <p>Fills the interior of the current path with the color, gradient, or pattern 
757      * specified by the {@link #fillStyle} property.</p>
758      * @param c The current canvas widget.
759      * @since 1.0
760      * @see #fillRect(Canvas, Number, Number, Number, Number)
761      */
762     public static final void fill(Canvas c) {
763         c.context.fill();
764     }
765 
766     /**
767      * <p>Paints or fills a rectangle.</p>
768      * <p>This method fills the specified rectangle with the color, gradient, or pattern 
769      * specified by the {@link JsCanvasRenderingContext2D#fillStyle} property.</p>
770      * <p>Current implementations of this method also clear the path as if 
771      * {@link #beginPath(Canvas)} had been called. This surprising behavior may not be 
772      * standardized and should not be relied on.</p>
773      * @param c The current canvas widget.
774      * @param x The X coordinate of the upper-left corner of the rectangle.
775      * @param y The Y coordinate of the upper-left corner of the rectangle.
776      * @param w The X dimension of the rectangle.
777      * @param h The Y dimension of the rectangle.
778      * @since 1.0
779      * @see #fill(Canvas)
780      * @see #rect(Canvas, Number, Number, Number, Number)
781      * @see #strokeRect(Canvas, Number, Number, Number, Number)
782      */
783     public static final void fillRect(Canvas c, Number x, Number y, Number w, Number h) {
784         c.context.fillRect(x, y, w, h);
785     }
786 
787     /**
788      * <p>Adds a straight line segment to the current sub-path.</p>
789      * <p>This method adds a straight line to the current sub-path. The line begins at 
790      * the current point and ends at <tt>(x,y)</tt>.</p>
791      * <p>When this method returns, the current position is <tt>(x,y)</tt>.</p>
792      * @param x The X coordinate of the end point of the line.
793      * @param y The Y coordinate of the end point of the line.
794      * @since 1.0
795      * @see #beginPath(Canvas)
796      * @see #moveTo(Canvas, Number, Number)
797      */
798     public static final void lineTo(Canvas c, Number x, Number y) {
799         c.context.lineTo(x, y);
800     }
801 
802     /**
803      * <p>Sets the current position and begins a new sub-path.</p>
804      * <p>This method sets the current position to <tt>(x,y)</tt> and creates a new 
805      * sub-path with this as its first point. If there was a previous sub-path and it 
806      * consisted of just one point, that sub-path is removed from the path.</p>
807      * @param c The current canvas widget.
808      * @param x The X coordinate of the new current point.
809      * @param y The Y coordinate of the new current point.
810      * @since 1.0
811      * @see #beginPath(Canvas)
812      */
813     public static final void moveTo(Canvas c, Number x, Number y) {
814         c.context.moveTo(x, y);
815     }
816 
817     /**
818      * <p>Adds a quadratic Bézier curve to the current sub-path.</p>
819      * <p>This method adds a quadratic Bézier curve segment to the current sub-path. 
820      * The curve starts at the current point and ends at <tt>(x,y)</tt>. The control 
821      * point <tt>(cx, cy)</tt> specifies the shape of the curve between these two points.</p>
822      * <p>When this method returns, the current position is <tt>(x,y)</tt>.</p>
823      * @param cx The X coordinate of the control point.
824      * @param cy The Y coordinate of the control point.
825      * @param x The X coordinate of the end point.
826      * @param y The Y coordinate of the end point.
827      * @since 1.0
828      * @see #bezierCurveTo(Canvas, Number, Number, Number, Number, Number, Number)
829      */
830     public static final void quadraticCurveTo(Canvas c, Number cx, Number cy, Number x, Number y) {
831         c.context.quadraticCurveTo(cx, cy, x, y);
832     }
833 
834     /**
835      * <p>Adds a rectangle sub-path to the current path.</p>
836      * <p>This method adds a rectangle to the path. This rectangle is in a sub-path of 
837      * its own and is not connected to any other sub-paths in the path.</p>
838      * <p>When this method returns, the current position is (0,0).</p>
839      * @param c The current canvas widget.
840      * @param x The X coordinate of the upper-left corner of the rectangle.
841      * @param y The Y coordinate of the upper-left corner of the rectangle.
842      * @param w The X dimension of the rectangle.
843      * @param h The Y dimension of the rectangle.
844      * @since 1.0
845      * @see #fillRect(Canvas, Number, Number, Number, Number)
846      * @see #strokeRect(Canvas, Number, Number, Number, Number)
847      */
848     public static final void rect(Canvas c, Number x, Number y, Number w, Number h) {
849         c.context.rect(x, y, w, h);
850     }
851 
852     /**
853      * <p>Resets the canvas to the graphics state most recently saved.</p>
854      * <p>This method pops the stack of saved graphics states and restores the values of 
855      * the {@link JsCanvasRenderingContext2D} properties, the clipping path, and the 
856      * transformation matrix.</p>
857      * @param c The current canvas widget.
858      * @since 1.0
859      * @see #save(Canvas)
860      */
861     public static final void restore(Canvas c) {
862         c.context.restore();
863     }
864 
865     /**
866      * <p>Rotates the canvas.</p>
867      * <p>This method alters the mapping between canvas coordinates and the pixels of 
868      * the <tt>&lt;canvas&gt;</tt> element in the web browser so that any subsequent 
869      * drawing appears rotated within the canvas by the specified angle. It does not 
870      * rotate the <tt>&lt;canvas&gt;</tt> element itself.</p>
871      * <p>Note that the angle is specified in radians. To convert degrees to radians, 
872      * multiply by {@link js.MathLike#PI} and divide by 180.</p>
873      * @param c The current canvas widget.
874      * @param a The amount of rotation, in radians. Positive values result in clockwise 
875      * rotation, and negative values result in counterclockwise rotation.
876      * @since 1.0
877      * @see #rotate(Canvas, NumberLike)
878      * @see #scale(Canvas, Number, Number)
879      * @see #translate(Canvas, Number, Number)
880      */
881     public static final void rotate(Canvas c, Number a) {
882         c.context.rotate(a);
883     }
884 
885     /**
886      * <p>Rotates the canvas.</p>
887      * <p>This method alters the mapping between canvas coordinates and the pixels of 
888      * the <tt>&lt;canvas&gt;</tt> element in the web browser so that any subsequent 
889      * drawing appears rotated within the canvas by the specified angle. It does not 
890      * rotate the <tt>&lt;canvas&gt;</tt> element itself.</p>
891      * <p>Note that the angle is specified in radians. To convert degrees to radians, 
892      * multiply by {@link js.MathLike#PI} and divide by 180.</p>
893      * @param c The current canvas widget.
894      * @param a The amount of rotation, in radians. Positive values result in clockwise 
895      * rotation, and negative values result in counterclockwise rotation.
896      * @since 1.0
897      * @see #rotate(Canvas, Number)
898      * @see #scale(Canvas, Number, Number)
899      * @see #translate(Canvas, Number, Number)
900      */
901     public static final void rotate(Canvas c, NumberLike<?> a) {
902         c.context.rotate(a);
903     }
904 
905     /**
906      * <p>Saves the properties, clipping region, and transformation matrix of the 
907      * {@link JsCanvasRenderingContext2D} object.</p>
908      * @param c The current canvas widget.
909      * @since 1.0
910      * @see #restore(Canvas)
911      */
912     public static final void save(Canvas c) {
913         c.context.save();
914     }
915 
916     /**
917      * <p>Scales the user coordinate system of the canvas.</p>
918      * <p>This method adds a scale transformation to the current transformation matrix 
919      * of the canvas. Scaling is done with independent horizontal and vertical scaling 
920      * factors.</p>
921      * <p>Specifying a negative value for <tt>sx</tt> causes X coordinates to be flipped 
922      * across the Y axis, and a negative value of <tt>sy</tt> causes Y coordinates to 
923      * be flipped across the X axis.</p>
924      * @param c The current canvas widget.
925      * @param sx The horizontal scaling factor.
926      * @param sy The vertical scaling factor.
927      * @since 1.0
928      * @see #rotate(Canvas, Number)
929      * @see #rotate(Canvas, NumberLike)
930      * @see #translate(Canvas, Number, Number)
931      */
932     public static final void scale(Canvas c, Number sx, Number sy) {
933         c.context.scale(sx, sy);
934     }
935 
936     /**
937      * <p>Draws, or strokes, a line following the current path.</p>
938      * <p>The line is drawn according to the {@link JsCanvasRenderingContext2D#lineWidth}, 
939      * {@link JsCanvasRenderingContext2D#lineJoin}, {@link JsCanvasRenderingContext2D#lineCap}, 
940      * and {@link JsCanvasRenderingContext2D#strokeStyle} properties, among others.</p>
941      * @param c The current canvas widget.
942      * @since 1.0
943      * @see #fill(Canvas)
944      * @see #strokeRect(Canvas, Number, Number, Number, Number)
945      */
946     public static final void stroke(Canvas c) {
947         c.context.stroke();
948     }
949 
950     /**
951      * <p>Draws a rectangle without filling it.</p>
952      * <p>This method draws the outline, but does not fill the interior, of a rectangle 
953      * with the specified position and size. Line color and line width are specified by 
954      * the {@link JsCanvasRenderingContext2D#strokeStyle} and {@link JsCanvasRenderingContext2D#lineWidth} 
955      * properties. The appearance of the rectangle corners are specified by the 
956      * {@link JsCanvasRenderingContext2D#lineJoin} property.</p>
957      * <p>Current implementations of this method clear the path as if {@link #beginPath(Canvas)} 
958      * had been called. This surprising behavior may not be standardized and should not 
959      * be relied on.</p>
960      * @param c The current canvas widget.
961      * @param x The X coordinate of the upper-left corner of the rectangle.
962      * @param y The Y coordinate of the upper-left corner of the rectangle.
963      * @param w The X dimension of the rectangle.
964      * @param h The Y dimension of the rectangle.
965      * @since 1.0
966      * @see #fillRect(Canvas, Number, Number, Number, Number)
967      * @see #rect(Canvas, Number, Number, Number, Number)
968      * @see #stroke(Canvas)
969      */
970     public static final void strokeRect(Canvas c, Number x, Number y, Number w, Number h) {
971         c.context.strokeRect(x, y, w, h);
972     }
973 
974     /**
975      * <p>Translates the user coordinate system of the canvas.</p>
976      * <p>This method adds horizontal and vertical offsets to the transformation matrix 
977      * of the canvas. The arguments <tt>dx</tt> and <tt>dy</tt> are added to all points 
978      * in any subsequently defined paths.</p>
979      * @param c The current canvas widget.
980      * @param dx The amount to translate in the X dimension.
981      * @param dy The amount to translate in the Y dimension.
982      * @since 1.0
983      * @see #rotate(Canvas, Number)
984      * @see #rotate(Canvas, NumberLike)
985      * @see #scale(Canvas, Number, Number)
986      */
987     public static final void translate(Canvas c, Number dx, Number dy) {
988         c.context.translate(dx, dy);
989     }
990 }