#

API Documentation for: NEXT
Show: Inherited Protected Private Deprecated

# SpriteSheet Class

Extends EventDispatcher
Defined in: `SpriteSheet:38`
Module: EaselJS

Encapsulates the properties and methods associated with a sprite sheet. A sprite sheet is a series of images (usually animation frames) combined into a larger image (or images). For example, an animation consisting of eight 100x100 images could be combined into a single 400x200 sprite sheet (4 frames across by 2 high).

The data passed to the SpriteSheet constructor defines three critical pieces of information:

1. The image or images to use.
2. The positions of individual image frames. This data can be represented in one of two ways: As a regular grid of sequential, equal-sized frames, or as individually defined, variable sized frames arranged in an irregular (non-sequential) fashion.
3. Likewise, animations can be represented in two ways: As a series of sequential frames, defined by a start and end frame [0,3], or as a list of frames [0,1,2,3].

#### SpriteSheet Format

     data = {
         // DEFINING FRAMERATE:
         // this specifies the framerate that will be set on the SpriteSheet. See framerate
         // for more information.
         framerate: 20,

         // DEFINING IMAGES:
         // list of images or image URIs to use. SpriteSheet can handle preloading.
         // the order dictates their index value for frame definition.
         images: [image1, "path/to/image2.png"],

         // DEFINING FRAMES:
            // the simple way to define frames, only requires frame size because frames are consecutive:
            // define frame width/height, and optionally the frame count and registration point x/y.
            // if count is omitted, it will be calculated automatically based on image dimensions.
            frames: {width:64, height:64, count:20, regX: 32, regY:64},

            // OR, the complex way that defines individual rects for frames.
            // The 5th value is the image index per the list defined in "images" (defaults to 0).
            frames: [
                // x, y, width, height, imageIndex, regX, regY
                [0,0,64,64,0,32,64],
                [64,0,96,64,0]
            ],

         // DEFINING ANIMATIONS:

            // simple animation definitions. Define a consecutive range of frames (begin to end inclusive).
            // optionally define a "next" animation to sequence to (or false to stop) and a playback "speed".
            animations: {
                // start, end, next, speed
                run: [0,8],
                jump: [9,12,"run",2]
            }

         // the complex approach which specifies every frame in the animation by index.
         animations: {
             run: {
                 frames: [1,2,3,3,2,1]
             },
             jump: {
                 frames: [1,4,5,6,1],
                 next: "run",
                 speed: 2
             },
             stand: { frames: [7] }
         }

            // the above two approaches can be combined, you can also use a single frame definition:
            animations: {
                run: [0,8,true,2],
                jump: {
                    frames: [8,9,10,9,8],
                    next: "run",
                    speed: 2
                },
                stand: 7
            }
     }

Note that the `speed` property was added in EaselJS 0.7.0. Earlier versions had a `frequency` property instead, which was the inverse of speed. For example, a value of "4" would be 1/4 normal speed in earlier versions, but us 4x normal speed in 0.7.0+.

#### Example

To define a simple sprite sheet, with a single image "sprites.jpg" arranged in a regular 50x50 grid with two animations, "run" looping from frame 0-4 inclusive, and "jump" playing from frame 5-8 and sequencing back to run:

     var data = {
         images: ["sprites.jpg"],
         frames: {width:50, height:50},
         animations: {run:[0,4], jump:[5,8,"run"]}
     };
     var spriteSheet = new createjs.SpriteSheet(data);
     var animation = new createjs.Sprite(spriteSheet, "run");

Warning: Images loaded cross-origin will throw cross-origin security errors when interacted with using a mouse, using methods such as `getObjectUnderPoint`, using filters, or caching. You can get around this by setting `crossOrigin` flags on your images before passing them to EaselJS, eg: `img.crossOrigin="Anonymous";`

## Constructor

### `SpriteSheet`

(

- `data`

)

Defined in `SpriteSheet:38`

#### Parameters:

- `data` Object

  An object describing the SpriteSheet data.

- Index
- Methods
- Properties
- Events

## Item Index

### Methods

- _calculateFrames
- _dispatchEvent
- _handleImageLoad
- addEventListener
- clone
- dispatchEvent
- getAnimation
- getAnimations
- getFrame
- getFrameBounds
- getNumFrames
- hasEventListener
- initialize
- off
- on
- removeAllEventListeners
- removeEventListener
- toString
- willTrigger

### Properties

- _animations
- _captureListeners
- _data
- _frameHeight
- _frames
- _frameWidth
- _images
- _listeners
- _loadCount
- _numFrames
- _regX
- _regY
- complete
- framerate
- onComplete deprecated

### Events

- complete

## Methods

### `_calculateFrames`

() protected

