SpriteStage Class
A sprite stage is the root level Container for an aggressively optimized display list. Each time its tick method is called, it will render its display list to its target canvas. WebGL content is fully compatible with the existing Context2D renderer. On devices or browsers that don't support WebGL, content will automatically be rendered via canvas 2D.
Restrictions:
- only Sprite, SpriteContainer, BitmapText, Bitmap and DOMElement are allowed to be added to the display list.
- a child being added (with the exception of DOMElement) MUST have an image or spriteSheet defined on it.
- a child's image/spriteSheet MUST never change while being on the display list.Example
This example creates a sprite stage, adds a child to it, then uses Ticker to update the child and redraw the stage using update. var stage = new createjs.SpriteStage("canvasElementId", false, false);
stage.updateViewport(800, 600);
var image = new createjs.Bitmap("imagePath.png");
stage.addChild(image);
createjs.Ticker.addEventListener("tick", handleTick);
function handleTick(event) {
image.x += 10;
stage.update();
}Note: SpriteStage is not included in the minified version of EaselJS.
Constructor
SpriteStage
-
canvas -
preserveDrawingBuffer -
antialias
Parameters:
-
canvasHTMLCanvasElement | String | ObjectA canvas object that the SpriteStage will render to, or the string id of a canvas object in the current document.
-
preserveDrawingBufferBooleanIf true, the canvas is NOT auto-cleared by WebGL (spec discourages true). Useful if you want to use p.autoClear = false.
-
antialiasBooleanSpecifies whether or not the browser's WebGL implementation should try to perform antialiasing.
Item Index
Methods
- _applyFilterBounds
- _applyFilters
- _applyShadow
- _createBuffers
- _createShader
- _createShaderProgram
- _dispatchEvent
- _dispatchMouseEvent
- _drawToGPU
- _drawWebGLKids
- _getBounds
- _getElementRect
- _getObjectsUnderPoint
- _getPointerData
- _handleDoubleClick
- _handleMouseDown
- _handleMouseMove
- _handleMouseUp
- _handlePointerDown
- _handlePointerMove
- _handlePointerUp
- _initializeWebGL
- _initializeWebGLContext
- _isMouseOpaque
- _setClearColor
- _setMaxBoxesPoints
- _setUpKidTexture
- _setWebGLContext
- _testHit
- _testMouseOver
- _tick
- _transformBounds
- _updatePointerPosition
- addChild
- addChildAt
- addEventListener
- cache
- clear
- clearImageTexture
- clone
- cloneProps
- contains
- dispatchEvent
- draw
- enableDOMEvents
- enableMouseOver
- getBounds
- getCacheDataURL
- getChildAt
- getChildByName
- getChildIndex
- getConcatenatedMatrix
- getMatrix
- getNumChildren
- getObjectsUnderPoint
- getObjectUnderPoint
- getStage
- getTransformedBounds
- globalToLocal
- hasEventListener
- hitTest
- initialize
- isVisible
- localToGlobal
- localToLocal
- off
- on
- removeAllChildren
- removeAllEventListeners
- removeChild
- removeChildAt
- removeEventListener
- set
- setBounds
- setChildIndex
- setTransform
- sortChildren
- swapChildren
- swapChildrenAt
- tick
- toDataURL
- toString
- uncache
- update
- updateCache
- updateContext
- updateViewport
- willTrigger
Properties
- _antialias
- _bounds
- _cacheDataURL
- _cacheDataURLID
- _cacheOffsetX
- _cacheOffsetY
- _cacheScale
- _captureListeners
- _clearColor
- _currentBoxIndex
- _drawTexture
- _indices
- _indicesBuffer
- _listeners
- _matrix
- _maxBoxesPerDraw
- _maxBoxesPointsPerDraw
- _maxIndicesPerDraw
- _maxTexturesPerDraw
- _mouseOverIntervalID
- _nextStage
- _pointerCount
- _pointerData
- _preserveDrawingBuffer
- _prevStage
- _primaryPointerID
- _projectionMatrix
- _rectangle
- _shaderProgram
- _vertices
- _verticesBuffer
- _viewportHeight
- _viewportWidth
- _webGLContext
- _webGLErrorDetected
- alpha
- autoClear
- cacheCanvas
- cacheID
- canvas
- children
- compositeOperation
- cursor
- DisplayObject__tick
- DisplayObject_draw
- DisplayObject_getBounds
- DisplayObject_initialize
- drawRect
- filters
- handleEvent
- hitArea
- id
- INDICES_PER_BOX static
- isWebGL
- mask
- MAX_BOXES_POINTS_INCREMENT static
- MAX_INDEX_SIZE static
- mouseChildren
- mouseEnabled
- mouseInBounds
- mouseMoveOutside
- mouseX
- mouseY
- name
- nextStage
- NUM_VERTEX_PROPERTIES static
- NUM_VERTEX_PROPERTIES_PER_BOX static
- onClick deprecated
- onDoubleClick deprecated
- onMouseDown deprecated
- onMouseMove deprecated
- onMouseOut deprecated
- onMouseOver deprecated
- onMouseUp deprecated
- onPress deprecated
- onTick deprecated
- parent
- POINTS_PER_BOX static
- regX
- regY
- rotation
- scaleX
- scaleY
- shadow
- skewX
- skewY
- snapToPixel
- snapToPixelEnabled
- Stage_draw
- Stage_initialize
- tickChildren
- tickEnabled
- tickOnUpdate
- visible
- x
- y
Methods
_applyFilters
()
protected
_createBuffers
-
ctx
Sets up the necessary vertices and indices buffers.
Parameters:
-
ctxWebGLRenderingContext
_createShader
-
ctx -
type -
str
Creates a shader from the specified string.
Parameters:
Returns:
_createShaderProgram
-
ctx
Creates the shader program that's going to be used to draw everything.
Parameters:
-
ctxWebGLRenderingContext
_dispatchEvent
-
eventObj -
eventPhase
_dispatchMouseEvent
-
target -
type -
bubbles -
pointerId -
o -
[nativeEvent]
Parameters:
-
targetDisplayObject -
typeString -
bubblesBoolean -
pointerIdNumber -
oObject -
[nativeEvent]MouseEvent optional
_drawToGPU
-
ctx
Draws all the currently defined boxes to the GPU.
Parameters:
-
ctxWebGLRenderingContextThe canvas WebGL context object to draw into.
_drawWebGLKids
-
kids -
ctx -
parentMVMatrix
Draw all the kids into the WebGL context.
_handleDoubleClick
-
e -
owner
Parameters:
-
eMouseEvent -
ownerStageIndicates that the event has already been captured & handled by the indicated stage.
_handlePointerDown
-
id -
e -
pageX -
pageY -
owner
_handlePointerMove
-
id -
e -
pageX -
pageY -
owner
_handlePointerUp
-
id -
e -
clear -
owner
_initializeWebGL
()
protected
Initializes rendering with WebGL using the current canvas element.
_initializeWebGLContext
()
protected
Sets up the WebGL context for rendering.
_isMouseOpaque
()
Boolean
protected
Indicates whether the display object has any mouse event listeners or a cursor.
Returns:
_setClearColor
-
r -
g -
b -
a
Sets the color to use when the WebGL canvas has been cleared.
_setMaxBoxesPoints
-
ctx -
value
Updates the maximum total number of boxes points that can be defined per draw call, and updates the buffers with the new array length sizes.
Parameters:
-
ctxWebGLRenderingContext -
valueNumberThe new this._maxBoxesPointsPerDraw value.
_setUpKidTexture
-
ctx -
kid
Sets up a kid's WebGL texture.
Parameters:
-
ctxWebGLRenderingContextThe canvas WebGL context object to draw into.
-
kidObjectThe list of kids to draw.
Returns:
_setWebGLContext
()
WebGLRenderingContext
protected
Sets the WebGL context to use for future draws.
Returns:
The newly created context.
_testMouseOver
-
clear -
owner -
eventTarget
_tick
-
props
Parameters:
-
propsObjectProperties to copy to the DisplayObject DisplayObject/tick event object. function.
_updatePointerPosition
-
id -
e -
pageX -
pageY
addChild
-
child
Adds a child to the top of the display list. Only children of type SpriteContainer, Sprite, Bitmap, BitmapText, or DOMElement are allowed. Children also MUST have either an image or spriteSheet defined on them (unless it's a DOMElement).
Example
container.addChild(bitmapInstance);You can also add multiple children at once:
container.addChild(bitmapInstance, shapeInstance, textInstance);Parameters:
-
childDisplayObjectThe display object to add.
Returns:
The child that was added, or the last child if multiple children were added.
addChildAt
-
child -
index
Adds a child to the display list at the specified index, bumping children at equal or greater indexes up one, and setting its parent to this Container. Only children of type SpriteContainer, Sprite, Bitmap, BitmapText, or DOMElement are allowed. Children also MUST have either an image or spriteSheet defined on them (unless it's a DOMElement).
Example
addChildAt(child1, index);You can also add multiple children, such as:
addChildAt(child1, child2, ..., index);The index must be between 0 and numChildren. For example, to add myShape under otherShape in the display list, you could use:
container.addChildAt(myShape, container.getChildIndex(otherShape));This would also bump otherShape's index up by one. Fails silently if the index is out of range.
Parameters:
-
childDisplayObjectThe display object to add.
-
indexNumberThe index to add the child at.
Returns:
Returns the last child that was added, or the last child if multiple children were added.
addEventListener
-
type -
listener -
[useCapture]
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:
-
typeStringThe string type of the event.
-
listenerFunction | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[useCapture]Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
cache
-
x -
y -
width -
height -
[scale=1]
Draws the display object into a new canvas, which is then used for subsequent draws. For complex content
that does not change frequently (ex. a Container with many children that do not move, or a complex vector Shape),
this can provide for much faster rendering because the content does not need to be re-rendered each tick. The
cached display object can be moved, rotated, faded, etc freely, however if its content changes, you must
manually update the cache by calling updateCache() or cache() again. You must specify
the cache area via the x, y, w, and h parameters. This defines the rectangle that will be rendered and cached
using this display object's coordinates.
Example
For example if you defined a Shape that drew a circle at 0, 0 with a radius of 25: var shape = new createjs.Shape();
shape.graphics.beginFill("#ff0000").drawCircle(0, 0, 25);
myShape.cache(-25, -25, 50, 50);Note that filters need to be defined before the cache is applied. Check out the Filter class for more information. Some filters (ex. BlurFilter) will not work as expected in conjunction with the scale param.
Usually, the resulting cacheCanvas will have the dimensions widthscale by heightscale, however some filters (ex. BlurFilter) will add padding to the canvas dimensions.
Parameters:
-
xNumberThe x coordinate origin for the cache region.
-
yNumberThe y coordinate origin for the cache region.
-
widthNumberThe width of the cache region.
-
heightNumberThe height of the cache region.
-
[scale=1]Number optionalThe scale at which the cache will be created. For example, if you cache a vector shape using myShape.cache(0,0,100,100,2) then the resulting cacheCanvas will be 200x200 px. This lets you scale and rotate cached elements with greater fidelity. Default is 1.
clearImageTexture
-
image
Clears an image's texture to free it up for garbage collection.
Parameters:
-
imageImage
clone
()
Stage
Returns a clone of this Stage.
Returns:
A clone of the current Container instance.
cloneProps
-
o
Parameters:
-
oDisplayObjectThe DisplayObject instance which will have properties from the current DisplayObject instance copied into.
contains
-
child
Returns true if the specified display object either is this container or is a descendent (child, grandchild, etc) of this container.
Parameters:
-
childDisplayObjectThe DisplayObject to be checked.
Returns:
true if the specified display object either is this container or is a descendent.
dispatchEvent
-
eventObj -
[target]
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:
-
eventObjObject | String | EventAn 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 optionalThe 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:
Returns the value of eventObj.defaultPrevented.
draw
-
ctx -
[ignoreCache=false]
Draws the stage into the specified context (using WebGL) ignoring its visible, alpha, shadow, and transform. If WebGL is not supported in the browser, it will default to a 2D context. Returns true if the draw was handled (useful for overriding functionality).
NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
Parameters:
-
ctxCanvasRenderingContext2DThe canvas 2D context object to draw into.
-
[ignoreCache=false]Boolean optionalIndicates whether the draw operation should ignore any current cache. For example, used for drawing the cache (to prevent it from simply drawing an existing cache back into itself).
enableDOMEvents
-
[enable=true]
Enables or disables the event listeners that stage adds to DOM elements (window, document and canvas). It is good practice to disable events when disposing of a Stage instance, otherwise the stage will continue to receive events from the page.
When changing the canvas property you must disable the events on the old canvas, and enable events on the new canvas or mouse events will not work as expected. For example:
myStage.enableDOMEvents(false);
myStage.canvas = anotherCanvas;
myStage.enableDOMEvents(true);Parameters:
-
[enable=true]Boolean optionalIndicates whether to enable or disable the events. Default is true.
enableMouseOver
-
[frequency=20]
Enables or disables (by passing a frequency of 0) mouse over (mouseover
and mouseout) and roll over events (rollover
and rollout) for this stage's display list. These events can
be expensive to generate, so they are disabled by default. The frequency of the events can be controlled
independently of mouse move events via the optional frequency parameter.
Example
var stage = new createjs.Stage("canvasId");
stage.enableMouseOver(10); // 10 updates per secondParameters:
-
[frequency=20]Number optionalOptional param specifying the maximum number of times per second to broadcast mouse over/out events. Set to 0 to disable mouse over events completely. Maximum is 50. A lower frequency is less responsive, but uses less CPU.
getBounds
()
Rectangle
Returns a rectangle representing this object's bounds in its local coordinate system (ie. with no transformation). Objects that have been cached will return the bounds of the cache.
Not all display objects can calculate their own bounds (ex. Shape). For these objects, you can use setBounds so that they are included when calculating Container bounds.
| All | All display objects support setting bounds manually using setBounds(). Likewise, display objects that have been cached using cache() will return the bounds of their cache. Manual and cache bounds will override the automatic calculations listed below. |
| Bitmap | Returns the width and height of the sourceRect (if specified) or image, extending from (x=0,y=0). |
| Sprite | Returns the bounds of the current frame. May have non-zero x/y if a frame registration point was specified in the spritesheet data. See also getFrameBounds |
| Container | Returns the aggregate (combined) bounds of all children that return a non-null value from getBounds(). |
| Shape | Does not currently support automatic bounds calculations. Use setBounds() to manually define bounds. |
| Text | Returns approximate bounds. Horizontal values (x/width) are quite accurate, but vertical values (y/height) are not, especially when using textBaseline values other than "top". |
| BitmapText | Returns approximate bounds. Values will be more accurate if spritesheet frame registration points are close to (x=0,y=0). |
Bounds can be expensive to calculate for some objects (ex. text, or containers with many children), and are recalculated each time you call getBounds(). You can prevent recalculation on static objects by setting the bounds explicitly:
var bounds = obj.getBounds();
obj.setBounds(bounds.x, bounds.y, bounds.width, bounds.height);
// getBounds will now use the set values, instead of recalculatingTo reduce memory impact, the returned Rectangle instance may be reused internally; clone the instance or copy its values if you need to retain it.
var myBounds = obj.getBounds().clone();
// OR:
myRect.copy(obj.getBounds());Returns:
A Rectangle instance representing the bounds, or null if bounds are not available for this object.
getCacheDataURL
()
String
Returns a data URL for the cache, or null if this display object is not cached. Uses cacheID to ensure a new data URL is not generated if the cache has not changed.
Returns:
The image data url for the cache.
getChildAt
-
index
Returns the child at the specified index.
Example
container.getChildAt(2);Parameters:
-
indexNumberThe index of the child to return.
Returns:
The child at the specified index. Returns null if there is no child at the index.
getChildByName
-
name
Returns the child with the specified name.
Parameters:
-
nameStringThe name of the child to return.
Returns:
The child with the specified name.
getChildIndex
-
child
Returns the index of the specified child in the display list, or -1 if it is not in the display list.
Example
var index = container.getChildIndex(child);Parameters:
-
childDisplayObjectThe child to return the index of.
Returns:
The index of the specified child. -1 if the child is not found.
getConcatenatedMatrix
-
[matrix]
Generates a concatenated Matrix2D object representing the combined transform of the display object and all of its parent Containers up to the highest level ancestor (usually the Stage). This can be used to transform positions between coordinate spaces, such as with localToGlobal and globalToLocal.
Parameters:
getMatrix
-
matrix
Returns a matrix based on this object's transform.
Parameters:
-
matrixMatrix2DOptional. A Matrix2D object to populate with the calculated values. If null, a new Matrix object is returned.
Returns:
A matrix representing this display object's transform.
getNumChildren
()
Number
Returns the number of children in the display list.
Returns:
The number of children in the display list.
getObjectsUnderPoint
-
x -
y
Returns an array of all display objects under the specified coordinates that are in this container's display list. This routine ignores any display objects with mouseEnabled set to false. The array will be sorted in order of visual depth, with the top-most display object at index 0. This uses shape based hit detection, and can be an expensive operation to run, so it is best to use it carefully. For example, if testing for objects under the mouse, test on tick (instead of on mousemove), and only if the mouse's position has changed.
Parameters:
Returns:
An Array of DisplayObjects under the specified coordinates.
getObjectUnderPoint
-
x -
y
Similar to Container/getObjectsUnderPoint(), but returns only the top-most display
object. This runs significantly faster than getObjectsUnderPoint(), but is still an expensive
operation. See getObjectsUnderPoint for more information.
Parameters:
Returns:
The top-most display object under the specified coordinates.
getStage
()
Stage
Returns the stage that this display object will be rendered on, or null if it has not been added to one.
Returns:
The Stage instance that the display object is a descendent of. null if the DisplayObject has not been added to a Stage.
getTransformedBounds
()
Rectangle
Returns a rectangle representing this object's bounds in its parent's coordinate system (ie. with transformations applied). Objects that have been cached will return the transformed bounds of the cache.
Not all display objects can calculate their own bounds (ex. Shape). For these objects, you can use setBounds so that they are included when calculating Container bounds.
To reduce memory impact, the returned Rectangle instance may be reused internally; clone the instance or copy its values if you need to retain it.
Container instances calculate aggregate bounds for all children that return bounds via getBounds.
Returns:
A Rectangle instance representing the bounds, or null if bounds are not available for this object.
globalToLocal
-
x -
y
Transforms the specified x and y position from the global (stage) coordinate space to the coordinate space of the display object. For example, this could be used to determine the current mouse position within the display object. Returns a Point instance with x and y properties correlating to the transformed position in the display object's coordinate space.
Example
displayObject.x = 300;
displayObject.y = 200;
stage.addChild(displayObject);
var point = myDisplayObject.globalToLocal(100, 100);
// Results in x=-200, y=-100Parameters:
Returns:
A Point instance with x and y properties correlating to the transformed position in the display object's coordinate space.
hasEventListener
-
type
Indicates whether there is at least one listener for the specified event type.
Parameters:
-
typeStringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
hitTest
-
x -
y
Tests whether the display object intersects the specified local point (ie. draws a pixel with alpha > 0 at the specified position). This ignores the alpha, shadow and compositeOperation of the display object, and all transform properties including regX/Y.
Parameters:
Returns:
A Boolean indicating whether there is a visible section of a DisplayObject that overlaps the specified coordinates.
initialize
-
canvas -
preserveDrawingBuffer -
antialias
Initialization method.
Parameters:
-
canvasHTMLCanvasElement | String | ObjectA canvas object, or the string id of a canvas object in the current document.
-
preserveDrawingBufferBooleanIf true, the canvas is NOT auto-cleared by WebGL (spec discourages true). Useful if you want to use p.autoClear = false.
-
antialiasBooleanSpecifies whether or not the browser's WebGL implementation should try to perform antialiasing.
isVisible
()
Boolean
Returns true or false indicating whether the display object would be visible if drawn to a canvas. This does not account for whether it would be visible within the boundaries of the stage.
NOTE: This method is mainly for internal use, though it may be useful for advanced uses.
Returns:
Boolean indicating whether the display object would be visible if drawn to a canvas
localToGlobal
-
x -
y
Transforms the specified x and y position from the coordinate space of the display object to the global (stage) coordinate space. For example, this could be used to position an HTML label over a specific point on a nested display object. Returns a Point instance with x and y properties correlating to the transformed coordinates on the stage.
Example
displayObject.x = 300;
displayObject.y = 200;
stage.addChild(displayObject);
var point = myDisplayObject.localToGlobal(100, 100);
// Results in x=400, y=300Parameters:
Returns:
A Point instance with x and y properties correlating to the transformed coordinates on the stage.
localToLocal
-
x -
y -
target
Transforms the specified x and y position from the coordinate space of this display object to the coordinate space of the target display object. Returns a Point instance with x and y properties correlating to the transformed position in the target's coordinate space. Effectively the same as using the following code with localToGlobal and globalToLocal.
var pt = this.localToGlobal(x, y);
pt = target.globalToLocal(pt.x, pt.y);Parameters:
-
xNumberThe x position in the source display object to transform.
-
yNumberThe y position on the source display object to transform.
-
targetDisplayObjectThe target display object to which the coordinates will be transformed.
Returns:
Returns a Point instance with x and y properties correlating to the transformed position in the target's coordinate space.
off
-
type -
listener -
[useCapture]
A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.
on
-
type -
listener -
[scope] -
[once=false] -
[data] -
[useCapture=false]
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:
-
typeStringThe string type of the event.
-
listenerFunction | ObjectAn object with a handleEvent method, or a function that will be called when the event is dispatched.
-
[scope]Object optionalThe 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 optionalIf true, the listener will remove itself after the first time it is triggered.
-
[data]optionalArbitrary data that will be included as the second parameter when the listener is called.
-
[useCapture=false]Boolean optionalFor events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.
Returns:
Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.
removeAllChildren
()
Removes all children from the display list.
Example
container.removeAlLChildren();removeAllEventListeners
-
[type]
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 optionalThe string type of the event. If omitted, all listeners for all types will be removed.
removeChild
-
child
Removes the specified child from the display list. Note that it is faster to use removeChildAt() if the index is already known.
Example
container.removeChild(child);You can also remove multiple children:
removeChild(child1, child2, ...);Returns true if the child (or children) was removed, or false if it was not in the display list.
Parameters:
-
childDisplayObjectThe child to remove.
Returns:
true if the child (or children) was removed, or false if it was not in the display list.
removeChildAt
-
index
Removes the child at the specified index from the display list, and sets its parent to null.
Example
container.removeChildAt(2);You can also remove multiple children:
container.removeChild(2, 7, ...)Returns true if the child (or children) was removed, or false if any index was out of range.
Parameters:
-
indexNumberThe index of the child to remove.
Returns:
true if the child (or children) was removed, or false if any index was out of range.
removeEventListener
-
type -
listener -
[useCapture]
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);set
-
props
Provides a chainable shortcut method for setting a number of properties on the instance.
Example
var myGraphics = new createjs.Graphics().beginFill("#ff0000").drawCircle(0, 0, 25);
var shape = stage.addChild(new Shape())
.set({graphics:myGraphics, x:100, y:100, alpha:0.5});Parameters:
-
propsObjectA generic object containing properties to copy to the DisplayObject instance.
Returns:
Returns the instance the method is called on (useful for chaining calls.)
setBounds
-
x -
y -
width -
height
Allows you to manually specify the bounds of an object that either cannot calculate their own bounds (ex. Shape & Text) for future reference, or so the object can be included in Container bounds. Manually set bounds will always override calculated bounds.
The bounds should be specified in the object's local (untransformed) coordinates. For example, a Shape instance with a 25px radius circle centered at 0,0 would have bounds of (-25, -25, 50, 50).
setChildIndex
-
child -
index
Changes the depth of the specified child. Fails silently if the child is not a child of this container, or the index is out of range.
Parameters:
-
childDisplayObject -
indexNumber
setTransform
-
[x=0] -
[y=0] -
[scaleX=1] -
[scaleY=1] -
[rotation=0] -
[skewX=0] -
[skewY=0] -
[regX=0] -
[regY=0]
Shortcut method to quickly set the transform properties on the display object. All parameters are optional. Omitted parameters will have the default value set.
Example
displayObject.setTransform(100, 100, 2, 2);Parameters:
-
[x=0]Number optionalThe horizontal translation (x position) in pixels
-
[y=0]Number optionalThe vertical translation (y position) in pixels
-
[scaleX=1]Number optionalThe horizontal scale, as a percentage of 1
-
[scaleY=1]Number optionalthe vertical scale, as a percentage of 1
-
[rotation=0]Number optionalThe rotation, in degrees
-
[skewX=0]Number optionalThe horizontal skew factor
-
[skewY=0]Number optionalThe vertical skew factor
-
[regX=0]Number optionalThe horizontal registration point in pixels
-
[regY=0]Number optionalThe vertical registration point in pixels
Returns:
Returns this instance. Useful for chaining commands.
sortChildren
-
sortFunction
Performs an array sort operation on the child list.
Example: Display children with a higher y in front.
var sortFunction = function(obj1, obj2, options) {
if (obj1.y > obj2.y) { return 1; }
if (obj1.y < obj2.y) { return -1; }
return 0;
}
container.sortChildren(sortFunction);Parameters:
-
sortFunctionFunctionthe function to use to sort the child list. See JavaScript's
Array.sortdocumentation for details.
swapChildren
-
child1 -
child2
Swaps the specified children's depth in the display list. Fails silently if either child is not a child of this Container.
Parameters:
-
child1DisplayObject -
child2DisplayObject
swapChildrenAt
-
index1 -
index2
Swaps the children at the specified indexes. Fails silently if either index is out of range.
tick
-
[params]
Propagates a tick event through the display list. This is automatically called by update unless tickOnUpdate is set to false.
Any parameters passed to tick() will be included as an array in the "param" property of the event object dispatched
to tick event handlers. Additionally, if the first parameter
is a tick event object (or has equivalent properties), then the delta,
time, runTime, and paused properties will be copied to the event object.
Some time-based features in EaselJS (for example Sprite/framerate require that a tick event object (or equivalent) be passed as the first parameter to tick(). For example:
Ticker.on("tick", handleTick);
function handleTick(evtObj) {
// do some work here, then update the stage, passing through the tick event object as the first param
// and some custom data as the second and third param:
myStage.update(evtObj, "hello", 2014);
}
// ...
myDisplayObject.on("tick", handleDisplayObjectTick);
function handleDisplayObjectTick(evt) {
console.log(evt.params[0]); // the original tick evtObj
console.log(evt.delta, evt.paused); // ex. "17 false"
console.log(evt.params[1], evt.params[2]); // "hello 2014"
}Parameters:
-
[params]optional multipleParams to include when ticking descendants. The first param should usually be a tick event.
toDataURL
-
backgroundColor -
mimeType
Returns a data url that contains a Base64-encoded image of the contents of the stage. The returned data url can be specified as the src value of an image element.
Parameters:
-
backgroundColorStringThe background color to be used for the generated image. The value can be any value HTML color value, including HEX colors, rgb and rgba. The default value is a transparent background.
-
mimeTypeStringThe MIME type of the image format to be create. The default is "image/png". If an unknown MIME type is passed in, or if the browser does not support the specified MIME type, the default value will be used.
Returns:
a Base64 encoded image.
toString
()
String
Returns a string representation of this object.
Returns:
a string representation of the instance.
update
-
[params]
Each time the update method is called, the stage will tick all descendants (see: DisplayObject/tick) and then render the display list to the canvas using WebGL. If WebGL is not supported in the browser, it will default to a 2D context.
Any parameters passed to update() will be passed on to any
tick event handlers.
Some time-based features in EaselJS (for example Sprite/framerate require that a tick event object (or equivalent) be passed as the first parameter to update(). For example:
Ticker.addEventListener("tick", handleTick);
function handleTick(evtObj) {
// do some work here, then update the stage, passing through the event object:
myStage.update(evtObj);
}Parameters:
-
[params]optional multipleParams to include when ticking descendants. The first param should usually be a tick event.
updateCache
-
compositeOperation
Redraws the display object to its cache. Calling updateCache without an active cache will throw an error. If compositeOperation is null the current cache will be cleared prior to drawing. Otherwise the display object will be drawn over the existing cache using the specified compositeOperation.
Example
Clear the current graphics of a cached shape, draw some new instructions, and then update the cache. The new line will be drawn on top of the old one. // Not shown: Creating the shape, and caching it.
shapeInstance.clear();
shapeInstance.setStrokeStyle(3).beginStroke("#ff0000").moveTo(100, 100).lineTo(200,200);
shapeInstance.updateCache();Parameters:
-
compositeOperationStringThe compositeOperation to use, or null to clear the cache and redraw it. whatwg spec on compositing.
updateContext
-
ctx
Applies this display object's transformation, alpha, globalCompositeOperation, clipping path (mask), and shadow to the specified context. This is typically called prior to draw.
Parameters:
-
ctxCanvasRenderingContext2DThe canvas 2D to update.
updateViewport
-
width -
height
Update the WebGL viewport. Note that this does NOT update the canvas element's width/height.
willTrigger
-
type
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:
-
typeStringThe string type of the event.
Returns:
Returns true if there is at least one listener for the specified event.
Properties
_antialias
Boolean
protected
Specifies whether or not the browser's WebGL implementation should try to perform antialiasing.
Default: false
_drawTexture
WebGLTexture
protected
The current texture that will be used to draw into the GPU.
Default: null
_indices
Uint16Array
protected
The indices to the vertices defined in p._vertices.
Default: null
_indicesBuffer
WebGLBuffer
protected
The buffer that contains all the indices data.
Default: null
_maxBoxesPerDraw
Number
protected
The maximum number of boxes (sprites) that can be drawn in one draw call.
Default: null
_maxBoxesPointsPerDraw
Number
protected
The maximum total number of boxes points that can be defined per draw call.
Default: null
_maxIndicesPerDraw
Number
protected
The maximum number of indices that can be drawn in one draw call.
Default: null
_maxTexturesPerDraw
Number
protected
The maximum number of textures WebGL can work with per draw call.
Default: 1
_pointerData
Object
private
Holds objects with data for each active pointer id. Each object has the following properties: x, y, event, target, overTarget, overX, overY, inBounds, posEvtObj (native event that last updated position)
_preserveDrawingBuffer
Boolean
protected
Specifies whether or not the canvas is auto-cleared by WebGL. Spec discourages true. If true, the canvas is NOT auto-cleared by WebGL. Value is ignored if p._alphaEnabled is false. Useful if you want to use p.autoClear = false.
Default: false
_projectionMatrix
Float32Array
protected
A 2D projection matrix used to convert WebGL's clipspace into normal pixels.
Default: null
_shaderProgram
WebGLProgram
protected
The shader program used to draw everything.
Default: null
_vertices
Float32Array
protected
The vertices data for the current draw call.
Default: null
_verticesBuffer
WebGLBuffer
protected
The buffer that contains all the vertices data.
Default: null
_webGLContext
WebGLRenderingContext
protected
The current WebGL canvas context.
Default: null
_webGLErrorDetected
Boolean
protected
Indicates whether or not an error has been detected when dealing with WebGL. If the is true, the behavior should be to use Canvas 2D rendering instead.
Default: false
alpha
Number
The alpha (transparency) for this display object. 0 is fully transparent, 1 is fully opaque.
Default: 1
autoClear
Boolean
Indicates whether the stage should automatically clear the canvas before each render. You can set this to false
to manually control clearing (for generative art, or when pointing multiple stages at the same canvas for
example).
Example
var stage = new createjs.Stage("canvasId");
stage.autoClear = false;Default: true
cacheCanvas
HTMLCanvasElement | Object
If a cache is active, this returns the canvas that holds the cached version of this display object. See Cache for more information.
Default: null
cacheID
Number
Returns an ID number that uniquely identifies the current cache for this display object. This can be used to determine if the cache has changed since a previous check.
Default: 0
canvas
HTMLCanvasElement | Object
The canvas the stage will render to. Multiple stages can share a single canvas, but you must disable autoClear for all but the first stage that will be ticked (or they will clear each other's render).
When changing the canvas property you must disable the events on the old canvas, and enable events on the new canvas or mouse events will not work as expected. For example:
myStage.enableDOMEvents(false);
myStage.canvas = anotherCanvas;
myStage.enableDOMEvents(true);children
Array
The array of children in the display list. You should usually use the child management methods such as addChild, removeChild, swapChildren, etc, rather than accessing this directly, but it is included for advanced uses.
Default: null
compositeOperation
String
The composite operation indicates how the pixels of this display object will be composited with the elements
behind it. If null, this property is inherited from the parent container. For more information, read the
whatwg spec on compositing.
Default: null
cursor
String
A CSS cursor (ex. "pointer", "help", "text", etc) that will be displayed when the user hovers over this display object. You must enable mouseover events using the enableMouseOver method to use this property. Setting a non-null cursor on a Container will override the cursor set on its descendants.
Default: null
drawRect
Rectangle
Specifies the area of the stage to affect when calling update. This can be use to selectively re-render only active regions of the canvas. If null, the whole canvas area is affected.
filters
Array
An array of Filter objects to apply to this display object. Filters are only applied / updated when Cache or UpdateCache is called on the display object, and only apply to the area that is cached.
Default: null
handleEvent
Function
Default event handler that calls the Stage update method when a tick event is received. This allows you to register a Stage instance as a event listener on Ticker directly, using:
Ticker.addEventListener("tick", myStage");Note that if you subscribe to ticks using this pattern, then the tick event object will be passed through to
display object tick handlers, instead of delta and paused parameters.
id
Number
Unique ID for this display object. Makes display objects easier for some uses.
Default: -1
INDICES_PER_BOX
Number
final
static
The number of indices needed to define a box using triangles. 6 indices = 2 triangles = 1 box
isWebGL
Boolean
Indicates whether WebGL is being used for rendering. For example, this would be false if WebGL is not supported in the browser.
mask
Shape
A Shape instance that defines a vector mask (clipping path) for this display object. The shape's transformation will be applied relative to the display object's parent coordinates (as if it were a child of the parent).
Default: null
MAX_BOXES_POINTS_INCREMENT
Number
final
static
The amount used to increment p._maxBoxesPointsPerDraw when the maximum has been reached. If the maximum size of element index WebGL allows for (SpriteStage.MAX_INDEX_SIZE) was used, the array size for p._vertices would equal 1280kb and p._indices 192kb. But since mobile phones with less memory need to be accounted for, the maximum size is somewhat arbitrarily divided by 4, reducing the array sizes to 320kb and 48kb respectively.
MAX_INDEX_SIZE
Number
final
static
The maximum size WebGL allows for element index numbers: 16 bit unsigned integer
mouseChildren
Boolean
Indicates whether the children of this container are independently enabled for mouse/pointer interaction. If false, the children will be aggregated under the container - for example, a click on a child shape would trigger a click event on the container.
Default: true
mouseEnabled
Boolean
Indicates whether to include this object when running mouse interactions. Setting this to false for children
of a Container will cause events on the Container to not fire when that child is
clicked. Setting this property to false does not prevent the getObjectsUnderPoint
method from returning the child.
Note: In EaselJS 0.7.0, the mouseEnabled property will not work properly with nested Containers. Please check out the latest NEXT version in GitHub for an updated version with this issue resolved. The fix will be provided in the next release of EaselJS.
Default: true
mouseInBounds
Boolean
Indicates whether the mouse is currently within the bounds of the canvas.
Default: false
mouseMoveOutside
Boolean
If true, mouse move events will continue to be called when the mouse leaves the target canvas. See mouseInBounds, and MouseEvent x/y/rawX/rawY.
Default: false
mouseX
Number
The current mouse X position on the canvas. If the mouse leaves the canvas, this will indicate the most recent position over the canvas, and mouseInBounds will be set to false.
mouseY
Number
The current mouse Y position on the canvas. If the mouse leaves the canvas, this will indicate the most recent position over the canvas, and mouseInBounds will be set to false.
name
String
An optional name for this display object. Included in toString . Useful for debugging.
Default: null
nextStage
Stage
Specifies a target stage that will have mouse / touch interactions relayed to it after this stage handles them. This can be useful in cases where you have multiple layered canvases and want user interactions events to pass through. For example, this would relay mouse events from topStage to bottomStage:
topStage.nextStage = bottomStage;To disable relaying, set nextStage to null.
MouseOver, MouseOut, RollOver, and RollOut interactions are also passed through using the mouse over settings of the top-most stage, but are only processed if the target stage has mouse over interactions enabled. Considerations when using roll over in relay targets:
- The top-most (first) stage must have mouse over interactions enabled (via enableMouseOver)
- All stages that wish to participate in mouse over interaction must enable them via enableMouseOver
- All relay targets will share the frequency value of the top-most stage
If the target stage's canvas is completely covered by this stage's canvas, you may also want to disable its DOM events using:
targetStage.enableDOMEvents(false);NUM_VERTEX_PROPERTIES
Number
final
static
The number of properties defined per vertex in p._verticesBuffer. x, y, textureU, textureV, alpha
parent
Container
final
A reference to the Container or Stage object that contains this display object, or null if it has not been added to one.
Default: null
regX
Number
The left offset for this display object's registration point. For example, to make a 100x100px Bitmap rotate around its center, you would set regX and regY to 50.
Default: 0
regY
Number
The y offset for this display object's registration point. For example, to make a 100x100px Bitmap rotate around its center, you would set regX and regY to 50.
Default: 0
scaleX
Number
The factor to stretch this display object horizontally. For example, setting scaleX to 2 will stretch the display object to twice its nominal width. To horizontally flip an object, set the scale to a negative number.
Default: 1
scaleY
Number
The factor to stretch this display object vertically. For example, setting scaleY to 0.5 will stretch the display object to half its nominal height. To vertically flip an object, set the scale to a negative number.
Default: 1
shadow
Shadow
A shadow object that defines the shadow to render on this display object. Set to null to remove a shadow. If
null, this property is inherited from the parent container.
Default: null
snapToPixel
Boolean
Indicates whether the display object should be drawn to a whole pixel when Stage/snapToPixelEnabled is true. To enable/disable snapping on whole categories of display objects, set this value on the prototype (Ex. Text.prototype.snapToPixel = true).
Default: true
snapToPixelEnabled
Boolean
Indicates whether display objects should be rendered on whole pixels. You can set the DisplayObject/snapToPixel property of display objects to false to enable/disable this behaviour on a per instance basis.
Default: false
tickChildren
Boolean
If false, the tick will not be propagated to children of this Container. This can provide some performance benefits. In addition to preventing the "tick" event from being dispatched, it will also prevent tick related updates on some display objects (ex. Sprite & MovieClip frame advancing, DOMElement visibility handling).
Default: true
tickEnabled
Boolean
If false, the tick will not run on this display object (or its children). This can provide some performance benefits. In addition to preventing the "tick" event from being dispatched, it will also prevent tick related updates on some display objects (ex. Sprite & MovieClip frame advancing, DOMElement visibility handling).
Default: true
tickOnUpdate
Boolean
If true, tick callbacks will be called on all display objects on the stage prior to rendering to the canvas.
Default: true
visible
Boolean
Indicates whether this display object should be rendered to the canvas and included when running the Stage Stage/getObjectsUnderPoint method.
Default: true
Events
click
Dispatched when the user presses their left mouse button and then releases it while over the display object. See the MouseEvent class for a listing of event properties.
dblclick
Dispatched when the user double clicks their left mouse button over this display object. See the MouseEvent class for a listing of event properties.
drawend
Dispatched each update immediately after the display list is drawn to the canvas and the canvas context is restored.
drawstart
Dispatched each update immediately before the canvas is cleared and the display list is drawn to it. You can call preventDefault on the event object to cancel the draw.
mousedown
Dispatched when the user presses their left mouse button over the display object. See the MouseEvent class for a listing of event properties.
mouseenter
Dispatched when the mouse moves into the canvas area (mouseInBounds == false) from outside it (mouseInBounds == true). This is currently only dispatched for mouse input (not touch). See the MouseEvent class for a listing of event properties.
mouseleave
Dispatched when the mouse moves from within the canvas area (mouseInBounds == true) to outside it (mouseInBounds == false). This is currently only dispatched for mouse input (not touch). See the MouseEvent class for a listing of event properties.
mouseout
Dispatched when the user's mouse leaves this display object. This event must be enabled using enableMouseOver. See also rollout. See the MouseEvent class for a listing of event properties.
mouseover
Dispatched when the user's mouse enters this display object. This event must be enabled using enableMouseOver. See also rollover. See the MouseEvent class for a listing of event properties.
pressmove
After a mousedown occurs on a display object, a pressmove event will be generated on that object whenever the mouse moves until the mouse press is released. This can be useful for dragging and similar operations.
pressup
After a mousedown occurs on a display object, a pressup event will be generated on that object when that mouse press is released. This can be useful for dragging and similar operations.
rollout
This event is similar to mouseout, with the following differences: it does not bubble, and it considers Container instances as an aggregate of their content.
For example, myContainer contains two overlapping children: shapeA and shapeB. The user moves their mouse over shapeA, then directly on to shapeB, then off both. With a listener for Mouseout:event on myContainer, two events would be received, each targeting a child element:
- when the mouse leaves shapeA (target=shapeA)
- when the mouse leaves shapeB (target=shapeB)
This event must be enabled using enableMouseOver. See the MouseEvent class for a listing of event properties.
rollover
This event is similar to mouseover, with the following differences: it does not bubble, and it considers Container instances as an aggregate of their content.
For example, myContainer contains two overlapping children: shapeA and shapeB. The user moves their mouse over shapeA and then directly on to shapeB. With a listener for Mouseover:event on myContainer, two events would be received, each targeting a child element:
- when the mouse enters shapeA (target=shapeA)
- when the mouse enters shapeB (target=shapeB)
This event must be enabled using enableMouseOver. See the MouseEvent class for a listing of event properties.
stagemousedown
Dispatched when the user presses their left mouse button on the canvas. See the MouseEvent class for a listing of event properties.
stagemousemove
Dispatched when the user moves the mouse over the canvas. See the MouseEvent class for a listing of event properties.
stagemouseup
Dispatched when the user the user releases the mouse button anywhere that the page can detect it (this varies slightly between browsers). See the MouseEvent class for a listing of event properties.
tick
Dispatched on each display object on a stage whenever the stage updates. This occurs immediately before the rendering (draw) pass. When update is called, first all display objects on the stage dispatch the tick event, then all of the display objects are drawn to stage. Children will have their Tick:event event dispatched in order of their depth prior to the event being dispatched on their parent.
tickend
Dispatched each update immediately after the tick event is propagated through the display list. Does not fire if tickOnUpdate is false. Precedes the "drawstart" event.
tickstart
Dispatched each update immediately before the tick event is propagated through the display list. You can call preventDefault on the event object to cancel propagating the tick event.