API Documentation for: 0.6.0
Show:

DisplayObject Class

Defined in: DisplayObject:103
Module: EaselJS

DisplayObject is an abstract class that should not be constructed directly. Instead construct subclasses such as Container, Bitmap, and Shape. DisplayObject is the base class for all display classes in the EaselJS library. It defines the core properties and methods that are shared between all display objects, such as transformation properties (x, y, scaleX, scaleY, etc), caching, and mouse handlers.

Constructor

DisplayObject

()

Defined in DisplayObject:103

Methods

_applyFilters

() protected

Defined in _applyFilters:966

_applyShadow

(
  • ctx
  • shadow
)
protected

Defined in _applyShadow:922

Parameters:

  • ctx CanvasRenderingContext2D
  • shadow Shadow

_hasMouseHandler

(
  • typeMask
)
Boolean protected

Indicates whether the display object has a listener of the corresponding event types.

Parameters:

  • typeMask Number

    A bitmask indicating which event types to look for. Bit 1 specifies press & click & double click, bit 2 specifies it should look for mouse over and mouse out. This implementation may change.

Returns:

_testHit

(
  • ctx
)
Boolean protected

Defined in _testHit:949

Parameters:

  • ctx CanvasRenderingContext2D

Returns:

_tick

() protected

Defined in _tick:937

addEventListener

(
  • type
  • listener
)
Function | Object

Adds the specified event listener.

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.

Returns:

Function | Object: Returns the listener for chaining or assignment.

cache

(
  • x
  • y
  • width
  • height
  • scale
)

Defined in cache:628

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 it's 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. For example if you defined a Shape that drew a circle at 0, 0 with a radius of 25, you could call myShape.cache(-25, -25, 50, 50) to cache the full shape.

Parameters:

  • x Number

    The x coordinate origin for the cache region.

  • y Number

    The y coordinate origin for the cache region.

  • width Number

    The width of the cache region.

  • height Number

    The height of the cache region.

  • scale Number

    Optional. The 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.

clone

() DisplayObject

Defined in clone:870

Returns a clone of this DisplayObject. Some properties that are specific to this instance's current context are reverted to their defaults (for example .parent).

Returns:

DisplayObject: A clone of the current DisplayObject instance.

cloneProps

(
  • o
)
protected

Defined in cloneProps:894

Parameters:

  • o DisplayObject

    The DisplayObject instance which will have properties from the current DisplayObject instance copied into.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event.

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will contstruct a generic event object with "type" and "params" properties.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object.

Returns:

Boolean: Returns true if any listener returned true.

draw

(
  • ctx
  • ignoreCache
)

Defined in draw:581

Draws the display object into the specified context ignoring it's visible, alpha, shadow, and transform. 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:

  • ctx CanvasRenderingContext2D

    The canvas 2D context object to draw into.

  • ignoreCache Boolean

    Indicates 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).

getCacheDataURL.

()

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.

getConcatenatedMatrix

(
  • mtx
)
Matrix2D

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:

  • mtx Matrix2D

    Optional. A Matrix2D object to populate with the calculated values. If null, a new Matrix object is returned.

Returns:

Matrix2D: 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).

getMatrix

(
  • matrix
)
Matrix2D

Defined in getMatrix:800

Returns a matrix based on this object's transform.

Parameters:

  • matrix Matrix2D

    Optional. A Matrix2D object to populate with the calculated values. If null, a new Matrix object is returned.

Returns:

Matrix2D: A matrix representing this display object's transform.

getStage

() Stage

Defined in getStage:702

Returns the stage that this display object will be rendered on, or null if it has not been added to one.

Returns:

Stage: The Stage instance that the display object is a descendent of. null if the DisplayObject has not been added to a Stage.

globalToLocal

(
  • x
  • y
)
Point

Defined in globalToLocal:736

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.

Parameters:

  • x Number

    The x position on the stage to transform.

  • y Number

    The y position on the stage to transform.

Returns:

Point: A Point instance with x and y properties correlating to the transformed position in the display object's coordinate space.

hasEventListener

(
  • type
)
Boolean

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.

hitTest

(
  • x
  • y
)
Boolean

Defined in hitTest:834

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:

  • x Number

    The x position to check in the display object's local coordinates.

  • y Number

    The y position to check in the display object's local coordinates.

Returns:

Boolean: A Boolean indicting whether a visible portion of the DisplayObject intersect the specified local Point.

initialize

() protected

Inherited from EventDispatcher but overwritten in initialize:559

Initialization method.

isVisible

() Boolean

Defined in isVisible:570

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: Boolean indicating whether the display object would be visible if drawn to a canvas

localToGlobal

(
  • x
  • y
)
Point

Defined in localToGlobal:718

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.

Parameters:

  • x Number

    The x position in the source display object to transform.

  • y Number

    The y position in the source display object to transform.

Returns:

Point: A Point instance with x and y properties correlating to the transformed coordinates on the stage.

localToLocal

(
  • x
  • y
  • target
)
Point

