ve

vue-easeljs

A Vue.js plugin to control an HTML5 canvas using EaselJS

Showing:

Popularity

Downloads/wk

108

GitHub Stars

82

Maintenance

Last Commit

1yr ago

Contributors

2

Package

Dependencies

0

Size (min+gzip)

47.6KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

vue-easeljs

A Vue.js plugin to control an HTML5 canvas using EaselJS

Thanks

Thanks go to:

Getting Started

Install vue-easeljs

On the command line:

npm install vue-easeljs --save

In app.js:

Vue.use(require('vue-easeljs'));

In your Vue.js code start with an easel-canvas component. Other components reside within it.

The earliest components are hidden by later components whenever they overlap.

Example

See Live Demo

Components

easel-bitmap

Show a static image.

Attributes:

AttributeValuesDescriptionRequired/Default
alignalignmentcontrols what point of the image the x and y refer to.Default: 'top-left'
alpha0 to 1controls the opacity of the image.Default: 1, completely opaque
cachebooleaninstead of drawing from source constantly, use a cached version of the sourceDefault: false
cursorstringset the CSS mouse cursor to use when hovering over this bitmapDefault: null
filtersfiltersapply filters.Default: null
flip'horizontal' | 'vertical' | 'both' | ''flips the image.Default: ''
imagestringrelative or absolute URL to an image file.Required
rotationdegreesrotates the image.Default: 0
scalenumberresizes the image.Default: 1
shadowshadowcast an image-shaped shadow.Default: null
visiblebooleandraw or do not draw the bitmap on canvasDefault: true
xnumberhorizontal position based on the origin of the parent component.Default: 0
ynumbervertical position based on the origin of the parent component.Default: 0

Example:

<easel-bitmap
    image="/images/awesome-background.jpg"
    :x="0"
    :y="0"
    :align="['left','top']"
>
</easel-bitmap>

See Live Demo

easel-canvas

Give the vue-easeljs components a place to live. The canvas has no visible pixels of its own.

Attributes:

AttributeValuesDescriptionRequired/Default
anti-aliasbooleanwhether or not edges should be smoothed on scaled images.Default: true
heightnumberthe pixel height of the canvas on the page.Default: 300
widthnumberthe pixel width of the canvas on the page.Default: 150
viewport-heightnumberthe pixel height of the canvas internally.Default: equal to height
viewport-widthnumberthe pixel width of the canvas internally.Default: equal to width

The width and height props control the size of the canvas element on the page.

The separate viewport-width and viewport-height props control the size of the canvas internally. For example, a canvas with width and height of 100 can fully show an element of width and height 50. But the same canvas with viewport-width and viewport-height set to 40 cannot fully show the same element.

The viewport-width and viewport-height props are a convenience feature, allowing a developer to specify subcomponents' pixel sizes at a set size regardless of the actual size of the canvas. Setting small viewport sizes will make elements inside appear larger and pixelated, but if those elements are then scaled down they will not be pixelated. They will regain their original size and pixelation.

Example:

<easel-canvas width="500" height="100">
    <easel-shape
        form="rect"
        :dimensions="[500,100]"
        :x="0"
        :y="0"
        fill="#CCCCFF"
    >
    </easel-shape>
    <easel-text
        text="This is so easy!"
        :x="250"
        :y="75"
        font="70px Calibri"
        color="white"
        :shadow="['#000088',3,2,3]"
        :align="['center', 'alphabetical']"
    >
    </easel-text>
</easel-canvas>

See Live Demo

easel-container

Group other vue-easel components together and manipulate them as one. The container has no visible pixels of its own.

Attributes:

AttributeValuesDescriptionRequired/Default
alpha0 to 1controls the opacity of the container's contents.Default: 1, completely opaque
cachebooleaninstead of drawing contained element from source constantly, use a cached version of all elements togetherDefault: false
cursorstringset the CSS mouse cursor to use when hovering over the elements in this containerDefault: null
filtersfiltersapply filters.Default: null
flip'horizontal' | 'vertical' | 'both' | ''flips the container.Default: ''
rotationdegreesrotates the container.Default: 0
scalenumberresizes the container.Default: 1
shadowshadowcast a shadow of all contained components.Default: null
visiblebooleandraw or do not draw the container's elements on canvasDefault: true
xnumberhorizontal position based on the origin of the parent component.Default: 0
ynumbervertical position based on the origin of the parent component.Default: 0

Example:

<easel-container
    flip="horizontal"
    scale=".5"
    :x="250"
    :y="50"
>
    <easel-bitmap
        image="/images/wooden-sign-texture.png"
    >
    </easel-bitmap>
    <easel-text
        text="Dan's Left Shoe Emporium"
        font="50px 'Times New Roman'"
        :y="25"
    >
    </easel-text>
