#

API Documentation for: 1.0.0
Show: Inherited Protected Private Deprecated

# SpriteSheetBuilder Class

Extends EventDispatcher
Defined in: `SpriteSheetBuilder:41`
Module: EaselJS

The SpriteSheetBuilder allows you to generate SpriteSheet instances at run time from any display object. This can allow you to maintain your assets as vector graphics (for low file size), and render them at run time as SpriteSheets for better performance.

SpriteSheets can be built either synchronously, or asynchronously, so that large SpriteSheets can be generated without locking the UI.

Note that the "images" used in the generated SpriteSheet are actually canvas elements, and that they will be sized to the nearest power of 2 up to the value of maxWidth or maxHeight.

## Constructor

### `SpriteSheetBuilder`

(

- `[framerate=0]`

)

Defined in `SpriteSheetBuilder:41`

#### Parameters:

- `[framerate=0]` Number optional

  The framerate of SpriteSheet instances that are created.

- Index
- Methods
- Properties
- Events

## Item Index

### Methods

- _dispatchEvent
- _drawNext
- _endBuild
- _fillRow
- _getSize
- _run
- _setupMovieClipFrame
- _startBuild
- addAnimation
- addEventListener
- addFrame
- addMovieClip
- build
- buildAsync
- clone
- dispatchEvent
- hasEventListener
- off
- on
- removeAllEventListeners
- removeEventListener
- stopAsync
- toString
- willTrigger

### Properties

- _animations
- _captureListeners
- _data
- _frames
- _index
- _listeners
- _nextFrameIndex
- _scale
- _timerID
- framerate
- maxHeight
- maxWidth
- padding
- progress
- scale
- spriteSheet
- timeSlice

### Events

- complete
- progress

## Methods

### `_dispatchEvent`

(

- `eventObj`
- `eventPhase`

)
protected

Inherited from EventDispatcher: `_dispatchEvent:380`

#### Parameters:

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

### `_drawNext`

() protected

Defined in `_drawNext:514`

#### Returns:

Boolean Returns false if this is the last draw.

### `_endBuild`

() protected

Defined in `_endBuild:478`

### `_fillRow`

(

- `frames`
- `y`
- `img`
- `dataFrames`
- `pad`

)
Number protected

Defined in `_fillRow:440`

#### Parameters:

- `frames` Array
- `y` Number
- `img` HTMLImageElement
- `dataFrames` Object
- `pad` Number

#### Returns:

Number:

The width & height of the row.

### `_getSize`

() Number protected

Defined in `_getSize:429`

#### Returns:

Number:

The width & height of the row.

### `_run`

() protected

Defined in `_run:489`

### `_setupMovieClipFrame`

() Number protected

Defined in `_setupMovieClipFrame:416`

#### Returns:

Number:

The width & height of the row.

### `_startBuild`

() protected

Defined in `_startBuild:375`

### `addAnimation`

(

- `name`
- `frames`
- `[next]`
- `[speed]`

)

Defined in `addAnimation:243`

Adds an animation that will be included in the created SpriteSheet.

#### Parameters:

- `name` String

  The name for the animation.

- `frames` Array

  An array of frame indexes that comprise the animation. Ex. [3,6,5] would describe an animation that played frame indexes 3, 6, and 5 in that order.

- `[next]` String optional

  Specifies the name of the animation to continue to after this animation ends. You can also pass false to have the animation stop when it ends. By default it will loop to the start of the same animation.

- `[speed]` Number optional

  Specifies a frame advance speed for this animation. For example, a value of 0.5 would cause the animation to advance every second tick. Note that earlier versions used `frequency` instead, which had the opposite effect.

### `addEventListener`

(

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

)
Function | Object

Inherited from EventDispatcher: `addEventListener:140`

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.

### `addFrame`

(

- `source`
- `[sourceRect]`
- `[scale=1]`
- `[setupFunction]`
- `[setupData]`

)
Number

Defined in `addFrame:215`

Adds a frame to the SpriteSheet. Note that the frame will not be drawn until you call build method. The optional setup params allow you to have a function run immediately before the draw occurs. For example, this allows you to add a single source multiple times, but manipulate it or its children to change it to generate different frames.

