Canvas Molecule
Add a 2D canvas.
Comments
Each vector graphic shape on canvas is represented by a shape object. Direct manipulation of the shape object is possible, if you are familiar with the its structure.
{ id: name,
type: 'typeName',
pts: [ {px: 5, py: 10,
cp1: {px: 2, py: 15},
cp2: {px: 2, py: 15}},
...],
pref: {visible: true,
closed: false,
drawBorder: true,
filled: false,
text: 'hello',
...,
shapes: [...] },
center: {px: 10, py: 20},
img: Image };typeName can be null, arc, or group. An arc shape includes a circle or arc segment. A group shape holds all its child shapes in pref.shapes array. Nested groups are possible such as group of groups.
cp1 and cp2 are the first and second control points which are only present for bezier shapes.
If pref.pattern_src is given, img holds the downloaded Image object, allowing you to query for its width and height.
Note: After making changes, you need to call refresh, or the parent droplet’s droplet.paint function, to update to screen.
Double clicking on the droplet enters you into canvas’s edit mode where you can modify each shape interactively. While in edit mode, selecting a shape followed by clicking on the gear icon on the right opens up a configure dialog box that allows you to change individual shape’s drawing preference.
The event callback option in the config dialog, if set, will trigger your supplied function during animation playback. In addition to regular tween variables, the input params contain the following identifiers,
| type | ’update’ or ‘complete’, ‘update’ is sent on each time increment, ‘complete’ is sent on reaching each key frame. |
| shape | the shape ID. |
| track | the track name. |
| keyframe | the index of current key frame (0-based.) |
Optionally, you can assign a category name to each shape and later change its drawing preferences by category (see preferences).
pref.name
string, ( r )
The scriptable name for this molecule. This name can be set using rename function dynamically.
pref.composite
string, ( r, w )
Specifies the style of composition between overlapping shapes.
| source-over | Default. Display the source image wherever the source image is opaque. Display the destination image elsewhere. |
| destination-over | New shapes are drawn behind the existing canvas content. |
| source-in | The new shape is drawn only where both the new shape and the destination canvas overlap. Everything else is made transparent. |
| destination-in | The existing canvas content is kept where both the new shape and existing canvas content overlap. Everything else is made transparent. |
| source-out | The new shape is drawn where it doesn’t overlap the existing canvas content. |
| destination-out | The existing content is kept where it doesn’t overlap the new shape. |
| source-atop | The new shape is only drawn where it overlaps the existing canvas content. |
| destination-atop | The existing canvas is only kept where it overlaps the new shape. The new shape is drawn behind the canvas content. |
| lighter | Display the sum of the source image and destination image, with color values approaching 1 as a limit. |
| darker | Where both shapes overlap the color is determined by subtracting color values. |
| xor | Exclusive OR of the source and destination images. Works only with black and white images and is not recommended for color images. |
| copy | Only draws the new shape and removes everything else. |
pref.fillType
int, ( r, w )
Specifies the style of fill.
| 0 | Default. fill with solid color. (see pref.fr, pref.fg, pref.fb.) |
| 1 | fill with color gradient. (see pref.colorStops.) |
| 2 | fill with pattern. (see pref.pattern_src.) |
| 3 | fill with text. (see pref.text.) |
pref.colorStops
array, ( r, w )
An array of color stops. Each color stop is a string of the following format, rgba(rv, gv, bv, av) offset.
| rv | (int [0, 255]) red component. |
| gv | (int [0, 255]) green component. |
| bv | (int [0, 255]) blue component. |
| av | (int [0, 255]) alpha component. |
| offset | (float [0, 1]) color stop offset. |
pref.textAlign
string, ( r, w )
Specifies the alignment of fill text.
| left | The text is left-aligned. |
| right | The text is right-aligned. |
| center | The text is centered. |
| start | Default. The text is aligned at the normal start of the line (left-aligned for left-to-right locales, right-aligned for right-to-left locales). |
| end | The text is aligned at the normal end of the line (right-aligned for left-to-right locales, left-aligned for right-to-left locales). |
pref.textBaseLine
string, ( r, w )
Specifies the current baseline for drawing text.
| top | The text baseline is the top of the em square. |
| hanging | The text baseline is the hanging baseline. Currently unsupported; this will act like alphabetic. |
| middle | The text baseline is the middle of the em square. |
| alphabetic | Default. The text baseline is the normal alphabetic baseline. |
| ideographic | Currently unsupported; this will act like alphabetic. |
| bottom | The text baseline is the bottom of the bounding box. This differs from the ideographic baseline in that the ideographic baseline doesn’t consider descenders. |
tracks
object, ( r )
Returns the array of animation tracks. Each track is indexed by its shape ID and track name and support the following methods,
| play | play(bool repeat, bool mirror, int repeatCount) or play(bool repeat, int repeatCount), start the animation track. |
| stop | stop animation track. |
| reset | restore track to initial state. |
| delay | delay(int msec), add an initial delay in msec. |
| isPlaying | check if track is currently playing. |
and the following attributes,
| keys | accessor to the array of keyframes. |
| easing | specify the easing function. (e.g. EASING.Exponential.InOut.) |
| easingOption | 0 for on every keyframe or 1 for only the first and last key frames. |
ishape
object, ( r, w )
The accessor to the currently selected shape. (see selectShape.)
addGroup
addGroup(name);
Creates a group with the given name. A group is a special kind of shape object with its type sets to ‘group’. A group is used to hold multiple shapes. Every drawing/transformation operation applied to a group is applied to every shape within that group.
Parameters
| name | (string) a group name. |
Returns
(object) a group.
selectShape
selectShape(name);
Select a shape by name. The selected shape is stored in ishape.
Parameters
| name | (string) a shape name. |
Returns
(object) a shape.
rotateShape
rotateShape( rad, shape, x, y )
Rotate the currently selected shape by rad radian. If shape is given, it rotates the given shape. If x and y are given, it rotate using (x, y) as the pivot point.
Parameters
| rad | (float) angle in radian. |
| shape | (object) Optional. a shape object. |
| x | (int) Optional. x-coordinate. |
| y | (int) Optional. y-coordinate. |
Returns
N/A
rotateShapeByDegree
rotateShape( deg, shape, x, y )
Rotate the currently selected shape by deg degree. If shape is given, it rotates the given shape. If x and y are given, (x, y) is used as the pivot point.
Parameters
| deg | (float) angle in degree. |
| shape | (object) Optional. a shape object. |
| x | (int) Optional. x-coordinate. |
| y | (int) Optional. y-coordinate. |
Returns
N/A
scaleShape
scaleShape( rw, rh, point, shape )
Scales the currently selected shape using the given ratio (rw, rh) for width and height and point as the scaling center. If shape is given, scaling is applied to the input shape.
Parameters
| rw | (float) scaling factor in width. |
| rh | (float) scaling factor in height. |
| point | (object) the scaling center in {‘px’: x, ‘py’: y} format. |
| shape | (object) Optional. a shape object. |
Returns
N/A
scaleShapeCt
scaleShapeCt( rw, rh, shape )
Scales the currently selected shape using the given ratio (rw, rh) for width and height and the shape’s center point as the scaling center. If shape is given, scaling is applied to the input shape.
Parameters
| rw | (float) scaling factor in width. |
| rh | (float) scaling factor in height. |
| shape | (object) Optional. a shape object. |
Returns
N/A
cloneShape
cloneShape( shape, copyName )
Clone the given shape. If copyName is true, the new shape takes on the same Name as shape. Otherwise, a name is automatically assigned to the new shape. This call can be used to clone groups as well.
Parameters
| shape | (object) a shape object. |
| copyName | (bool) Optional. |
Returns
(object) a shape object.
selectControlPoint
selectControlPoint( x, y )
Select a Bezier control point at the given location. The Bezier shape that the point belongs to is also selected.
Parameters
| x | (int) x-coordinate. |
| y | (int) y-coordinate. |
Returns
(int) the index of a selected control point on the currently selected bezier shape, otherwise -1.
addBezierPoint
addBezierPoint( cp1x, cp1y, cp2x, cp2y, x, y )
Add a bezier point to the end of the currently selected shape’s point array. Each bezier point is made of two control points, (cp1x, cp1y) and (cp2x, cp2y), and a point on the curve, (x, y).
Parameters
| cp1x | (int) x-coordinate of first control point. |
| cp1y | (int) y-coordinate of first control point. |
| cp2x | (int) x-coordinate of second control point. |
| cp2y | (int) y-coordinate of second control point. |
| x | (int) x-coordinate. |
| y | (int) y-coordinate. |
Returns
N/A
moveControlPointTo
moveControlPointTo( index, option, x, y )
Move either the first(option=1) or second(option=2) control point at the given index from the currently selected shape to (x, y).
Parameters
| index | (int) index into a shape’s internal point array. (e.g. shape.pts.) |
| option | (int) specifies which control point. |
| x | (int) x-coordinate. |
| y | (int) y-coordinate. |
Returns
N/A
moveControlPointBy
moveControlPointBy( index, option, x, y )
Move either the first(option=1) or second(option=2) control point at the given index from the currently selected shape by (x, y).
Parameters
| index | (int) index into a shape’s internal point array. (e.g. shape.pts.) |
| option | (int) specifies which control point. |
| x | (int) x-coordinate. |
| y | (int) y-coordinate. |
Returns
N/A
fitText
fitText( shape, padding )
Fits shape to its fill text pattern with an optional padding. The shape parameter can be a shape name or shape object. If shape is omitted, the currently selected shape is used.
Parameters
| shape | (mixed) Optional. a shape name or a shape object. |
| padding | (int) padding in pixels. |
Returns
N/A
easing
easing( shape, track, type, opt )
Specify easing function for a subset of animation tracks.
Parameters
| shape | (string) name of a shape or * for wildcard. |
| track | (string) track name. |
| type | (object) type of easing function (e.g. EASING.Bounce.InOut.) |
| opt | (number) 0 for each keyframe, 1 for the first and last keys only. |
Returns
N/A
start
start( shape, track, repeat, mirror, repeatCount )
Starts a subset of animation tracks.
Parameters
| shape | (string) name of a shape or * for wildcard. |
| track | (string) track name. |
| repeat | (bool) repeat the animation. |
| mirror | (bool) alternate between forward and reversed animations. |
| repeatCount | (number) repeat count. |
Returns
N/A