Defined in localToLocal:755

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 calling var pt = this.localToGlobal(x, y); pt = target.globalToLocal(pt.x, pt.y);

Parameters:

  • x Number

    The x position in the source display object to transform.

  • y Number

    The y position on the stage to transform.

  • target DisplayObject

    The target display object to which the coordinates will be transformed.

Returns:

Point: Returns a Point instance with x and y properties correlating to the transformed position in the target's coordinate space.

removeAllEventListeners

(
  • [type]
)

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

Parameters:

  • [type] String optional

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

removeEventListener

(
  • type
  • listener
)

Removes the specified event listener.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

set

(
  • props
)
DisplayObject

Defined in set:858

Provides a chainable shortcut method for setting a number of properties on a DisplayObject instance. Ex.
var shape = stage.addChild( new Shape() ).set({graphics:myGraphics, x:100, y:100, alpha:0.5});

Parameters:

  • props Object

    A generic object containing properties to copy to the DisplayObject instance.

Returns:

DisplayObject: Returns The DisplayObject instance the method is called on (useful for chaining calls.)

setTransform

(
  • x
  • y
  • scaleX
  • scaleY
  • rotation
  • skewX
  • skewY
  • regX
  • regY
)
DisplayObject

Defined in setTransform:772

Shortcut method to quickly set the transform properties on the display object. All parameters are optional. Omitted parameters will have the default value set (ex. 0 for x/y, 1 for scaleX/Y).

Parameters:

Returns:

DisplayObject: Returns this instance. Useful for chaining commands.

setupContext

(
  • ctx
)

Defined in setupContext:599

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:

  • ctx CanvasRenderingContext2D

    The canvas 2D to update.

toString

() String

Inherited from EventDispatcher but overwritten in toString:882

Returns a string representation of this object.

Returns:

String: a string representation of the instance.

uncache

()

Defined in uncache:681

Clears the current cache. See cache() for more information.

updateCache

(
  • compositeOperation
)

Defined in updateCache:658

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.

Parameters:

Properties

_cacheDataURL

String protected

Defined in _cacheDataURL:539

Default: null

_cacheDataURLID

Number protected

Defined in _cacheDataURLID:531

Default: 0

_cacheOffsetX

Number protected

Defined in _cacheOffsetX:507

Default: 0

_cacheOffsetY

Number protected

Defined in _cacheOffsetY:515

Default: 0

_cacheScale

Number protected

Defined in _cacheScale:523

Default: 1

_hitTestCanvas

HTMLCanvasElement | Object protected static

Defined in _hitTestCanvas:128

_hitTestContext

CanvasRenderingContext2D protected static

Defined in _hitTestContext:137

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

_matrix

Matrix2D protected

Defined in _matrix:547

Default: null

_nextCacheID

Number protected static

Defined in _nextCacheID:145

alpha

Number

Defined in alpha:207

The alpha (transparency) for this display object. 0 is fully transparent, 1 is fully opaque.

Default: 1

cacheCanvas

HTMLCanvasElement | Object

Defined in cacheCanvas:215

If a cache is active, this returns the canvas that holds the cached version of this display object. See cache() for more information. READ-ONLY.

Default: null

cacheID

Number

Defined in cacheID:453

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

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

Defined in cursor:484

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 stage.enableMouseOver() method to use this property. If null it will use the default cursor.

Default: null

filters

Array

Defined in filters:444

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

hitArea

DisplayObject

Defined in hitArea:471

A display object that will be tested when checking mouse interactions or testing getObjectsUnderPoint. The hit area will have its transformation applied relative to this display object's coordinate space (as though the hit test object were a child of this display object and relative to its regX/Y). The hitArea will be tested using only its own alpha value regardless of the alpha value on the target display object, or the target's ancestors (parents). hitArea is NOT currently used by the hitTest() method.

Note that hitArea is not supported for Stage.

Default: null

id

Number

Defined in id:224

Unique ID for this display object. Makes display objects easier for some uses.

Default: -1

mask

Shape

Defined in mask:462

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

mouseEnabled

Boolean

Defined in mouseEnabled:232

Indicates whether to include this object when running Stage.getObjectsUnderPoint(), and thus for mouse interactions. Setting this to true for Containers will cause the Container to be returned (not its children) regardless of whether it's mouseChildren property is true.

Default: true

name

String

Defined in name:243

An optional name for this display object. Included in toString(). Useful for debugging.

Default: null

onClick

Function deprecated

Defined in onClick:392

Deprecated: In favour of the "click" event. Will be removed in a future version.

The onClick callback is called when the user presses down on and then releases the mouse button over this display object. The handler is passed a single param containing the corresponding MouseEvent instance. If an onClick handler is set on a container, it will receive the event if any of its children are clicked.

onDoubleClick

Function deprecated

Defined in onDoubleClick:402

Deprecated: In favour of the "dblClick" event. Will be removed in a future version.

The onDoubleClick callback is called when the user double clicks over this display object. The handler is passed a single param containing the corresponding MouseEvent instance. If an onDoubleClick handler is set on a container, it will receive the event if any of its children are clicked.

onMouseOut