</easel-container>

See Live Demo

easel-shape

Show a shape.

Attributes:

AttributeValuesDescriptionRequired/Default
alignalignmentcontrols what point of the shape the x and y refer to.Default: 'top-left'
alpha0 to 1controls the opacity of the shape.Default: 1, completely opaque
cachebooleaninstead of drawing the shape constantly, use a cached version of the shapeDefault: false
cursorstringset the CSS mouse cursor to use when hovering over this shapeDefault: null
dimensionsDepends on the form.See below.Required
fillHTML colorthe inside of the shapeOptional.
filtersfiltersapply filters.Default: null
flip'horizontal' | 'vertical' | 'both' | ''flips the shape.Default: ''
form'circle' | 'ellipse' | 'rect' | 'star'Required
rotationdegreesrotates the shape.Default: 0
scalenumberresizes the shape.Default: 1
shadowshadowcast a same-shape shadow.Default: null
strokeHTML colorthe outline of the shape.Optional.
visiblebooleandraw or do not draw the shape on canvasDefault: true
xnumberhorizontal position based on the origin of the parent component.Default: 0
ynumbervertical position based on the origin of the parent component.Default: 0

Dimensions for:

ShapeDimension TypeFormatValue explanation
circlenumberthe radius of the circle.
ellipsearray[w, h]the width and height of the ellipse.
rectarray[w, h], or [w, h, r], or [w, h, topLeft, topRight, bottomRight, bottomLeft]the width and height of the rectangle. Optionally include the radius of rounded corners as one value or four.
stararray[r, s, p]the radius, sides count, and point size of a "star". Use point size 0 to draw a simple polygon. Max point size is 1.

Example:

<easel-shape
    form="star"
    :dimensions="[100, 3, 0]"
    fill="blue"
    stroke="red"
    :x="100"
    :y="100"
>

See Live Demo

easel-sprite

Show a moving image. An easel-sprite must reside in an easel-sprite-sheet node. The easel-sprite-sheet defines the animations that can be used by the easel-sprite.

Attributes:

AttributeValuesDescriptionRequired/Default
alignalignmentcontrols what point of the image the x and y refer to.Default: 'top-left'
alpha0 to 1controls the opacity of the image.Default: 1, completely opaque
animationstringname of the animation to run from the easel-sprite-sheet.Required
cachebooleaninstead of drawing from source constantly, use a cached version of the sourceDefault: false
cursorstringset the CSS mouse cursor to use when hovering over this spriteDefault: null
filtersfiltersapply filters.Default: null
flip'horizontal' | 'vertical' | 'both' | ''flips the image.Default: ''
rotationdegreesrotates the image.Default: 0
scalenumberresizes the image.Default: 1
shadowshadowcast an image-shaped shadow.Default: null
visiblebooleandraw or do not draw the sprite on canvasDefault: true
xnumberhorizontal position based on the origin of the parent component.Default: 0
ynumbervertical position based on the origin of the parent component.Default: 0

Example:

See the easel-sprite-sheet example below.

easel-sprite-sheet

Define image animations for use in a sprite.

Attributes:

AttributeValuesDescriptionRequired/Default
animationsobjectdefines names for animations. Each animation is a series of frames.Required
frameratenumberthe speed the animation should play at.Required
framesmixedusually an object with format: {width: width, height: height}.Required
imagesarrayrelative or absolute URL's to image files.Required

EaselJS provides a lot of options for defining sprite sheets, to allow you to format the images in whatever way suits you.

A sprite sheet is a single image with a set of images on it that will be used in rotation to show an animation.

The friendliest approach is to layout the images in a grid. For example, if a character requires 32x32 pixels to show, you might create a sprite sheet with 10 frames of the character in a 320x32 pixel image. Or a 32x320 image. Or a 160x64 image. Whatever the image size, EaselJS will figure it out based on the width and height you give it.

In that case the following definition will do nicely:

<easel-sprite-sheet
    :images="['/images/character.png']"
    :frames="{width: 32, height: 32}"
    ...
>

But sometimes frames have space between them or margins around them. In these cases, you'll need to specify more information.

In this example, there is space and margin between the frames.

<easel-sprite-sheet
    :images="['/images/lots-of-characters.png']"
    :frames="{width: 32, height: 32, spacing: 5, margin: 10}"
    ...
>

Other times, the frames are different sizes or are on different images.

In that case, this format will be required:

<easel-sprite-sheet
    :images="['/images/thomasChugging.png','/images/thomasBraking.png']"
    :frames="[
        // x, y, width, height, imageIndex
        [0, 0, 64, 32, 0],
        [0, 32, 64, 32, 0],
        ...
    ]"
    ...
>

Animations give names to a series of frames. The name is used in the easel-sprite component to determine what to show.

