EaselJS

EaselJS  0.4.2

EaselJS > EaselJS > DisplayObject
Search:
 
Filters

Class DisplayObject

Known Subclasses:
Container BitmapAnimation DOMElement Text Bitmap Shape
DisplayObject is an abstract class that should not be constructed directly. Instead construct subclasses such as Sprite, Bitmap, and Shape. DisplayObject is the base class for all display classes in the CanvasDisplay library. It defines the core properties and methods that are shared between all display objects.

Constructor

DisplayObject ( )

Properties

_cacheDataURL - protected String

Default Value: null

_cacheDataURLID - protected Number

Default Value: 0

_cacheOffsetX - protected Number

Default Value: 0

_cacheOffsetY - protected Number

Default Value: 0

_hitTestCanvas - protected static HTMLCanvasElement


_hitTestContext - protected static CanvasRenderingContext2D


_matrix - protected Matrix2D

Default Value: null

_nextCacheID - protected static Number


alpha - Number

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

cacheCanvas - HTMLCanvasElement

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 Value: 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 Value: 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 Value: null

filters - Array[Filter]

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 Value: null

id - Number

Unique ID for this display object. Makes display objects easier for some uses.
Default Value: -1

mouseEnabled - Boolean

Indicates whether to include this object when running Stage.getObjectsUnderPoint(). Setting this to true for Sprites will cause the Sprite to be returned (not its children) regardless of whether it's mouseChildren property is true.
Default Value: true

name - String

An optional name for this display object. Included in toString(). Useful for debugging.
Default Value: null

parent - final DisplayObject

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

regX - Number

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 Value: 0

regY - Number

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 Value: 0

rotation - Number

The rotation in degrees for this display object.
Default Value: 0

scaleX - Number

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 Value: 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 it's nominal height.
Default Value: 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 Value: null

skewX - Number

The factor to skew this display object horizontally.
Default Value: 0

skewY - Number

The factor to skew this display object vertically.
Default Value: 0

snapToPixel - Boolean

Indicates whether the display object should have it's x & y position rounded prior to drawing it to stage. This only applies if the enclosing stage has snapPixelsEnabled set to true, and the display object's composite transform does not include any scaling, rotation, or skewing. The snapToPixel property is true by default for Bitmap and BitmapAnimation instances, and false for all other display objects.
Default Value: false

suppressCrossDomainErrors - static Boolean

Suppresses errors generated when using features like hitTest, onPress/onClick, and getObjectsUnderPoint with cross domain content
Default Value: false

visible - Boolean

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

x - Number

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

y - Number

The y (vertical) position of the display object, relative to its parent.
Default Value: 0

Methods

_applyFilters

protected void _applyFilters ( )
Returns: void

_testHit

protected Boolean _testHit ( ctx )
Parameters:
ctx <CanvasRenderingContext2D>
Returns: Boolean

_tick

protected void _tick ( )
Returns: void

applyShadow

protected void applyShadow ( ctx , shadow )
Parameters:
ctx <CanvasRenderingContext2D>
shadow <Shadow>
Returns: void

cache

void cache ( x , y , width , height )
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 Sprite 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.
Returns: void

clone

DisplayObject clone ( )
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

protected void cloneProps ( o )
Parameters:
o <DisplayObject> The DisplayObject instance which will have properties from the current DisplayObject instance copied into.
Returns: void

draw

void draw ( ctx , ignoreCache )
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).
Returns: void

getCacheDataURL.

void 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.
Returns: void

getConcatenatedMatrix

Matrix2D getConcatenatedMatrix ( mtx )
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).

getStage

Stage getStage ( )
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

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

hitTest

Boolean 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:
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 void initialize ( )
Initialization method.
Returns: void

isVisible

Boolean isVisible ( )
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

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

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

setTransform

void setTransform ( x , y , scaleX , scaleY , rotation , skewX , skewY , regX , regY )
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:
x <Number>
y <Number>
scaleX <Number>
scaleY <Number>
rotation <Number>
skewX <Number>
skewY <Number>
regX <Number>
regY <Number>
Returns: void

toString

String toString ( )
Returns a string representation of this object.
Returns: String
a string representation of the instance.

uncache

void uncache ( )
Clears the current cache. See cache() for more information.
Returns: void

updateCache

void 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.
Parameters:
compositeOperation <String> The compositeOperation to use, or null to clear the cache and redraw it. whatwg spec on compositing.
Returns: void

Events

onClick

onClick ( event )
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.
Parameters:
event <MouseEvent> MouseEvent with information about the event.

onDoubleClick

onDoubleClick ( event )
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.
Parameters:
event <MouseEvent> MouseEvent with information about the event.

onMouseOut

onMouseOut ( event )
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.
Parameters:
event <MouseEvent> MouseEvent with information about the event.

onMouseOver

onMouseOver ( event )
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.
Parameters:
event <MouseEvent> MouseEvent with information about the event.

onPress

onPress ( event )
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.
Parameters:
event <MouseEvent> MouseEvent with information about the event.

onTick

onTick ( )
The onTick callback is called on each display object on a stage whenever the stage updates. This occurs immediately before the rendering (draw) pass.