Function deprecated

Defined in onMouseOut:421

Deprecated: In favour of the "mouseout" event. Will be removed in a future version.

The onMouseOut callback is called when the user rolls off of the display object. You must enable this event using stage.enableMouseOver(). The handler is passed a single param containing the corresponding MouseEvent instance.

onMouseOver

Function deprecated

Defined in onMouseOver:412

Deprecated: In favour of the "mouseover" event. Will be removed in a future version.

The onMouseOver callback is called when the user rolls over the display object. You must enable this event using stage.enableMouseOver(). The handler is passed a single param containing the corresponding MouseEvent instance.

onPress

Function deprecated

Defined in onPress:381

Deprecated: In favour of the "mousedown" event. Will be removed in a future version.

The onPress callback is called when the user presses down on their mouse over this display object. The handler is passed a single param containing the corresponding MouseEvent instance. You can subscribe to the onMouseMove and onMouseUp callbacks of the event object to receive these events until the user releases the mouse button. If an onPress handler is set on a container, it will receive the event if any of its children are clicked.

onTick

Function deprecated

Defined in onTick:430

Deprecated: In favour of the "tick" event. Will be removed in a future version.

The onTick callback is called on each display object on a stage whenever the stage updates. This occurs immediately before the rendering (draw) pass. When stage.update() is called, first all display objects on the stage have onTick called, then all of the display objects are drawn to stage. Children will have their onTick called in order of their depth prior to onTick being called on their parent.

Any parameters passed in to stage.update() are passed on to the onTick() handlers. For example, if you call stage.update("hello"), all of the display objects with a handler will have onTick("hello") called.

parent

Container final

Defined in parent:251

A reference to the Container or Stage object that contains this display object, or null if it has not been added to one. READ-ONLY.

Default: null

regX

Number

Defined in regX:261

The x offset for this display object's registration point. For example, to make a 100x100px Bitmap rotate around it's center, you would set regX and regY to 50.

Default: 0

regY

Number

Defined in regY:270

The y offset for this display object's registration point. For example, to make a 100x100px Bitmap rotate around it's center, you would set regX and regY to 50.

Default: 0

rotation

Number

Defined in rotation:279

The rotation in degrees for this display object.

Default: 0

scaleX

Number

Defined in scaleX:287

The factor to stretch this display object horizontally. For example, setting scaleX to 2 will stretch the display object to twice it's nominal width.

Default: 1

scaleY

Number

Defined in scaleY:296

The factor to stretch this display object vertically. For example, setting scaleY to 0.5 will stretch the display object to half it's nominal height.

Default: 1

shadow

Shadow

Defined in shadow:321

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

skewX

Number

Defined in skewX:305

The factor to skew this display object horizontally.

Default: 0

skewY

Number

Defined in skewY:313

The factor to skew this display object vertically.

Default: 0

snapToPixel

Boolean deprecated

Defined in snapToPixel:365

Deprecated: Hardware acceleration in modern browsers makes this unnecessary.

Indicates whether the display object should have it's x & y position rounded prior to drawing it to stage. Snapping to whole pixels can result in a sharper and faster draw for images (ex. Bitmap & cached objects). This only applies if the enclosing stage has snapPixelsEnabled set to true. The snapToPixel property is true by default for Bitmap and BitmapAnimation instances, and false for all other display objects.

Note that this applies only rounds the display object's local position. You should ensure that all of the display object's ancestors (parent containers) are also on a whole pixel. You can do this by setting the ancestors' snapToPixel property to true.

Default: false

suppressCrossDomainErrors

Boolean static

Suppresses errors generated when using features like hitTest, mouse events, and getObjectsUnderPoint with cross domain content

Default: false

visible

Boolean

Defined in visible:330

Indicates whether this display object should be rendered to the canvas and included when running Stage.getObjectsUnderPoint().

Default: true

x

Number

Defined in x:339

The x (horizontal) position of the display object, relative to its parent.

Default: 0

y

Number

Defined in y:347

Default: 0

Events

click

Defined in click:162

Available since 0.6.0

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

Defined in dblClick:169

Available since 0.6.0

Dispatched when the user double clicks their left mouse button over this display object. See the MouseEvent class for a listing of event properties.

mousedown

Defined in mousedown:155

Available since 0.6.0

Dispatched when the user presses their left mouse button over the display object. See the MouseEvent class for a listing of event properties.

mouseout

Defined in mouseout:185

Available since 0.6.0

Dispatched when the user's mouse rolls out of this display object. This event must be enabled using enableMouseOver. See the MouseEvent class for a listing of event properties.

mouseover

Defined in mouseover:176

Available since 0.6.0

Dispatched when the user's mouse rolls over this display object. This event must be enabled using Stage.enableMouseOver. See the MouseEvent class for a listing of event properties.

tick

Defined in tick:193

Available since 0.6.0

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 dispatched in order of their depth prior to the event being dispatched on their parent.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • params Array

    An array containing any arguments that were passed to the Stage.update() method. For example if you called stage.update("hello"), then the params would be ["hello"].