Defined in `_calculateFrames:455`

### `_dispatchEvent`

(

- `eventObj`
- `eventPhase`

)
protected

Inherited from EventDispatcher: `_dispatchEvent:369`

#### Parameters:

- `eventObj` Object | String | Event
- `eventPhase` Object

### `_handleImageLoad`

() protected

Defined in `_handleImageLoad:443`

### `addEventListener`

(

- `type`
- `listener`
- `[useCapture]`

)
Function | Object

Inherited from EventDispatcher: `addEventListener:142`

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

#### Example

     displayObject.addEventListener("click", handleClick);
     function handleClick(event) {
        // Click happened.
     }

#### Parameters:

- `type` String

  The string type of the event.

- `listener` Function | Object

  An object with a handleEvent method, or a function that will be called when the event is dispatched.

- `[useCapture]` Boolean optional

  For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

#### Returns:

Function | Object:

Returns the listener for chaining or assignment.

### `clone`

() SpriteSheet

Defined in `clone:422`

Returns a clone of the SpriteSheet instance.

#### Returns:

SpriteSheet:

a clone of the SpriteSheet instance.

### `dispatchEvent`

(

- `eventObj`
- `[target]`

)
Boolean

Inherited from EventDispatcher: `dispatchEvent:280`

Dispatches the specified event to all listeners.

#### Example

     // Use a string event
     this.dispatchEvent("complete");

     // Use an Event instance
     var event = new createjs.Event("progress");
     this.dispatchEvent(event);

#### Parameters:

- `eventObj` Object | String | Event

  An object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance with the specified type.

- `[target]` Object optional

  The object to use as the target property of the event object. This will default to the dispatching object. This parameter is deprecated and will be removed.

#### Returns:

Boolean:

Returns the value of eventObj.defaultPrevented.

### `getAnimation`

(

- `name`

)
Object

Defined in `getAnimation:364`

Returns an object defining the specified animation. The returned object contains:

- frames: an array of the frame ids in the animation
- speed: the playback speed for this animation
- name: the name of the animation
- next: the default animation to play next. If the animation loops, the name and next property will be the same.

#### Parameters:

- `name` String

  The name of the animation to get.

#### Returns:

Object:

a generic object with frames, speed, name, and next properties.

### `getAnimations`

() Array

Defined in `getAnimations:355`

Returns an array of all available animation names as strings.

#### Returns:

Array:

an array of animation names available on this sprite sheet.

### `getFrame`

(

- `frameIndex`

)
Object

Defined in `getFrame:380`

Returns an object specifying the image and source rect of the specified frame. The returned object has:

- an image property holding a reference to the image object in which the frame is found
- a rect property containing a Rectangle instance which defines the boundaries for the frame within that image.
- A regX and regY property corresponding to the regX/Y values for the frame.

#### Parameters:

- `frameIndex` Number

  The index of the frame.

#### Returns:

Object:

a generic object with image and rect properties. Returns null if the frame does not exist.

### `getFrameBounds`

(

- `frameIndex`
- `[rectangle]`

)
Rectangle

Defined in `getFrameBounds:397`

Returns a Rectangle instance defining the bounds of the specified frame relative to the origin. For example, a 90 x 70 frame with a regX of 50 and a regY of 40 would return:

     [x=-50, y=-40, width=90, height=70]

#### Parameters:

- `frameIndex` Number

  The index of the frame.

- `[rectangle]` Rectangle optional

  A Rectangle instance to copy the values into. By default a new instance is created.

#### Returns:

Rectangle:

A Rectangle instance. Returns null if the frame does not exist, or the image is not fully loaded.

### `getNumFrames`

(

- `animation`

)
Number

Defined in `getNumFrames:338`

Returns the total number of frames in the specified animation, or in the whole sprite sheet if the animation param is omitted.

#### Parameters:

- `animation` String

  The name of the animation to get a frame count for.

#### Returns:

Number:

The number of frames in the animation, or in the entire sprite sheet if the animation param is omitted.

### `hasEventListener`

(

- `type`

)
Boolean

Inherited from EventDispatcher: `hasEventListener:329`

Indicates whether there is at least one listener for the specified event type.

#### Parameters:

- `type` String

  The string type of the event.

#### Returns:

Boolean:

Returns true if there is at least one listener for the specified event.

### `initialize`

(

- `data`

)
protected

Inherited from EventDispatcher but overwritten in `initialize:252`

#### Parameters:

- `data` Object

  An object describing the SpriteSheet data.

### `off`

(

- `type`
- `listener`
- `[useCapture]`

)

Inherited from EventDispatcher: `off:247`

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

#### Parameters:

- `type` String

  The string type of the event.

