ngvas
    TypeScript icon, indicating that this package has built-in type declarations

    0.7.6 • Public • Published

    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 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.

    Install

    npm i ngvas

    DownloadsWeekly Downloads

    17

    Version

    0.7.6

    License

    MIT

    Last publish

    Collaborators

    • patrimart