API Documentation for: 0.6.1
Show:

DOMElement Class

Extends DisplayObject
Defined in: DOMElement:36
Module: EaselJS

This class is still experimental, and more advanced use is likely to be buggy. Please report bugs.

A DOMElement allows you to associate a HTMLElement with the display list. It will be transformed within the DOM as though it is child of the Container it is added to. However, it is not rendered to canvas, and as such will retain whatever z-index it has relative to the canvas (ie. it will be drawn in front of or behind the canvas).

The position of a DOMElement is relative to their parent node in the DOM. It is recommended that the DOM Object be added to a div that also contains the canvas so that they share the same position on the page.

DOMElement is useful for positioning HTML elements over top of canvas content, and for elements that you want to display outside the bounds of the canvas. For example, a tooltip with rich HTML content.

Mouse Interaction

DOMElement instances are not full EaselJS display objects, and do not participate in EaselJS mouse events or support methods like hitTest. To get mouse events from a DOMElement, you must instead add handlers to the htmlElement (note, this does not support EventDispatcher)

 var domElement = new createjs.DOMElement(htmlElement);
 domElement.htmlElement.onclick = function() {
     console.log("clicked");
 }

Constructor

DOMElement

(
  • htmlElement
)

Defined in DOMElement:36

Parameters:

  • htmlElement HTMLElement

    A reference or id for the DOM element to manage.

Methods

_applyFilters

() protected

_applyShadow

(
  • ctx
  • shadow
)
protected

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

Inherited from DisplayObject: _testHit:1032

Parameters:

  • ctx CanvasRenderingContext2D

Returns:

_tick

() protected

Inherited from DisplayObject but overwritten in _tick:253

addEventListener

(
  • type
  • listener
)
Function | Object

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.

Returns:

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

cache

()

Inherited from DisplayObject but overwritten in cache:156

Not applicable to DOMElement.

clone

()

Inherited from DisplayObject but overwritten in clone:198

DOMElement cannot be cloned. Throws an error.

cloneProps

(
  • o
)
protected

Inherited from DisplayObject: cloneProps:977

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 to all listeners.

Example

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

 // Use an object
 var event = {
     type: "complete",
     foo: "bar"
 };
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String

    An object with a "type" property, or a string type. If a string is used, dispatchEvent will construct a generic event object with the specified type.

  • [target] Object optional

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

Returns:

Boolean: Returns true if any listener returned true.

draw

(
  • ctx
  • ignoreCache
)

Inherited from DisplayObject but overwritten in draw:124

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 Matrix2D 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

Inherited from DisplayObject: getMatrix:871

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

Inherited from DisplayObject: getStage:746

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

()

Inherited from DisplayObject but overwritten in globalToLocal:186

Not applicable to DOMElement.

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.

hitArea

()

Defined in hitArea:174

Not applicable to DOMElement.

hitTest

(
  • x
  • y
)
Boolean

Inherited from DisplayObject: hitTest:905

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.

Example

 stage.addEventListener("stagemousedown", handleMouseDown);
 function handleMouseDown(event) {
     var hit = myShape.hitTest(event.stageX, event.stageY);
 }

Please note that shape-to-shape collision is not currently supported by EaselJS.

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:96

Initialization method.

isVisible

() Boolean

Inherited from DisplayObject but overwritten in isVisible:113

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

()

Inherited from DisplayObject but overwritten in localToGlobal:180

Not applicable to DOMElement.

localToLocal

()

Inherited from DisplayObject but overwritten in localToLocal:192

Not applicable to DOMElement.

removeAllEventListeners

(
  • [type]
)

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

Example

 // Remove all listeners
 displayObject.removeAllEvenListeners();

 // 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
)

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.

set

(
  • props
)
DisplayObject

Inherited from DisplayObject: set:935

Provides a chainable shortcut method for setting a number of properties on a DisplayObject 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:

  • 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=0]
  • [y=0]
  • [scaleX=1]
  • [scaleY=1]
  • [rotation=0]
  • [skewX=0]
  • [skewY=0]
  • [regX=0]
  • [regY=0]
)
DisplayObject

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 optional

    The horizontal translation (x position) in pixels

  • [y=0] Number optional

    The vertical translation (y position) in pixels

  • [scaleX=1] Number optional

    The horizontal scale, as a percentage of 1

  • [scaleY=1] Number optional

    the vertical scale, as a percentage of 1

  • [rotation=0] Number optional

    The rotation, in degrees

  • [skewX=0] Number optional

    The horizontal skew factor

  • [skewY=0] Number optional

    The vertical skew factor

  • [regX=0] Number optional

    The horizontal registration point in pixels

  • [regY=0] Number optional

    The vertical registration point in pixels