- `listener` Function | Object

  The listener function or object.

- `[useCapture]` Boolean optional

  For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

### `on`

(

- `type`
- `listener`
- `[scope]`
- `[once=false]`
- `[data]`
- `[useCapture=false]`

)
Function

Inherited from EventDispatcher: `on:175`

A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener.

This method works by creating an anonymous wrapper function and subscribing it with addEventListener. The created anonymous function is returned for use with .removeEventListener (or .off).

#### Example

        var listener = myBtn.on("click", handleClick, null, false, {count:3});
        function handleClick(evt, data) {
            data.count -= 1;
            console.log(this == myBtn); // true - scope defaults to the dispatcher
            if (data.count == 0) {
                alert("clicked 3 times!");
                myBtn.off("click", listener);
                // alternately: evt.remove();
            }
        }

#### Parameters:

- `type` String

  The string type of the event.

- `listener` Function | Object

  An object with a handleEvent method, or a function that will be called when the event is dispatched.

- `[scope]` Object optional

  The scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).

- `[once=false]` Boolean optional

  If true, the listener will remove itself after the first time it is triggered.

- `[data]` optional

  Arbitrary data that will be included as the second parameter when the listener is called.

- `[useCapture=false]` Boolean optional

  For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

#### Returns:

Function:

Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

### `removeAllEventListeners`

(

- `[type]`

)

Inherited from EventDispatcher: `removeAllEventListeners:258`

Removes all listeners for the specified type, or all listeners of all types.

#### Example

     // Remove all listeners
     displayObject.removeAllEventListeners();

     // Remove all click listeners
     displayObject.removeAllEventListeners("click");

#### Parameters:

- `[type]` String optional

  The string type of the event. If omitted, all listeners for all types will be removed.

### `removeEventListener`

(

- `type`
- `listener`
- `[useCapture]`

)

Inherited from EventDispatcher: `removeEventListener:217`

Removes the specified event listener.

Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.

#### Example

     displayObject.removeEventListener("click", handleClick);

#### Parameters:

- `type` String

  The string type of the event.

- `listener` Function | Object

  The listener function or object.

- `[useCapture]` Boolean optional

  For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

### `toString`

() String

Inherited from EventDispatcher but overwritten in `toString:413`

Returns a string representation of this object.

#### Returns:

String:

a string representation of the instance.

### `willTrigger`

(

- `type`

)
Boolean

Inherited from EventDispatcher: `willTrigger:340`

Indicates whether there is at least one listener for the specified event type on this object or any of its ancestors (parent, parent's parent, etc). A return value of true indicates that if a bubbling event of the specified type is dispatched from this object, it will trigger at least one listener.

This is similar to hasEventListener, but it searches the entire event flow for a listener, not just this object.

#### Parameters:

- `type` String

  The string type of the event.

#### Returns:

Boolean:

Returns `true` if there is at least one listener for the specified event.

## Properties

### `_animations`

Unknown protected

Defined in `_animations:190`

### `_captureListeners`

Object protected

Inherited from EventDispatcher: `_captureListeners:126`

### `_data`

Unknown protected

Defined in `_data:208`

### `_frameHeight`

Unknown protected

Defined in `_frameHeight:221`

### `_frames`

Unknown protected

Defined in `_frames:196`

### `_frameWidth`

Unknown protected

Defined in `_frameWidth:227`

### `_images`

Unknown protected

Defined in `_images:202`

### `_listeners`

Object protected

Inherited from EventDispatcher: `_listeners:119`

### `_loadCount`

Unknown protected

Defined in `_loadCount:214`

### `_numFrames`

Unknown protected

Defined in `_numFrames:233`

### `_regX`

Unknown protected

Defined in `_regX:239`

### `_regY`

Unknown protected

Defined in `_regY:245`

### `complete`

Boolean

Defined in `complete:163`

Indicates whether all images are finished loading.

### `framerate`

Number

Defined in `framerate:172`

Specifies the framerate to use by default for Sprite instances using the SpriteSheet. See Sprite.framerate for more information.

### `onComplete`

Function deprecated

Defined in `onComplete:181`

Deprecated: Use addEventListener and the "complete" event.

REMOVED. Use addEventListener and the complete event.

## Events

### `complete`

Defined in `complete:147`

Available since 0.6.0

Dispatched when all images are loaded. Note that this only fires if the images were not fully loaded when the sprite sheet was initialized. You should check the complete property to prior to adding a listener. Ex.

    var sheet = new SpriteSheet(data);
    if (!sheet.complete) {
       // not preloaded, listen for the complete event:
       sheet.addEventListener("complete", handler);
    }

#### Event Payload:

- `target` Object

  The object that dispatched the event.

- `type` String

  The event type.