Shorthand for canvas context operations.
npm install shortvasA wrapper around a 2D canvas context providing some shorter method names,
altered interfaces, and chaining in an attempt to make it easier to do common
canvas tasks with less typing. Compatibility with the original canvas
properties and methods is preserved to make introducing the module easier.
The only real extra feature provided over a standard context is an
implementation of getTransform.
With npm installed, run
```
npm install shortvas
In the examples below, two canvases canvas1 and canvas2 are made. canvas1canvas2
is operated on using the standard context interface and is operated on
with an equivalent sequence of Shortvas calls.
If run in a browser:
` js
var Shortvas = require("shortvas");
var canvas1 = document.createElement("canvas");
var longhand = canvas1.getContext("2d");
var canvas2 = document.createElement("canvas");
var shorthand = Shortvas.get(canvas2); // A context can also be passed in.
// Draw a red diagonal line.
longhand.strokeStyle = "#FF0000";
longhand.beginPath();
longhand.moveTo(5, 5);
longhand.lineTo(10, 10);
longhand.stroke();
shorthand.bp().M(5, 5).l(5, 5).stroke(0xFF0000);
// Draw a blue diamond with a green border using a 0 to 1 coordinate system.
longhand.save();
longhand.translate(40, 20);
longhand.scale(40, 40);
longhand.strokeStyle = "#00FF00";
longhand.lineWidth = 0.1;
longhand.fillStyle = "#0000FF";
longhand.beginPath();
longhand.moveTo(0.5, 0);
longhand.lineTo(0, 0.5);
longhand.lineTo(0.5, 1);
longhand.lineTo(1, 0.5);
longhand.closePath();
longhand.fill();
longhand.stroke();
longhand.restore();
shorthand.sv()
.toRect([40, 20, 40, 40]).bp()
.M(0.5, 0).L(0, 0.5).L(0.5, 1).L(1, 0.5).Z()
.fill(0x0000FF).stroke(0x00FF00, 0.1)
.rs();
`
` js`
var Shortvas = require("shortvas");
Returns a ShortvasContext instance, a wrapper around either the given context
or around the 2D context of the given canvas element.
Available options are noCache, which if true will skip the cachedShortvasContext attached to the canvas and make a new one. See
ShortvasContext for details.
If the provided color is a string, return it. If it is a hexadecimal number
in 0xRRGGBB format, return an HTML string representing that color. Behavior
for other types is undefined.
` js`
var color = Shortvas.color(0x001AB2); // "#001ab2"
All colors that can be passed into the various Shortvas methods pass through
this function, so you probably don't need to use it directly.
Extends the prototype of ShortvasContext with all methods on the provided
object which are own and enumerable. Nonfunction values will be ignored.
` js`
var Shortvas = require("shortvas");
var canvas = document.createElement("canvas");
var shortCtx = Shortvas.get(canvas); // ShortvasContext instance
A ShortvasContext is returned from the module's top level get method and is
a wrapper around a 2D canvas context. This wrapper supports all of the
properties and methods that a typical context implementation would so that it
can be easily dropped in to existing code.
A ShortvasContext instance stores itself under the custom property__shortvas__ in the canvas element, which will be retrieved if a secondgetTransform
Shortvas is made with the same canvas or its 2D context. Besides making it a
lot harder to break , it's also more consistent with how agetContext
canvas's works.
All ShortvasContext methods that would ordinarily not return anything insteadShortvasContext
return the called so that chaining is possible. This includes
both inherited context methods and the new methods documented below.
ShortvasContext aliases many vertex methods with names consistent with theS
notation for the SVG d attribute.
However, note that compatibility is not 100%. , T, and A are notC
implemented, cannot accept more than six arguments, and the behavior of
the relative vertex methods may not be totally consistent.
As mentioned above, ShortvasContext implements all of the usual properties
and methods of a 2D canvas context. Properties are implemented via ES5 getters
and setters, so setting a Shortvas property will set it on the backing canvas
context.
These are the standard canvas properties and methods supported by a
returned Shortvas instance, conditioned on the environment supporting all of
them. The list is based off information from
the living standard,
MDN,
and what was implemented in Chrome 46.0.2490.80.
- Properties: canvas, globalAlpha, globalCompositeOperation, strokeStyle, fillStyle, shadowOffsetX, shadowOffsetY, shadowBlur, shadowColor, lineWidth, lineCap, lineJoin, miterLimit, lineDashOffset, font, textAlign, textBaselinesave
- Methods: , restore, scale, rotate, translate, transform, setTransform, resetTransform, createLinearGradient, createRadialGradient, createPattern, clearRect, fillRect, strokeRect, beginPath, fill, stroke, drawFocusIfNeeded, clip, isPointInPath, isPointInStroke, fillText, strokeText, measureText, drawImage, createImageData, getImageData, putImageData, getContextAttributes, setLineDash, getLineDash, closePath, moveTo, lineTo, quadraticCurveTo, bezierCurveTo, arcTo, rect, arc
resetTransform will be implemented via setTransform if it is not native.
In addition to several documented below, the following aliases of existing
canvas properties and methods exist on ShortvasContext:save
- : push, svrestore
- : pop, rstransform
- : addTsetTransform
- : setTresetTransform
- : resetT
The underlying canvas context, which may be useful if you need to use features
not implemented/proxied by Shortvas. Using it in place of the ShortvasContextgetTransform
should normally Just Work, but beware of doing transforms through the context
directly if you intend to use .
Equivalent to context.canvas.width on the underlying context, and can be
assigned to like other proxied properties.
Equivalent to context.canvas.height on the underlying context, and can be
assigned to like other proxied properties.
_Aliases: getT_
Returns an array [a, b, c, d, e, f] representing the current transformationContext#transform
matrix with the same format as the arguments one would pass to. The implied 3 by 3 transformation matrix is``
a c e
b d f
0 0 1
_Aliases: pivot_
A composite transformation equivalent to translate(x, y), rotate(angle),translate(-x, -y)
and , which has the effect of rotating everything by angle(x, y)
radians about the point .
A composite transformation that multiples the passed angle by pi / 180, then
passes it to rotate.
_Aliases: pivotDeg_
A composite transformation that multiples the passed angle by pi / 180, then
passes it and the other arguments to rotateAbout.
A composite transformation of translations and scaling. Pass in two rectangles
in [x, y, w, h] format. The rectangle corresponding to from in the oldto
coordinate system will become the rectangle corresponding to in the new
coordinate system.
For example, if you wanted your context to have the top left corner be (0, 0)
and the bottom right corner be (1, 1) and your instance is named shortCtx,
` js`
shortCtx.resetT().toRect(0, 0, shortCtx.width, shortCtx.height);
Sets the provided properties on the context. shortCtx.set(props) andObject.assign(shortCtx, props) are essentially equivalent.
Same as ShortvasContext#set except that save is called just before, meaningwith should be balanced with a call to restore.
This calls save, runs the function f, and then calls restore. If propssave
is provided, it will set those properties between and f, in a mannerShortvasContext#with
similar to .
Wipes the entire canvas by temporarily resetting the transform and filling
the rectangle spanning the whole canvas with the given color. color can beShortvas.color
any value accepted by .
Clears the entire canvas by temporarily resetting the transform and calling
clearRect on the whole canvas area. This turns the canvas transparent, unlikeblank.
_Aliases: bp_
Calls Context#beginPath and resets the internal position state used by the
relative vertex methods.
_Aliases: M_
Equivalent of Context#moveTo. This method, along with all vertex methods
below, supports passing in an array or array-like object in the arguments.
The rule is that Shortvas will flatten the passed arguments down one level
before forwarding to the underlying context while leaving nonarrays untouched.
Relative version of Context#moveTo, moving to x + dx, y + dy where x, y are
the coordinates of the last path vertex (default 0, 0).
Supports arrays (see moveTo).
_Aliases: L_
Equivalent of Context#lineTo.
Supports arrays (see moveTo).
Relative version of Context#lineTo, drawing a line to x + dx, y + dy wherex, y are the coordinates of the last path vertex (default 0, 0).
Supports arrays (see moveTo).
Same as ShortvasContext#lineTo, except that the y-coordinate is set to the
value it had for the last vertex, meaning this command draws a horizontal line.
Supports arrays (see moveTo).
Relative version of ShortvasContext#H, drawing a line to x + dx, y wherex, y are the coordinates of the last path vertex (default 0, 0).
Supports arrays (see moveTo).
Same as ShortvasContext#lineTo, except that the x-coordinate is set to the
value it had for the last vertex, meaning this command draws a vertical line.
Supports arrays (see moveTo).
Relative version of ShortvasContext#V, drawing a line to x, y + dy wherex, y are the coordinates of the last path vertex (default 0, 0).
Supports arrays (see moveTo).
_Aliases: Q_
Equivalent of Context#quadraticCurveTo.
Supports arrays (see moveTo).
Relative version of ShortvasContext#quadraticCurveto, drawing a quadratic curvex + dcpx, y + dcpy, x + dx, y + dy
to where x, y are the coordinates of the
last path vertex (default 0, 0).
Supports arrays (see moveTo).
_Aliases: C_
Equivalent of Context#bezierCurveTo.
Supports arrays (see moveTo).
Unlike SVG, Shortvas does not yet support more than six arguments.
Relative version of ShortvasContext#bezierCurveto, drawing a bezier curve tox + dcp1x, y + dcp1y, x + dcp2x, y + dcp2y, x + dx, y + dyx, y
where are the coordinates of the last path vertex (default 0, 0).
Supports arrays (see moveTo).
Equivalent of Context#rect.
Supports arrays (see moveTo).
Equivalent of Context#arc.
Supports arrays (see moveTo).
Note that SVG's A does not match this method. A is a planned but not
currently implemented method.
Equivalent of Context#arcTo.
Supports arrays (see moveTo).
Note that significant computation is needed to ensure this method plugs into
relative methods like l correctly, which may be a performance liability.
_Aliases: Z, z_
Equivalent of Context#closePath().
Supports arrays (see moveTo).
This will not adjust the current x, y position, instead expecting the next
method call (if any) to have absolute coordinates. This may change in the
future.
_Aliases: strokeAnd_
Finishes the current path by setting strokeStyle and lineWidth to the givenContext#stroke
values, then calling . Missing arguments (null or undefined)
mean those context properties are left untouched.
_Aliases: fillAnd_
Finishes the current path by setting fillStyle to the given value, thenContext#fill
calling with the provided fillRule. Missing arguments (nullundefined
or ) mean those context properties are left untouched, or in thefillRule
case of the default "nonzero" will be used.
_Aliases: clipAnd_
Finishes the current path by calling Context#clip with the providedfillRule, which defaults to "nonzero".
Shortvas does not yet have a 1.0 release. Here are some things that will likely
be implemented by that time:
- Finish implementing missing SVG path vertex types.
- Font utilities, including string-to-object and object-to-string facilities.
- Gradient and pattern utilities.
With npm installed, run
``
npm test
To lint with ESLint, run
```
npm run check
MIT