ngvas

An Angular2 / Angular4 Module for HTML Canvas

The ngvas library allows you to control the <canvas> element from within Angular 2. Or is it 4 now?

Look in the /demo directory for a working example.

Experiment with ngvas in a Plunker.

---

Example Angular Module:

import { NgvasModule, tweens, hitAreas } from "ngvas";
 
@NgModule({
  imports:      [ BrowserModule, NgvasModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})
class AppModule { }

Example HTML with Ngvas components:

<ngvas [width]="500" [height]="500" (ready)="onNgvasInit()">
    <template ngFor let-rect [ngForOf]="rects">
        <ngvas-rectangle [fill]="rect.color" [translate]="rect.xy" [width]="rect.w" [height]="rect.h" origin="center"></ngvas-rectangle>
    </template>
    <ngvas-circle [fill]="'#0000ff'" [x]="100" [y]="100" [radius]="50" origin="center" (click)="onClickHandler($event)" [hitArea]="PixelHitArea"></ngvas-circle>
</ngvas>

---

Components

• <ngvas>: NgvasComponent - The parent component. Think of it as the <canvas> tag.
• <ngvas-arc>: NgvasArcComponent - CanvasRenderingContext2D.arc()
• <ngvas-bezier>: NgvasBezierCurveComponent - CanvasRenderingContext2D.bezierCurveTo()
• <ngvas-circle>: NgvasCircleComponent - CanvasRenderingContext2D.arc()
• <ngvas-image>: NgvasImageComponent - CanvasRenderingContext2D.drawImage()
• <ngvas-line>: NgvasLineComponent - CanvasRenderingContext2D.lineTo()
• <ngvas-polygon>: NgvasPolygonComponent
• <ngvas-quadratic>: NgvasQuadraticCurveComponent - CanvasRenderingContext2D.quadraticCurveTo()
• <ngvas-rectangle>: NgvasRectangleComponent - CanvasRenderingContext2D.fillRect()
• <ngvas-text>: NgvasTextComponent - CanvasRenderingContext2D.fillText()

<ngvas>: NgvasComponent Input Bindings

@Input("name")	Data Type	Description
active	boolean	Sets if animation in the canvas is active or not.
width	number	Sets the width of the <canvas> element.
height	number	Sets the height of the <canvas> element.

<ngvas>: NgvasComponent Event Bindings

@Output("name")	Data Type	Description
ready	NgvasComponent	Fires once when the component is initialized.

---

<ngvas-*>: NgvasBaseComponent Input Bindings

These input bindings are available on all <ngvas-*> components.

@Input("name")	Data Type	Description
name	string	The name of the component. Not used at this point.
active	boolean	Sets if the animation is active on the component.
visible	boolean	Sets if the component is visible on the canvas.
x	number	Sets the x coordinate of the shape.
y	number	Sets the y coordinate of the shape.
origin	[number, number] | "center"	Sets the x and y origin of the shape. "center" will lock the origin to the shape's center.
width	number	Sets the width of the shape. Not applicable for many shapes.
height	number	Sets the height of the shape. Not applicable for many shapes.
rotation	number	Sets the rotation of the shape in degrees.
scaleX	number	Sets the x scale of the shape.
scaleY	number	Sets the y scale of the shape in degrees.
skewX	number	Sets the x skew of the shape in degrees.
skewY	number	Sets the y skew of the shape.
scale	TweenInput<S, [number, number]>	Scale multiplier.
size	TweenInput<S, [number, number]>	Sets the width and height of the shape.
skew	TweenInput<S, [number, number]>	Sets the X and Y skew of the shape.
rotate	TweenInput<S, number>	Rotates the shape by the specified degrees.
translate	TweenInput<S, [number, number]>	Moves the shape the specified X and Y coordinates.
animate	((shape: S) => boolean) | undefined	This function is invoked on every frame request.
constrain	ConstraintFunction[] | undefined	This function is invoked on event frame request.
hitArea	typeof PixelHitArea	A function to calculate if the current mouse coordinates are within a shape.
opacity	number	Sets the overall opacity of the shape. It's proabably easier to use a fill or stroke ColorStyle with opacity.
compose	{ alpha?: number, overlay?: ComposeOverlay }	Sets how the shape is overlayed on the canvas. CanvasRenderingContext2D.globalCompositeOperation
fill	TweenInput<S, ColorStyle>	Sets the fill color, gradient or pattern of the shape. CanvasRenderingContext2D.fillStyle
stroke	TweenInput<S, { width:number, style:ColorStyle, join?:LineJoin, cap?:LineCap, dashOffset?:number, miterLimit?:number }>	Sets the stroke settings of the shape.
shadow	TweenInput<S, { blur:number, color:string, offsetX:number, offsetY:number }>	Sets the shadow settings of the shape.

<ngvas-*>: NgvasBaseComponent Event Bindings

These event bindings are available on all <ngvas-*> components. Note: a hit area is required for mouse events to work.

@Output("name")	Data Type	Description
click	MouseEvent	Emits a MouseEvent if the shape is clicked.
dblclick	MouseEvent	Emits a MouseEvent if the shape is double-clicked.
wheel	WheelEvent	Emits a WheelEvent if the scroll wheel is used over the shape.
mouseenter	MouseEvent	Emits a MouseEvent if the mouse pointer enters the shape.
mouseleave	MouseEvent	Emits a MouseEvent if the mouse pointer leaves the shape.
shape	BaseShape & BaseStyle	On init, emits the underlying class of the shape.

---

<ngvas-arc>: NgvasArcComponent Input Bindings

Draws a portion of a circle. connectToCenter to make a pie-chart shape.

@Input("name")	Data Type	Description
angle	TweenInput<ArcShape, number>	The ending angle of the arc in degrees.
radius	TweenInput<ArcShape, number>	The radius of the arc.
connectToCenter	boolean	If true, connects the arc to the center point like a pie slice.

Example:

<ngvas-arc fill="#ff0000" [x]="250" [y]="250" [radius]="50" [angle]="270" origin="center" [connectToCenter]="true"></ngvas-arc>

---

<ngvas-bezier>: NgvasBezierCurveComponent Input Bindings

Draws one or more connected bezier curves.

@Input("name")	Data Type	Description
curves	BezierCurve[]	An array of connected bezier curves.

<ngvas-bezier [stroke]="{ width: 4 }" [x]="50" [y]="50" [curves]="[[ [100, 100], [150, 450], [400, 300], [400, 400] ]]"></ngvas-bezier>

---

<ngvas-circle>: NgvasCircleComponent Input Bindings

Draws a circle. Basically, an arc with a 360 degree angle.

@Input("name")	Data Type	Description
radius	TweenInput<CircleShape, number>	The radius of the circle.

<ngvas-circle fill="#ff0000" [x]="250" [y]="250" [radius]="50" origin="center"></ngvas-circle>

---

<ngvas-image>: NgvasImageComponent Input Bindings

Draws an image from the

@Input("name")	Data Type	Description
src	string	The URL path to the image.

<ngvas-image fill="rgba(0,0,0,0)" [x]="10" [y]="10" [width]="100" [height]="100" src="../test/bird.jpg"></ngvas-image>

Note: As a temporary fix, <ngvas-image> must set fill to make it visible.

---

<ngvas-line>: NgvasLineComponent Input Bindings

Draws one or more connected lines.

@Input("name")	Data Type	Description
lines	Line[]	An array of connected lines.

<ngvas-line [stroke]="{ width: 4 }" [lines]="[ [[100, 100], [200, 200]], [[200, 200], [300, 100]] ]"></ngvas-line>

---

<ngvas-polygon>: NgvasPolygonComponent Input Bindings

Draws a shape with any combination of lines, bezier curves and quadratic curves.

@Input("name")	Data Type	Description
sides	Array<Line | BezierCurve | QuadraticCurve>	An array of a variety of lines and curves.

<ngvas-polygon fill="#ff0000" [x]="50" [y]="50" [sides]="sidesArray"></ngvas-polygon>

---

<ngvas-quadratic>: NgvasQuadraticCurveComponent Input Bindings

Draws one or more connected quadratic curves.

@Input("name")	Data Type	Description
curves	QuadraticCurve[]	An array of connected quadratic curves.

<ngvas-quadratic [stroke]="{ width: 4 }" [x]="50" [y]="50" [curves]="[[ [100, 100], [150, 450], [400, 400] ]]"></ngvas-quadratic>

---

<ngvas-text>: NgvasTextComponent Input Bindings

Draws text.

@Input("name")	Data Type	Description
text	string	The text to display.
textStyle	{ font?: string, align?: TextAlign, baseline?: TextBaseline }	The style of the displayed text.

<ngvas-text fill="#0000ff" [textStyle]="{ font: '48px Arial' }" [x]="50" [y]="250" text="This is text."></ngvas-text>

---

Tweening Inputs and Functions

You can set almost any value of a component to tween from its current value to a target value over a specified period of time with specific easing.

import { tweens } from "ngvas";
 
type TweenFunc = (time: number, startValue: number, changeValue: number, duration: number) => number;
 
type TweenInput <S, T> = T | [ T, number, TweenFunc | undefined, ((s: S) => void) | undefined ];
 
// Set the amount of pixels to move, the tween duration in MS, and the easing function to use.
const translateTween = [ [250, 250], 1000, tweens.easings.easeInOutSine ];

Example HTML:

<ngvas-circle fill="#ff0000" [x]="50" [y]="50" [radius]="50" [translate]="translateTween" origin="center"></ngvas-circle>

Built-in Tweens

• easeLinear
• easeInSine, easeOutSine, easeInOutSine
• easeInQuint, easeOutQuint, easeInOutQuint
• easeInQuart, easeOutQuart, easeInOutQuart
• easeInQuad, easeOutQuad, easeInOutQuad
• easeInExpo, easeOutExpo, easeInOutExpo
• easeInElastic, easeOutElastic, easeInOutElastic
• easeInCircular, easeOutCircular, easeInOutCircular
• easeInBack, easeOutBack, easeInOutBack
• easeInBounce, easeOutBounce, easeInOutBounce
• easeInCubic, easeOutCubic, easeInOutCubic

---

Hit Area Functions

One function to calculate if the mouse coordinates are on a shape is available. It is pixel accurate and non-optimized. Use it judiciously until more effecient hit area functions become available.

import { hitAreas } from "ngvas";
 
import PixelHitArea = hitAreas.PixelHitArea;

---

Types

Import interfaces:

import * as types from "ngvas";

// Point = [ x, y ]
type Point = [number, number];
 
// Line = [ startPoint, endPoint ]
type Line = [Point, Point];
 
// QuadraticCurve = [ startPoint, controlPoint, endPoint ]
type QuadraticCurve = [Point, Point, Point];
 
// BexierCurve = [ startPoint, controlPoint0, controlPoint1, endPoint ]
type BezierCurve = [Point, Point, Point, Point];
 
// Example: Point | [ Point, durationInMS, TweenFunc]
type TweenInput <S extends BaseStyle, T> = T | [ T, number, TweenFunc | undefined, ((s: S) => void) | undefined ]
 
type ComposeOverlay = "source-over" | "source-in" | "source-out" | "source-atop" |
            "destination-over" | "destination-in" | "destination-out" | "destination-atop" |
            "lighter" | "copy" | "xor" | "multiply" | "screen" | "overlay" | "darken" |
            "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" |
            "exclusion" | "hue" | "saturation" | "color" | "luminosity";
 
// ColorStyle: 0xff9966, "#ff9966", "#ff9966ff", "rgb(255,200,150)", "rgba(255,200,150,0.5)
type ColorStyle = number | string | CanvasGradient | CanvasPattern;
type LineJoin = "miter" | "bevel" | "round";
type LineCap = "butt" | "round" | "square";
type TextAlign = "left" | "right" | "center" | "start" | "end";
type TextBaseline = "top" | "hanging" | "middle" | "alphabetic" | "ideographic" | "bottom";

---

TODOs for 1.0

• Improve docs.
• Unit tests with >90% coverage.
• Improve originToCenter for curves and polygon.
• Built-in Constraints.
• Add mouse events: mousedown, mouseup
• Add other hit area types: vector rectangle, circle.
• Optimization.

TODOs for 1.x

• Add drag and drop events.
• Add HammerJS support.
• Grouping components.
• Optimization.