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.
Properties
_matrix
- protected Matrix2D
Default Value: null
The alpha (transparency) for this display object. 0 is fully transparent, 1 is fully opaque.
Default Value: 1
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
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
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
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
The rotation in degrees for this display object.
Default Value: 0
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
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
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
The factor to skew this display object horizontally.
Default Value: 0
The factor to skew this display object vertically.
Default Value: 0
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
Suppresses errors generated when using features like hitTest, onPress/onClick, and getObjectsUnderPoint with cross
domain content
Default Value: false
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
protected
void
_applyFilters
(
)
protected
Boolean
_testHit
(
ctx
)
- Parameters:
-
ctx
<CanvasRenderingContext2D>
- Returns:
Boolean
protected
void
applyShadow
(
ctx
,
shadow
)
- Parameters:
-
ctx
<CanvasRenderingContext2D>
-
shadow
<Shadow>
- Returns:
void
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
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.
protected
void
cloneProps
(
o
)
- Parameters:
-
o
<DisplayObject>
The DisplayObject instance which will have properties from the current DisplayObject
instance copied into.
- Returns:
void
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
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.
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).
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.
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.
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.
protected
void
initialize
(
)
Initialization method.
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
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.
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.
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
String
toString
(
)
Returns a string representation of this object.
- Returns:
String
- a string representation of the instance.
void
uncache
(
)
Clears the current cache. See cache() for more information.
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
(
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
(
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
(
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
(
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
(
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
(
)
The onTick callback is called on each display object on a stage whenever the stage updates.
This occurs immediately before the rendering (draw) pass.