Note that the source's transformations (x, y, scale, rotate, alpha) will be ignored, except for regX/Y. To apply transforms to a source object and have them captured in the SpriteSheet, simply place it into a Container and pass in the Container as the source.

#### Parameters:

- `source` DisplayObject

  The source DisplayObject to draw as the frame.

- `[sourceRect]` Rectangle optional

  A Rectangle defining the portion of the source to draw to the frame. If not specified, it will look for a `getBounds` method, bounds property, or `nominalBounds` property on the source to use. If one is not found, the frame will be skipped.

- `[scale=1]` Number optional

  Optional. The scale to draw this frame at. Default is 1.

- `[setupFunction]` Function optional

  A function to call immediately before drawing this frame. It will be called with two parameters: the source, and setupData.

- `[setupData]` Object optional

  Arbitrary setup data to pass to setupFunction as the second parameter.

#### Returns:

Number:

The index of the frame that was just added, or null if a sourceRect could not be determined.

### `addMovieClip`

(

- `source`
- `[sourceRect]`
- `[scale=1]`
- `[setupFunction]`
- `[setupData]`
- `[labelFunction]`

)

Defined in `addMovieClip:260`

This will take a MovieClip instance, and add its frames and labels to this builder. Labels will be added as an animation running from the label index to the next label. For example, if there is a label named "foo" at frame 0 and a label named "bar" at frame 10, in a MovieClip with 15 frames, it will add an animation named "foo" that runs from frame index 0 to 9, and an animation named "bar" that runs from frame index 10 to 14.

Note that this will iterate through the full MovieClip with actionsEnabled set to `false`, ending on the last frame.

#### Parameters:

- `source` MovieClip

  The source MovieClip instance to add to the SpriteSheet.

- `[sourceRect]` Rectangle optional

  A Rectangle defining the portion of the source to draw to the frame. If not specified, it will look for a getBounds method, `frameBounds` Array, `bounds` property, or `nominalBounds` property on the source to use. If one is not found, the MovieClip will be skipped.

- `[scale=1]` Number optional

  The scale to draw the movie clip at.

- `[setupFunction]` Function optional

  A function to call immediately before drawing each frame. It will be called with three parameters: the source, setupData, and the frame index.

- `[setupData]` Object optional

  Arbitrary setup data to pass to setupFunction as the second parameter.

- `[labelFunction]` Function optional

  This method will be called for each MovieClip label that is added with four parameters: the label name, the source MovieClip instance, the starting frame index (in the movieclip timeline) and the end index. It must return a new name for the label/animation, or `false` to exclude the label.

### `build`

() SpriteSheet

Defined in `build:318`

Builds a SpriteSheet instance based on the current frames.

#### Returns:

SpriteSheet:

The created SpriteSheet instance, or null if a build is already running or an error occurred.

### `buildAsync`

(

- `[timeSlice]`

)

Defined in `buildAsync:332`

Asynchronously builds a SpriteSheet instance based on the current frames. It will run 20 times per second, using an amount of time defined by `timeSlice`. When it is complete it will call the specified callback.

#### Parameters:

- `[timeSlice]` Number optional

  Sets the timeSlice property on this instance.

### `clone`

()

Defined in `clone:356`

SpriteSheetBuilder instances cannot be cloned.

### `dispatchEvent`

(

- `eventObj`
- `[bubbles]`
- `[cancelable]`

)
Boolean

Inherited from EventDispatcher: `dispatchEvent:285`

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 if necessary with the specified type. This latter approach can be used to avoid event object instantiation for non-bubbling events that may not have any listeners.

- `[bubbles]` Boolean optional

  Specifies the `bubbles` value when a string was passed to eventObj.

- `[cancelable]` Boolean optional

  Specifies the `cancelable` value when a string was passed to eventObj.

#### Returns:

Boolean:

Returns false if `preventDefault()` was called on a cancelable event, true otherwise.

### `hasEventListener`

(

- `type`

)
Boolean

