DisplayObject
public class
loom2d.display.DisplayObject
Description
The DisplayObject class is the base class for all objects that are rendered on the screen.
The Display Tree
In Starling, all displayable objects are organized in a display tree. Only objects that are part of the display tree will be displayed (rendered).
The display tree consists of leaf nodes (Image, Quad) that will be rendered directly to the screen, and of container nodes (subclasses of "DisplayObjectContainer", like "Sprite"). A container is simply a display object that has child nodes - which can, again, be either leaf nodes or other containers.
At the base of the display tree, there is the Stage, which is a container, too. When you use Application as the base class for your Loom application, a Stage instance is automatically created for you.
A display object has properties that define its position in relation to its parent
(x, y), as well as its rotation and scaling factors (scaleX, scaleY). Use the
alpha and visible properties to make an object translucent or
invisible.
Every display object may be the target of touch events. If you don't want an object to be touchable, you can disable the "touchable" property. When it's disabled, neither the object nor its children will receive any more touch events.
Transforming coordinates
Within the display tree, each object has its own local coordinate system. If you rotate a container, you rotate that coordinate system - and thus all the children of the container.
Sometimes you need to know where a certain point lies relative to another coordinate
system. That's the purpose of the method getTransformationMatrix. It will
create a matrix that represents the transformation of a point in one coordinate system to
another.
Subclassing
Since DisplayObject is an abstract class, you cannot instantiate it directly, but have to use one of its subclasses instead. There are already a lot of them available, and most of the time they will suffice.
However, you can create custom subclasses as well. That way, you can create an object with a custom render function. You will need to implement the following methods when you subclass DisplayObject:
function render(support:RenderSupport, parentAlpha:Number):void
function getBounds(targetSpace:DisplayObject, resultRect:Rectangle=null):Rectangle
Have a look at the Quad class for a sample implementation of the 'getBounds' method. Currently, this implementation is backed by Cocos2DX - but in an upcoming release we will move to a more direct rendering API.
See also:
loom2d.display.DisplayObjectContainer
loom2d.display.Sprite
loom2d.display.Stage
API overview
Constructor
Attributes
Public attributes
| alpha: Number |
The opacity of the object, 0 = transparent, 1 = opaque |
| base: DisplayObject |
read-only
The topmost object in the display tree the object is part of |
| blendEnabled: Boolean |
Enables or disables blending |
| blendMode: BlendMode |
The blend mode determines how the object is blended with the objects underneath |
| bounds: Rectangle |
read-only
The bounds of the object relative to the local coordinates of the parent |
| cacheAsBitmap: Boolean |
If true, the untransformed contents get cached into a texture at render time |
| depth: Number |
If depthSort is enabled on parent, this will be used to establish draw order |
| hasVisibleArea: Boolean |
read-only
Indicates if an object occupies any visible area |
| height: Number |
The height of the object in pixels |
| ignoreHitTestAlpha: Boolean |
This can be used if you wish to have a DisplayObject with zero alpha still respond to hit tests |
| name: String |
The name of the display object (default: null) |
| parent: DisplayObjectContainer | |
| pivotX: Number |
The x coordinate of the object's origin in its own coordinate space (default: 0) |
| pivotY: Number |
The y coordinate of the object's origin in its own coordinate space (default: 0) |
| root: DisplayObject |
read-only
The root object the display object is connected to (ie: an instance of the class that was passed to the Starling constructor), or null if the object is not connected to the stage |
| rotation: Number |
The rotation of the object in radians, (In Loom2D, all angles are measured in radians.) |
| scale: Number |
General scale factor |
| scaleX: Number |
The horizontal scale factor |
| scaleY: Number |
The vertical scale factor |
| skewX: Number |
The horizontal skew angle in radians |
| skewY: Number |
The vertical skew angle in radians |
| stage: Stage |
read-only
The stage the display object is connected to, or null if it is not connected to the stage |
| styleName: String |
The style name used by the CSS system |
| touchable: Boolean |
Indicates if this object (and its children) will receive touch events |
| transformationMatrix: Matrix |
The transformation matrix of the object relative to its parent |
| visible: Boolean |
The visibility of the object, An invisible object will be untouchable |
| width: Number |
The width of the object in pixels |
| x: Number |
The x coordinate of the object relative to the local coordinates of the parent |
| y: Number |
The y coordinate of the object relative to the local coordinates of the parent |
Protected attributes
Functions
Public functions
| center (): Void |
Center the DisplayObject's pivot point using the width and height |
| dispose (): Void |
Disposes all resources of the display object |
| getBounds ( targetSpace: DisplayObject , resultRect: Rectangle = null ): Rectangle |
Returns a rectangle that completely encloses the object as it appears in another coordinate system |
| getTargetTransformationMatrix ( targetSpace: DisplayObject , resultMatrix: Matrix ): Void | native |
| globalToLocal ( globalPoint: Point ): Point |
Transforms a point from global (stage) coordinates to the local coordinate system |
| hitTest ( localPoint: Point , forTouch: Boolean = false ): DisplayObject |
Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails |
| initializeLMLNode ( id: String ): Void |
Handle LML node initialization |
| invalidateBitmapCache (): Void |
native Update the cached texture before the next render |
| localToGlobal ( localPoint: Point ): Point |
Transforms a point from the local coordinate system to global (stage) coordinates |
| preinitializeLMLNode ( id: String ): Void |
Pre-initialize the LML node |
| removeFromParent ( dispose: Boolean = false ): Void |
Removes the object from its parent, if it has one |
Protected functions
Constructor
DisplayObject ()
Attributes
blendEnabled: Boolean
Enables or disables blending. If set to false, there will be no blending and there may be performance gains.
blendMode: BlendMode
The default value is BlendMode.AUTO
The blend mode determines how the object is blended with the objects underneath.
See also:
loom2d.display.BlendMode
bounds: Rectangle
read-only
The bounds of the object relative to the local coordinates of the parent.
cacheAsBitmap: Boolean
If true, the untransformed contents get cached into a texture at render time.
The contents remain static until you turn off caching or use invalidateBitmapCache
to update the cache manually.
depth: Number
If depthSort is enabled on parent, this will be used to establish draw order. Higher values are drawn closer. Matching values have undefined order.
hasVisibleArea: Boolean
read-only
Indicates if an object occupies any visible area. (Which is the case when its 'alpha', 'scaleX' and 'scaleY' values are not zero, and its 'visible' property is enabled.)
ignoreHitTestAlpha: Boolean
This can be used if you wish to have a DisplayObject with zero alpha still respond to hit tests
name: String
The name of the display object (default: null). Used by 'getChildByName()' of display object containers.
parent: DisplayObjectContainer
root: DisplayObject
read-only
The root object the display object is connected to (ie: an instance of the class that was passed to the Starling constructor), or null if the object is not connected to the stage.
rotation: Number
The rotation of the object in radians, (In Loom2D, all angles are measured in radians.)
scale: Number
General scale factor. '1' means no scale, negative values flip the object. Use this when setting scaleX/scaleY explicitly is too verbose.
stage: Stage
read-only
The stage the display object is connected to, or null if it is not connected to the stage.
transformationMatrix: Matrix
The transformation matrix of the object relative to its parent.
If you assign a custom transformation matrix, Starling will try to figure out
suitable values for x, y, scaleX, scaleY, and rotation.
However, if the matrix was created in a different way, this might not be possible.
In that case, Starling will apply the matrix, but not update the corresponding
properties.
Protected attributes
Functions
addEventListener
(
type: String
,
listener: Function
): Void
Inherited from EventDispatcher
Registers an event listener at a certain object.
Parameters
| type: String | |
| listener: Function |
center (): Void
Center the DisplayObject's pivot point using the width and height. This centers this object about its own origin based on its width and height.
dispatchEvent
(
event: Event
): Void
Inherited from EventDispatcher
Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.
Parameters
| event: Event |
dispatchEventWith
(
type: String
,
bubbles: Boolean
= false
,
data: Object
= null
): Void
Inherited from EventDispatcher
Dispatches an event with the given parameters to all objects that have registered listeners for the given type. The method uses an internal pool of event objects to avoid allocations.
Parameters
| type: String | |
| bubbles: Boolean = false | |
| data: Object = null |
dispose (): Void
Disposes all resources of the display object. GPU buffers are released, event listeners are removed, filters are disposed.
getBounds ( targetSpace: DisplayObject , resultRect: Rectangle = null ): Rectangle
Returns a rectangle that completely encloses the object as it appears in another coordinate system. If you pass a 'resultRectangle', the result will be stored in this rectangle instead of creating a new object.
Parameters
| targetSpace: DisplayObject | |
| resultRect: Rectangle = null |
getFullTypeName
(): String
Inherited from Object
native
Gets the fully qualified type name of the Object. The fully qualified type name includes the package of the type.
Returns
| String | fully qualified type name of the Object. |
getTargetTransformationMatrix ( targetSpace: DisplayObject , resultMatrix: Matrix ): Void
native
Parameters
| targetSpace: DisplayObject | |
| resultMatrix: Matrix |
getType
(): Type
Inherited from Object
native
Gets the Type that describes the Object.
Returns
| Type | The Type that describes the object. |
getTypeName
(): String
Inherited from Object
native
Gets the type name of the Object.
Returns
| String | type name of the Object. |
globalToLocal ( globalPoint: Point ): Point
Transforms a point from global (stage) coordinates to the local coordinate system.
Parameters
| globalPoint: Point |
hasEventListener
(
type: String
): Boolean
Inherited from EventDispatcher
Returns if there are listeners registered for a certain event type.
Parameters
| type: String |
hitTest ( localPoint: Point , forTouch: Boolean = false ): DisplayObject
Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. If "forTouch" is true, untouchable and invisible objects will cause the test to fail.
Parameters
| localPoint: Point | |
| forTouch: Boolean = false |
invalidateBitmapCache (): Void
native
Update the cached texture before the next render.
This function has no effect if cacheAsBitmap is turned off.
localToGlobal ( localPoint: Point ): Point
Transforms a point from the local coordinate system to global (stage) coordinates.
Parameters
| localPoint: Point |
removeEventListener
(
type: String
,
listener: Function
): Void
Inherited from EventDispatcher
Removes an event listener from the object.
Parameters
| type: String | |
| listener: Function |
removeEventListeners
(
type: String
= null
): Void
Inherited from EventDispatcher
Removes all event listeners with a certain type, or all of them if type is null. Be careful when removing all event listeners: you never know who else was listening.
Parameters
| type: String = null |