Returns:

DisplayObject: Returns this instance. Useful for chaining commands.

toString

() String

Inherited from EventDispatcher but overwritten in toString:206

Returns a string representation of this object.

Returns:

String: a string representation of the instance.

uncache

()

Inherited from DisplayObject but overwritten in uncache:162

Not applicable to DOMElement.

updateCache

()

Inherited from DisplayObject but overwritten in updateCache:168

Not applicable to DOMElement.

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:

  • ctx CanvasRenderingContext2D

    The canvas 2D to update.

Properties

_cacheDataURL

String protected

Default: null

_cacheDataURLID

Number protected

Default: 0

_cacheOffsetX

Number protected

Default: 0

_cacheOffsetY

Number protected

Default: 0

_cacheScale

Number protected

Inherited from DisplayObject: _cacheScale:546

Default: 1

_listeners

Object protected

Inherited from EventDispatcher: _listeners:90

_matrix

Matrix2D protected

Inherited from DisplayObject: _matrix:570

Default: null

_oldMtx

Unknown protected

Defined in _oldMtx:82

alpha

Number

Inherited from DisplayObject: alpha:229

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

Default: 1

cacheCanvas

HTMLCanvasElement | Object

Inherited from DisplayObject: cacheCanvas:237

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

Inherited from DisplayObject: cacheID:475

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

Inherited from DisplayObject: cursor:506

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. If null it will use the default cursor.

Default: null

DisplayObject__tick

Function protected

DisplayObject_initialize

Function private

filters

Array

Inherited from DisplayObject: filters:466

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

Inherited from DisplayObject: hitArea:492

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

Note that hitArea is NOT currently used by the hitTest() method, nor is it supported for Stage.

Default: null

htmlElement

HTMLElement

Defined in htmlElement:74

The DOM object to manage.

id

Number

Inherited from DisplayObject: id:246

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

Default: -1

mask

Shape

Inherited from DisplayObject: mask:483

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

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. Note that setting this property to false does not prevent the getObjectsUnderPoint method from returning the child.

Default: true

name

String

Inherited from DisplayObject: name:265

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

Default: null

onClick

Function deprecated

Inherited from DisplayObject: onClick:414

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

Inherited from DisplayObject: onDoubleClick:424

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

Inherited from DisplayObject: onMouseOut:443

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

Inherited from DisplayObject: onMouseOver:434

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

Inherited from DisplayObject: onPress:403

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

Inherited from DisplayObject: onTick:452

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

Inherited from DisplayObject: parent:273

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

Inherited from DisplayObject: regX:283

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

Inherited from DisplayObject: regY:292

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

Inherited from DisplayObject: rotation:301

The rotation in degrees for this display object.

Default: 0

scaleX

Number

Inherited from DisplayObject: scaleX:309

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. To horizontally flip an object, set the scale to a negative number.

Default: 1

scaleY

Number

Inherited from DisplayObject: scaleY:318

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. To vertically flip an object, set the scale to a negative number.

Default: 1

shadow

Shadow

Inherited from DisplayObject: shadow:343

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

Inherited from DisplayObject: skewX:327

The factor to skew this display object horizontally.

Default: 0

skewY

Number

Inherited from DisplayObject: skewY:335

The factor to skew this display object vertically.

Default: 0

snapToPixel

Boolean deprecated

Inherited from DisplayObject: snapToPixel:387

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

visible

Boolean

Inherited from DisplayObject: visible:352

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

Default: true

x

Number

Inherited from DisplayObject: x:361

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

Default: 0

y

Number

Inherited from DisplayObject: y:369

Default: 0

Events

click

Inherited from DisplayObject but overwritten in click:215

Interaction events should be added to htmlElement, and not the DOMElement instance, since DOMElement instances are not full EaselJS display objects and do not participate in EaselJS mouse events.

dblClick

Defined in dblClick:221

Interaction events should be added to htmlElement, and not the DOMElement instance, since DOMElement instances are not full EaselJS display objects and do not participate in EaselJS mouse events.

dblclick

Inherited from DisplayObject: dblclick:191

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

Inherited from DisplayObject but overwritten in mousedown:227

Interaction events should be added to htmlElement, and not the DOMElement instance, since DOMElement instances are not full EaselJS display objects and do not participate in EaselJS mouse events.

mouseout

Inherited from DisplayObject: mouseout:207

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

Inherited from DisplayObject but overwritten in mouseover:233

The HTMLElement can listen for the mouseover event, not the DOMElement instance. Since DOMElement instances are not full EaselJS display objects and do not participate in EaselJS mouse events.

tick

Inherited from DisplayObject but overwritten in tick:239

Not applicable to DOMElement.