Inherited from EventDispatcher: `hasEventListener:339`

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.

### `off`

(

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

)

Inherited from EventDispatcher: `off:249`

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

IMPORTANT: To remove a listener added with `on`, you must pass in the returned wrapper function as the listener. See on for an example.

#### 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:173`

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 wrapper function is returned for use with `removeEventListener` (or `off`).

IMPORTANT: To remove a listener added with `on`, you must pass in the returned wrapper function as the listener, or use remove. Likewise, each time you call `on` a NEW wrapper function is subscribed, so multiple calls to `on` with the same params will create multiple listeners.

#### 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:263`

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:219`

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.

### `stopAsync`

()

Defined in `stopAsync:347`

Stops the current asynchronous build.

### `toString`

() String

Inherited from EventDispatcher but overwritten in `toString:364`

Returns a string representation of this object.

#### Returns:

String:

a string representation of the instance.

### `willTrigger`

(

- `type`

)
Boolean

Inherited from EventDispatcher: `willTrigger:350`

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`

Array protected

Defined in `_animations:147`

### `_captureListeners`

Object protected

Inherited from EventDispatcher: `_captureListeners:106`

### `_data`

Array protected

Defined in `_data:154`

### `_frames`

Array protected

Defined in `_frames:140`

### `_index`

Number protected

Defined in `_index:168`

### `_listeners`

Object protected

Inherited from EventDispatcher: `_listeners:99`

### `_nextFrameIndex`

Number protected

Defined in `_nextFrameIndex:161`

### `_scale`

Number protected

Defined in `_scale:182`

### `_timerID`

Number protected

Defined in `_timerID:175`

### `framerate`

Number

Defined in `framerate:128`

A framerate value that will be passed to new SpriteSheet instances that are created. If no framerate is specified (or it is 0), then SpriteSheets will use the Ticker framerate.

Default: 0

### `maxHeight`

Number

Defined in `maxHeight:72`

The maximum height for the images (not individual frames) in the generated SpriteSheet. It is recommended to use a power of 2 for this value (ex. 1024, 2048, 4096). If the frames cannot all fit within the max dimensions, then additional images will be created as needed.

Default: 2048

### `maxWidth`

Number

Defined in `maxWidth:62`

The maximum width for the images (not individual frames) in the generated SpriteSheet. It is recommended to use a power of 2 for this value (ex. 1024, 2048, 4096). If the frames cannot all fit within the max dimensions, then additional images will be created as needed.

Default: 2048

### `padding`

Number

Defined in `padding:99`

The padding to use between frames. This is helpful to preserve antialiasing on drawn vector content.

Default: 1

### `progress`

Number readonly

Defined in `progress:118`

A value between 0 and 1 that indicates the progress of a build, or -1 if a build has not been initiated.

Default: -1

### `scale`

Number

Defined in `scale:89`

The scale to apply when drawing all frames to the SpriteSheet. This is multiplied against any scale specified in the addFrame call. This can be used, for example, to generate a SpriteSheet at run time that is tailored to the a specific device resolution (ex. tablet vs mobile).

Default: 1

### `spriteSheet`

SpriteSheet

Defined in `spriteSheet:82`

The SpriteSheet that was generated. This will be null before a build is completed successfully.

### `timeSlice`

Number

Defined in `timeSlice:107`

A number from 0.01 to 0.99 that indicates what percentage of time the builder can use. This can be thought of as the number of seconds per second the builder will use. For example, with a timeSlice value of 0.3, the builder will run 20 times per second, using approximately 15ms per build (30% of available time, or 0.3s per second). Defaults to 0.3.

Default: 0.3

## Events

### `complete`

Defined in `complete:196`

Available since 0.6.0

Dispatched when a build completes.

#### Event Payload:

- `target` Object

  The object that dispatched the event.

- `type` String

  The event type.

### `progress`

Defined in `progress:204`

Available since 0.6.0

Dispatched when an asynchronous build has progress.

#### Event Payload:

- `target` Object

  The object that dispatched the event.

- `type` String

  The event type.

- `progress` Number

  The current progress value (0-1).