Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/patrimart/ngvas
An Angular2/Angular4 library for HTML Canvas.
https://github.com/patrimart/ngvas
angular angular2 angular4 canvas ngvas
Last synced: about 2 months ago
JSON representation
An Angular2/Angular4 library for HTML Canvas.
- Host: GitHub
- URL: https://github.com/patrimart/ngvas
- Owner: patrimart
- Created: 2017-03-14T07:13:19.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-11-29T09:56:04.000Z (about 6 years ago)
- Last Synced: 2024-10-31T10:43:29.468Z (about 2 months ago)
- Topics: angular, angular2, angular4, canvas, ngvas
- Language: TypeScript
- Homepage:
- Size: 238 KB
- Stars: 28
- Watchers: 5
- Forks: 11
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ngvas
## An Angular2 / Angular4 Module for HTML Canvas
The **ngvas** library allows you to control the `` 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](https://plnkr.co/edit/Kc57baYFUnSY8MfDznZs?p=preview).
---
Example Angular Module:
```js
import { NgvasModule, tweens, hitAreas } from "ngvas";
@NgModule({
imports: [ BrowserModule, NgvasModule ],
declarations: [ AppComponent ],
bootstrap: [ AppComponent ]
})
class AppModule { }
```
Example HTML with Ngvas components:
```html
```
---
### Components
- ``: NgvasComponent - The parent component. Think of it as the `` tag.
- ``: NgvasArcComponent - [CanvasRenderingContext2D.arc()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/arc)
- ``: NgvasBezierCurveComponent - [CanvasRenderingContext2D.bezierCurveTo()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/bezierCurveTo)
- ``: NgvasCircleComponent - [CanvasRenderingContext2D.arc()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/arc)
- ``: NgvasImageComponent - [CanvasRenderingContext2D.drawImage()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage)
- ``: NgvasLineComponent - [CanvasRenderingContext2D.lineTo()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineTo)
- ``: NgvasPolygonComponent
- ``: NgvasQuadraticCurveComponent - [CanvasRenderingContext2D.quadraticCurveTo()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/quadraticCurveTo)
- ``: NgvasRectangleComponent - [CanvasRenderingContext2D.fillRect()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillRect)
- ``: NgvasTextComponent - [CanvasRenderingContext2D.fillText()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillText)
#### ``: 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 `` element. |
| height | `number` | Sets the height of the `` element. |
#### ``: NgvasComponent Event Bindings
| @Output("name") | Data Type | Description |
| ---------------- | ----------------- | ----------------------------------------------- |
| ready | `NgvasComponent` | Fires once when the component is initialized. |
---
#### ``: NgvasBaseComponent Input Bindings
These input bindings are available on all `` 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` | Scale multiplier. |
| size | `TweenInput` | Sets the width and height of the shape. |
| skew | `TweenInput` | Sets the X and Y skew of the shape. |
| rotate | `TweenInput` | Rotates the shape by the specified degrees. |
| translate | `TweenInput` | 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](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation) |
| fill | `TweenInput` | Sets the fill color, gradient or pattern of the shape. [CanvasRenderingContext2D.fillStyle](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fillStyle) |
| stroke | `TweenInput` | Sets the stroke settings of the shape. |
| shadow | `TweenInput` | Sets the shadow settings of the shape. |
#### ``: NgvasBaseComponent Event Bindings
These event bindings are available on all `` 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. |
---
#### ``: NgvasArcComponent Input Bindings
Draws a portion of a circle. `connectToCenter` to make a pie-chart shape.
| @Input("name") | Data Type | Description |
| --------------- | ------------------------------- | ------------------------------------------------------------------ |
| angle | `TweenInput` | The ending angle of the arc in degrees. |
| radius | `TweenInput` | The radius of the arc. |
| connectToCenter | `boolean` | If `true`, connects the arc to the center point like a pie slice. |
Example:
```html
```
---
#### ``: NgvasBezierCurveComponent Input Bindings
Draws one or more connected bezier curves.
| @Input("name") | Data Type | Description |
| --------------- | --------------- | ------------------------------------ |
| curves | `BezierCurve[]` | An array of connected bezier curves. |
```html
```
---
#### ``: NgvasCircleComponent Input Bindings
Draws a circle. Basically, an arc with a 360 degree angle.
| @Input("name") | Data Type | Description |
| --------------- | ---------------------------------- | -------------------------- |
| radius | `TweenInput` | The radius of the circle. |
```html
```
---
#### ``: NgvasImageComponent Input Bindings
Draws an image from the
| @Input("name") | Data Type | Description |
| --------------- | ---------- | --------------------------- |
| src | `string` | The URL path to the image. |
```html
```
Note: As a temporary fix, `` must set `fill` to make it visible.
---
#### ``: NgvasLineComponent Input Bindings
Draws one or more connected lines.
| @Input("name") | Data Type | Description |
| --------------- | ----------- | ----------------------------- |
| lines | `Line[]` | An array of connected lines. |
```html
```
---
#### ``: NgvasPolygonComponent Input Bindings
Draws a shape with any combination of lines, bezier curves and quadratic curves.
| @Input("name") | Data Type | Description |
| --------------- | --------------------------------------------- | ------------------------------------------- |
| sides | `Array` | An array of a variety of lines and curves. |
```html
```
---
#### ``: NgvasQuadraticCurveComponent Input Bindings
Draws one or more connected quadratic curves.
| @Input("name") | Data Type | Description |
| --------------- | ------------------- | ---------------------------------------- |
| curves | `QuadraticCurve[]` | An array of connected quadratic curves. |
```html
```
---
#### ``: 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. |
```html
```
---
### 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.
```js
import { tweens } from "ngvas";
type TweenFunc = (time: number, startValue: number, changeValue: number, duration: number) => number;
type TweenInput = 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:
```html
```
#### 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.
```js
import { hitAreas } from "ngvas";
import PixelHitArea = hitAreas.PixelHitArea;
```
---
### Types
Import interfaces:
```js
import * as types from "ngvas";
```
```js
// 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 = 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.