Class Graphics
The Graphics class exposes an easy to use API for generating vector drawing instructions and drawing them to a specified context.
Note that you can use Graphics without any dependency on the Easel framework by calling draw() directly,
or it can be used with the Shape object to draw vector graphics within the context of an Easel display list.
Note that all drawing methods in Graphics return the Graphics instance, so they can be chained together. For example, the following
line of code would generate the instructions to draw a rectangle with a red stroke and blue fill, then render it to the specified
context2D:
myGraphics.beginStroke("#F00").beginFill("#00F").drawRect(20, 20, 100, 50).draw(myContext2D);
Constructor
Graphics
(
instructions
)
- Parameters:
-
instructions
<String>
Optional. This is a string that will be eval'ed in the scope of this Graphics object.
This provides a mechanism for generating a vector shape from a serialized string. Ex.
"beginFill('#F00');drawRect(0, 0, 10, 10);"
Properties
_active
- protected Boolean
Default Value: false
_ctx
- protected static CanvasRenderingContext2D
_dirty
- protected Boolean
Default Value: false
bf
- protected object
Shortcut to beginBitmapFill.
bs
- protected object
Shortcut to beginBitmapStroke.
bt
- protected object
Shortcut to bezierCurveTo.
Maps the familiar ActionScript curveTo() method to the functionally similar quatraticCurveTo() method.
dp
- protected object
Shortcut to drawPolyStar.
Maps the familiar ActionScript drawRect() method to the functionally similar rect() method.
lf
- protected object
Shortcut to beginLinearGradientFill.
ls
- protected object
Shortcut to beginLinearGradientStroke.
qt
- protected object
Shortcut to quadraticCurveTo / curveTo.
rc
- protected object
Shortcut to drawRoundRectComplex.
rf
- protected object
Shortcut to beginRadialGradientFill.
rr
- protected object
Shortcut to drawRoundRect.
rs
- protected object
Shortcut to beginRadialGradientStroke.
ss
- protected object
Shortcut to setStrokeStyle.
Maps numeric values for the caps parameter of setStrokeStyle to corresponding string values.
This is primarily for use with the tiny API. The mappings are as follows: 0 to "butt",
1 to "round", and 2 to "square".
For example, myGraphics.ss(16, 2) would set the line caps to "square".
Maps numeric values for the joints parameter of setStrokeStyle to corresponding string values.
This is primarily for use with the tiny API. The mappings are as follows: 0 to "miter",
1 to "round", and 2 to "bevel".
For example, myGraphics.ss(16, 0, 2) would set the line joints to "bevel".
Methods
protected
void
_newPath
(
)
protected
void
_setProp
(
name
,
value
)
used to create Commands that set properties
- Parameters:
-
name
<String>
-
value
<String>
- Returns:
void
protected
void
_updateInstructions
(
)
Graphics
arc
(
x
,
y
,
radius
,
startAngle
,
endAngle
,
anticlockwise
)
Draws an arc defined by the radius, startAngle and endAngle arguments, centered at the position (x, y). For example
arc(100, 100, 20, 0, Math.PI*2) would draw a full circle with a radius of 20 centered at (100, 100). For detailed
information, read the
whatwg spec.
- Parameters:
-
x
<Number>
-
y
<Number>
-
radius
<Number>
-
startAngle
<Number>
Measured in radians.
-
endAngle
<Number>
Measured in radians.
-
anticlockwise
<Boolean>
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
arcTo
(
x1
,
y1
,
x2
,
y2
,
radius
)
Draws an arc with the specified control points and radius. For detailed information, read the
whatwg spec.
- Parameters:
-
x1
<Number>
-
y1
<Number>
-
x2
<Number>
-
y2
<Number>
-
radius
<Number>
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginBitmapFill
(
image
,
repetition
)
Begins a pattern fill using the specified image. This ends the current subpath.
- Parameters:
-
image
<object>
The Image, Canvas, or Video object to use as the pattern.
-
repetition
<String>
Optional. Indicates whether to repeat the image in the fill area. One of "repeat", "repeat-x",
"repeat-y", or "no-repeat". Defaults to "repeat".
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginBitmapStroke
(
image
,
repetition
)
Begins a pattern fill using the specified image. This ends the current subpath.
- Parameters:
-
image
<Image | HTMLCanvasElement | HTMLVideoElement>
The Image, Canvas, or Video object to use as the pattern.
-
repetition
<String>
Optional. Indicates whether to repeat the image in the fill area. One of "repeat", "repeat-x",
"repeat-y", or "no-repeat". Defaults to "repeat".
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginFill
(
color
)
Begins a fill with the specified color. This ends the current subpath.
- Parameters:
-
color
<String>
A CSS compatible color value (ex. "#FF0000" or "rgba(255,0,0,0.5)"). Setting to null will
result in no fill.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginLinearGradientFill
(
colors
,
ratios
,
x0
,
y0
,
x1
,
y1
)
Begins a linear gradient fill defined by the line (x0, y0) to (x1, y1). This ends the current subpath. For example, the
following code defines a black to white vertical gradient ranging from 20px to 120px, and draws a square to display it:
myGraphics.beginLinearGradientFill(["#000","#FFF"], [0, 1], 0, 20, 0, 120).drawRect(20, 20, 120, 120);
- Parameters:
-
colors
<Array[String]>
An array of CSS compatible color values. For example, ["#F00","#00F"] would define a gradient
drawing from red to blue.
-
ratios
<Array[Number]>
An array of gradient positions which correspond to the colors. For example, [0.1, 0.9] would draw
the first color to 10% then interpolating to the second color at 90%.
-
x0
<Number>
The position of the first point defining the line that defines the gradient direction and size.
-
y0
<Number>
The position of the first point defining the line that defines the gradient direction and size.
-
x1
<Number>
The position of the second point defining the line that defines the gradient direction and size.
-
y1
<Number>
The position of the second point defining the line that defines the gradient direction and size.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginLinearGradientStroke
(
colors
,
ratios
,
x0
,
y0
,
x1
,
y1
)
Begins a linear gradient stroke defined by the line (x0, y0) to (x1, y1). This ends the current subpath. For example, the following code defines a black to white vertical gradient ranging from 20px to 120px, and draws a square to display it:
myGraphics.setStrokeStyle(10).beginLinearGradientStroke(["#000","#FFF"], [0, 1], 0, 20, 0, 120).drawRect(20, 20, 120, 120);
- Parameters:
-
colors
<object>
An array of CSS compatible color values. For example, ["#F00","#00F"] would define a gradient drawing from red to blue.
-
ratios
<object>
An array of gradient positions which correspond to the colors. For example, [0.1, 0.9] would draw the first color to 10% then interpolating to the second color at 90%.
-
x0
<object>
The position of the first point defining the line that defines the gradient direction and size.
-
y0
<object>
The position of the first point defining the line that defines the gradient direction and size.
-
x1
<object>
The position of the second point defining the line that defines the gradient direction and size.
-
y1
<object>
The position of the second point defining the line that defines the gradient direction and size.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginRadialGradientFill
(
colors
,
ratios
,
x0
,
y0
,
r0
,
x1
,
y1
,
r1
)
Begins a radial gradient fill. This ends the current subpath. For example, the following code defines a red to blue radial
gradient centered at (100, 100), with a radius of 50, and draws a circle to display it:
myGraphics.beginRadialGradientFill(["#F00","#00F"], [0, 1], 100, 100, 0, 100, 100, 50).drawCircle(100, 100, 50);
- Parameters:
-
colors
<Array[String]>
An array of CSS compatible color values. For example, ["#F00","#00F"] would define a gradient
drawing from red to blue.
-
ratios
<Array[Number]>
An array of gradient positions which correspond to the colors. For example, [0.1, 0.9] would
draw the first color to 10% then interpolating to the second color at 90%.
-
x0
<Number>
Center position of the inner circle that defines the gradient.
-
y0
<Number>
Center position of the inner circle that defines the gradient.
-
r0
<Number>
Radius of the inner circle that defines the gradient.
-
x1
<Number>
Center position of the outer circle that defines the gradient.
-
y1
<Number>
Center position of the outer circle that defines the gradient.
-
r1
<Number>
Radius of the outer circle that defines the gradient.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginRadialGradientStroke
(
colors
,
ratios
,
x0
,
y0
,
r0
,
x1
,
y1
,
r1
)
Begins a radial gradient stroke. This ends the current subpath. For example, the following code defines a red to blue radial gradient centered at (100, 100), with a radius of 50, and draws a rectangle to display it:
myGraphics.setStrokeStyle(10).beginRadialGradientStroke(["#F00","#00F"], [0, 1], 100, 100, 0, 100, 100, 50).drawRect(50, 90, 150, 110);
- Parameters:
-
colors
<object>
An array of CSS compatible color values. For example, ["#F00","#00F"] would define a gradient drawing from red to blue.
-
ratios
<object>
An array of gradient positions which correspond to the colors. For example, [0.1, 0.9] would draw the first color to 10% then interpolating to the second color at 90%, then draw the second color to 100%.
-
x0
<object>
Center position of the inner circle that defines the gradient.
-
y0
<object>
Center position of the inner circle that defines the gradient.
-
r0
<object>
Radius of the inner circle that defines the gradient.
-
x1
<object>
Center position of the outer circle that defines the gradient.
-
y1
<object>
Center position of the outer circle that defines the gradient.
-
r1
<object>
Radius of the outer circle that defines the gradient.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
beginStroke
(
color
)
Begins a stroke with the specified color. This ends the current subpath.
- Parameters:
-
color
<object>
A CSS compatible color value (ex. "#FF0000" or "rgba(255,0,0,0.5)"). Setting to null will result in no stroke.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
bezierCurveTo
(
cp1x
,
cp1y
,
cp2x
,
cp2y
,
x
,
y
)
Draws a bezier curve from the current drawing point to (x, y) using the control points (cp1x, cp1y) and (cp2x, cp2y).
For detailed information, read the
whatwg spec.
method @bezierCurveTo
- Parameters:
-
cp1x
<Number>
-
cp1y
<Number>
-
cp2x
<Number>
-
cp2y
<Number>
-
x
<Number>
-
y
<Number>
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
clear
(
)
Clears all drawing instructions, effectively reseting this Graphics instance.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
clone
(
)
Returns a clone of this Graphics instance.
- Returns:
Graphics
- A clone of the current Graphics instance.
Graphics
closePath
(
)
Closes the current path, effectively drawing a line from the current drawing point to the first drawing point specified
since the fill or stroke was last set.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
void
draw
(
ctx
)
Draws the display object into the specified context ignoring it's visible, alpha, shadow, and transform.
Returns true if the draw was handled (useful for overriding functionality).
NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
- Parameters:
-
ctx
<CanvasRenderingContext2D>
The canvas 2D context object to draw into.
- Returns:
void
Graphics
drawCircle
(
x
,
y
,
radius
)
Draws a circle with the specified radius at (x, y).
- Parameters:
-
x
<Number>
x coordinate center point of circle.
-
y
<Number>
y coordinate center point of circle.
-
radius
<Number>
Radius of circle.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
drawEllipse
(
x
,
y
,
w
,
h
)
Draws an ellipse (oval).
- Parameters:
-
x
<Number>
-
y
<Number>
-
w
<Number>
-
h
<Number>
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
drawPolyStar
(
x
,
y
,
radius
,
sides
,
pointSize
,
angle
)
Draws a star if pointSize is greater than 0 or a regular polygon if pointSize is 0 with the specified number of points.
For example, the following code will draw a familiar 5 pointed star shape centered at 100, 100 and with a radius of 50:
myGraphics.beginFill("#FF0").drawPolyStar(100, 100, 50, 5, 0.6, -90); // -90 makes the first point vertical
- Parameters:
-
x
<Number>
Position of the center of the shape.
-
y
<Number>
Position of the center of the shape.
-
radius
<Number>
The outer radius of the shape.
-
sides
<Number>
The number of points on the star or sides on the polygon.
-
pointSize
<Number>
The depth or "pointy-ness" of the star points. A pointSize of 0 will draw a regular polygon (no points),
a pointSize of 1 will draw nothing because the points are infinitely pointy.
-
angle
<Number>
The angle of the first point / corner. For example a value of 0 will draw the first point directly to the
right of the center.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
drawRoundRect
(
x
,
y
,
w
,
h
,
radius
)
Draws a rounded rectangle with all corners with the specified radius.
- Parameters:
-
x
<Number>
-
y
<Number>
-
w
<Number>
-
h
<Number>
-
radius
<Number>
Corner radius.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
drawRoundRectComplex
(
x
,
y
,
w
,
h
,
radiusTL
,
radiusTR
,
radiusBR
,
radiusBL
)
Draws a rounded rectangle with different corner radiuses.
- Parameters:
-
x
<Number>
-
y
<Number>
-
w
<Number>
-
h
<Number>
-
radiusTL
<Number>
Top left corner radius.
-
radiusTR
<Number>
Top right corner radius.
-
radiusBR
<Number>
Bottom right corner radius.
-
radiusBL
<Number>
Bottom left corner radius.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
endFill
(
)
Ends the current subpath, and begins a new one with no fill. Functionally identical to beginFill(null).
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
endStroke
(
)
Ends the current subpath, and begins a new one with no stroke. Functionally identical to beginStroke(null).
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
static
getHSL
(
hue
,
saturation
,
lightness
,
alpha
)
Returns a CSS compatible color string based on the specified HSL numeric color values in the format "hsla(360,100,100,1.0)",
or if alpha is null then in the format "hsl(360,100,100)". For example, Graphics.getHSL(150, 100, 70) will return
"hsl(150,100,70)".
- Parameters:
-
hue
<Number>
The hue component for the color, between 0 and 360.
-
saturation
<Number>
The saturation component for the color, between 0 and 100.
-
lightness
<Number>
The lightness component for the color, between 0 and 100.
-
alpha
<Number>
Optional. The alpha component for the color where 0 is fully transparent and 1 is fully opaque.
static
getRGB
(
r
,
g
,
b
,
alpha
)
Returns a CSS compatible color string based on the specified RGB numeric color values in the format
"rgba(255,255,255,1.0)", or if alpha is null then in the format "rgb(255,255,255)". For example,
Graphics.getRGB(50, 100, 150, 0.5) will return "rgba(50,100,150,0.5)". It also supports passing a single hex color
value as the first param, and an optional alpha value as the second param. For example, Graphics.getRGB(0xFF00FF, 0.2)
will return "rgba(255,0,255,0.2)".
- Parameters:
-
r
<Number>
The red component for the color, between 0 and 0xFF (255).
-
g
<Number>
The green component for the color, between 0 and 0xFF (255).
-
b
<Number>
The blue component for the color, between 0 and 0xFF (255).
-
alpha
<Number>
Optional. The alpha component for the color where 0 is fully transparent and 1 is fully opaque.
protected
void
initialize
(
instructions
)
Initialization method.
- Parameters:
-
instructions
<String>
- Returns:
void
Graphics
lineTo
(
x
,
y
)
Draws a line from the current drawing point to the specified position, which become the new current drawing point.
For detailed information, read the
whatwg spec.
- Parameters:
-
x
<Number>
The x coordinate the drawing point should draw to.
-
y
<Number>
The y coordinate the drawing point should draw to.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
moveTo
(
x
,
y
)
Moves the drawing point to the specified position.
- Parameters:
-
x
<Number>
The x coordinate the drawing point should move to.
-
y
<Number>
The y coordinate the drawing point should move to.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
quadraticCurveTo
(
cpx
,
cpy
,
x
,
y
)
Draws a quadratic curve from the current drawing point to (x, y) using the control point (cpx, cpy). For detailed information,
read the
whatwg spec.
- Parameters:
-
cpx
<Number>
-
cpy
<Number>
-
x
<Number>
-
y
<Number>
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
rect
(
x
,
y
,
w
,
h
)
Draws a rectangle at (x, y) with the specified width and height using the current fill and/or stroke.
For detailed information, read the
whatwg spec.
- Parameters:
-
x
<Number>
-
y
<Number>
-
w
<Number>
Width of the rectangle
-
h
<Number>
Height of the rectangle
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
Graphics
setStrokeStyle
(
thickness
,
caps
,
joints
,
miter
)
Sets the stroke style for the current subpath. Like all drawing methods, this can be chained, so you can define the stroke style and color in a single line of code like so:
myGraphics.setStrokeStyle(8,"round").beginStroke("#F00");
- Parameters:
-
thickness
<object>
The width of the stroke.
-
caps
<object>
Optional. Indicates the type of caps to use at the end of lines. One of butt, round, or square. Defaults to "butt". Also accepts the values 0 (butt), 1 (round), and 2 (square) for use with the tiny API.
-
joints
<object>
Optional. Specifies the type of joints that should be used where two lines meet. One of bevel, round, or miter. Defaults to "miter". Also accepts the values 0 (miter), 1 (round), and 2 (bevel) for use with the tiny API.
-
miter
<object>
Optional. If joints is set to "miter", then you can specify a miter limit ratio which controls at what point a mitered joint will be clipped.
- Returns:
Graphics
- The Graphics instance the method is called on (useful for chaining calls.)
String
toString
(
)
Returns a string representation of this object.
- Returns:
String
- a string representation of the instance.