The value of an animation is a number, array, or object.

If the animation is just one frame, a number is appropriate.

If the animation is multiple frames laid out in order in the sprite sheet, then the array short form can be used. The first two values are the start and end of the animation. The third value is an optional next animation to begin when this one is done. The fourth is speed.

If the animation uses frames that are not in order, use an object with the field frames and the optional next and speed.

animations: {
    stand: 0,
    run: [1, 4, "stand"],
    fall: {
        frames: [5, 1, 0, 2],
    },
}

Example:

<easel-sprite-sheet
    :images="['images/lastguardian-all.png']"
    :frames="{width:32,height:32}"
    :animations="{
        stand: 7,
        walk: [6, 7],
        walkAndStand: [6, 7, 'stand'],
        confusion: {
            frames: [5, 1, 0, 2],
        },
    }"
    :framerate="4"
>
    <easel-sprite
        :x="32"
        :y="32"
        animation="walkAndStand"
    >
    </easel-sprite>
>
</easel-sprite-sheet>

See Live Demo

easel-text

Show some text.

Attributes:

AttributeValuesDescriptionRequired/Default
alignalignmentcontrols what point of the text the x and y refer to.Default: 'top-left'
alpha0 to 1controls the opacity of the text.Default: 1, completely opaque
cachebooleaninstead of drawing constantly, use a cached version of the textDefault: false
colorHTML colorthe color to use for the text.Default: 'black'
cursorstringset the CSS mouse cursor to use when hovering over this textDefault: null
filtersfiltersapply filters.Default: null
flip'horizontal' | 'vertical' | 'both' | ''flips the text.Default: ''
fontfontsize and family of the font. Format: "Npx family".Default: ?
rotationdegreesrotates the text.Default: 0
scalenumberresizes the text.Default: 1
shadowshadowcast a text-shaped shadow.Default: null
textstringthe text to display.Required
visiblebooleandraw or do not draw the text on canvasDefault: true
xnumberhorizontal position based on the origin of the parent component.Default: 0
ynumbervertical position based on the origin of the parent component.Default: 0

Example:

<easel-text
    text="The Ran In Span Falls Manly On The Plan"
    :x="250"
    :y="32"
    font="20px Arial"
    color="red"
>
</easel-text>

See Live Demo

Align attribute

All visible components can accept an align attribute. The align attribute defaults to 'top-left'.

The values refer to where the x, y coordinates should lie in reference to the rest of the object.

For example, if a 50x50 square shape is aligned at 'top-left', and its x and y are at 65, 70, then the square's top left point will be at 65, 70 and its bottom right point will be at 115, 120.

top left alignment

If the same square was aligned at 'bottom-right', then it's bottom right point would be at 65, 70 and its top left point would be at 15, 20.

bottom right alignment

The field can be either a string or an array.

As a string it is formatted as 'vertical-horizontal'.

As an array it is formatted as [vertical, horizontal].

Most components have these alignment options:

  • vertical: top, center, bottom
  • horizontal: left, center, right

The easel-text component has extra alignment options:

  • vertical: top, hanging, middle, alphabetic, ideographic, bottom
  • horizontal: start, end, left, right, center

These are described in the whatwg spec for HTML5 canvases. In cases of text with multiple lines, the horizontal alignment value applies to every line.

Note: For backwards compatibility, the horizontal and vertical parts of the string or array can be reversed. Future major versions will obsolete this option.

Cache attribute

The cache attribute is a boolean.

When caching is active, a rasterized version of the element is created in memory and used instead of the source material that the element uses. The element essentially becomes an EaselBitmap.

Many of an element's props will cause a cache refresh when they are changed.

The props alpha, flip, rotation, shadow, x, and y are applied to an element after caching and will not cause a cache refresh. However, if an element is part of a cached EaselContainer, changing those props on the child element will refresh the container's cache.

An animated sprite will refresh the rasterized image on each frame change.

And so a cached element should behave no differently from a non-cached element in most respects.

The difference is that caching has an impact on performance. In many cases it increases an element's speed, but if the cache needs to refresh often it can decrease speed.

Caching exists for those performance purposes and also because it will be necessary when filters are implemented in a future version of this library.

Filters attribute

Filters process a visual element's pixels, applying adjustments after the element is drawn.

The filters attribute is an array of arrays. Each filter array consists of the name of a filter followed by parameters.

Several filters can be applied to the same element.

Supplying filters forces cache to be true.

Available filters

This library comes pre-built with several filters.

BlurFilter

Blur an element. Applies to shadows as well.

['BlurFilter', x, y, quality]

ParameterRangeDefault
xhorizontal bluriness0 - Infinity0
yvertical bluriness0 - Infinity0
qualitythe number of blur iterations0 - Infinity1

ColorFilter

Systematically change the coloring of an element. Applies before shadowing is done. Use inside a container to include shadow.

['ColorFilter', rX, gX, bX, aX, rO, gO, bO]

ParameterRangeDefault
rXred multiplier0 to 11
gXgreen multiplier0 to 11
bXblue multiplier0 to 11
aXalpha multiplier0 to 11
rOred offset-255 to 2550
gOgreen offset-255 to 2550
bOblue offset-255 to 2550

ColorMatrixFilter

Adjust the brightness, contrast, saturation, and hue of an element.

['ColorMatrixFilter', brightness, contrast, saturation, hue]

ParameterRangeDefault
brightnessadd to the brightness-255 - 255undefined - no change
contrastadd to the contrast-100 - 100undefined - no change
saturationadd to the saturation-100 - 100undefined - no change
hueadd to the hue-180 - 180undefined - no change

PixelStrokeFilter

Add a pixelated stroke around the element.

['PixelStrokeFilter', [r, g, b, a]]

ParameterRangeDefault
colorcolor of stroke as array of red, green, blue, alphaarray, values 0 - 255[0, 0, 0, 255]

Not yet available

EaselJS has two filters -- AlphaMapFilter and AlphaMaskFilter -- that are not yet available, because their use requires complicated access to canvases. The idiom of this library is that you should never have to access a canvas. In the future this library should provide an <easel-mask> element to do masking, making those filters unnecessary.

Custom filters

Create new filters by registering a class with the VueEaseljs library at runtime using VueEaseljs.registerFilter.

See further documentation on Custom filters.

Example:

const VueEaseljs = require('vue-easeljs');

class MyFilter {

    constructor(value1, value2) {
        ...
    }

    adjustContext(ctx, x, y, width, height, targetCtx, targetX, targetY) {
        ...
    }
}

VueEaseljs.registerFilter('MyFilter', MyFilter);

Font attribute

The font attribute is a string that controls the family, size, and weight of text in an easel-text component.

The string is mostly compatible with the CSS font property with some changes.

In most cases it must include the font size and font family.

Example: "16px Garamond"

It can optionally include any of font style, font variant, font weight, and font stretch, in that order, before the font size.

Example: "italic small-caps bold 16px cursive"

Shadow attribute

All visible components can drop a shadow with an optional shadow attribute.

The field is formatted as [color, xOffset, yOffset, bluriness].

Shadow options:

  • color: HTML color
  • xOffset: number
  • yOffset: number
  • bluriness: number

Events

All visible components and the canvas itself emit Vue.js events with an event object.

EventFired when...
addedFired when the component is added to its parent.
animationend (easel-sprite only)Fired when an animation completes.
change (easel-sprite only)Fired when an animation changes.
clickFired when the component is clicked or tapped.
dblclickFired when the component is double-clicked or tapped.
mousedownFired when the component is clicked down.
mouseoutFired when the mouse leaves a component's hit area.
mouseoverFired when the mouse enters a component's hit area.
pressmoveFired when the component is dragged.
pressupFired when the component is unclicked.
removedFired when the component is removed from its parent.
rolloutFired when the mouse leaves a component's hit area.
rolloverFired when the mouse enters a comopnent's hit area.
tickFired many times a second to keep the components in sync. Using this event can impact performance.

Modifiers such as .stop usually work with the events.

For performance reasons, the events are only emitted if a handler exists. They will not show up in the Vue.js devtools if no handler exists.

These events will be made available in a future release:

  • drawend
  • drawstart
  • mouseenter
  • mouseleave
  • stagemousedown
  • stagemousemove
  • stagemouseup
  • tickend
  • tickstart

Developer Tips

Chrome/Chromium Users:

  • When developing locally, Chrome limits canvas access to local image files. They can be viewed but click events will error out unless Chrome is opened with the --allow-file-access-from-files flag. But be careful, since this flag opens your system up to some danger if the scripts you run on your page are untrustworthy. This is a limitation of canvas that applies to all canvas libraries. Fortunately, Chrome has this workaround. Unfortunately, it can stop working and require a browser restart.

All users:

  • When accessing image files from other hosts, CORS must be setup on the foreign host or else click events will error out. This is a limitation of canvas that applies to all canvas libraries.

The EaselJS documents can be helpful. They are essential if you intend to fork this repo and make pull requests.

Pending

These will be implemented in future releases:

  • Percentages
  • Pre-load images
  • Masks
  • Mouse cursors
  • Hit areas
  • Filters

There are no plans to implement these features that EaselJS provides, but pull requests are accepted:

  • BitmapText
  • Buttons
  • Complex Vector Paths
  • MovieClip

Contribution

If you find a bug or want to contribute to the code or documentation, you can help by submitting an issue or a pull request.

License

MIT

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100