GODPAPER | All Packages | All Classes | Index | Frames No Frames |
DisplayObject

Package | starling.display
Class | public class DisplayObject
Inheritance | DisplayObject EventDispatcher Object
Subclasses | DisplayObjectContainer, ParticleSystem, Polygon, Quad, QuadBatch

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. To create a Starling application, you create a custom Sprite subclass, and Starling will add an instance of this class to the stage.

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. For a sample on how to write a custom render function, you can have a look at this article in the Starling Wiki.

When you override the render method, it is important that you call the method 'finishQuadBatch' of the support object. This forces Starling to render all quads that were accumulated before by different render methods (for performance reasons). Otherwise, the z-ordering will be incorrect.

See also

DisplayObjectContainer
Sprite
Stage

Public Properties

| Property | Defined By
--- | --- | ---
|  | alpha : Number The opacity of the object. | DisplayObject
|  | base : DisplayObject [read-only] The topmost object in the display tree the object is part of. | DisplayObject
|  | blendMode : String The blend mode determines how the object is blended with the objects underneath. | DisplayObject
|  | bounds : Rectangle [read-only] The bounds of the object relative to the local coordinates of the parent. | DisplayObject
|  | filter : FragmentFilter The filter that is attached to the display object. | DisplayObject
|  | hasVisibleArea : Boolean [read-only] Indicates if an object occupies any visible area. | DisplayObject
|  | height : Number The height of the object in pixels. | DisplayObject
|  | name : String The name of the display object (default: null). | DisplayObject
|  | parent : DisplayObjectContainer [read-only] The display object container that contains this display object. | DisplayObject
|  | pivotX : Number The x coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject
|  | pivotY : Number The y coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject
|  | root : DisplayObject [read-only] The root object the display object is connected to (i.e. | DisplayObject
|  | rotation : Number The rotation of the object in radians. | DisplayObject
|  | scaleX : Number The horizontal scale factor. | DisplayObject
|  | scaleY : Number The vertical scale factor. | DisplayObject
|  | skewX : Number The horizontal skew angle in radians. | DisplayObject
|  | skewY : Number The vertical skew angle in radians. | DisplayObject
|  | stage : Stage [read-only] The stage the display object is connected to, or null if it is not connected to the stage. | DisplayObject
|  | touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject
|  | transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject
|  | useHandCursor : Boolean Indicates if the mouse cursor should transform into a hand while it's over the sprite. | DisplayObject
|  | visible : Boolean The visibility of the object. | DisplayObject
|  | width : Number The width of the object in pixels. | DisplayObject
|  | x : Number The x coordinate of the object relative to the local coordinates of the parent. | DisplayObject
|  | y : Number The y coordinate of the object relative to the local coordinates of the parent. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addEventListener(type:String, listener:Function):void [override] | DisplayObject
|  | alignPivot(hAlign:String = center, vAlign:String = center):void Moves the pivot point to a certain position within the local coordinate system of the object. | DisplayObject
|  | dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher
|  | dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void Dispatches an event with the given parameters to all objects that have registered listeners for the given type. | EventDispatcher
|  | dispose():void Disposes all resources of the display object. | DisplayObject
|  | getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle Returns a rectangle that completely encloses the object as it appears in another coordinate system. | DisplayObject
|  | getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system to another. | DisplayObject
|  | globalToLocal(globalPoint:Point, resultPoint:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject
|  | hasEventListener(type:String):Boolean Returns if there are listeners registered for a certain event type. | EventDispatcher
|  | 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. | DisplayObject
|  | localToGlobal(localPoint:Point, resultPoint:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject
|  | removeEventListener(type:String, listener:Function):void [override] | DisplayObject
|  | removeEventListeners(type:String = null):void [override] | DisplayObject
|  | removeFromParent(dispose:Boolean = false):void Removes the object from its parent, if it has one, and optionally disposes it. | DisplayObject
|  | render(support:RenderSupport, parentAlpha:Number):void Renders the display object with the help of a support object. | DisplayObject

Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | added | Dispatched when an object is added to a parent. | DisplayObject
|  | addedToStage | Dispatched when an object is connected to the stage (directly or indirectly). | DisplayObject
|  | enterFrame | Dispatched once every frame on every object that is connected to the stage. | DisplayObject
|  | keyDown | Dispatched when a key on the keyboard is pressed. | DisplayObject
|  | keyUp | Dispatched when a key on the keyboard is released. | DisplayObject
|  | removed | Dispatched when an object is removed from its parent. | DisplayObject
|  | removedFromStage | Dispatched when an object is removed from the stage and won't be rendered any longer. | DisplayObject
|  | touch | Dispatched when an object is touched. | DisplayObject

Property Detail

alpha | property

`alpha:Number`

The opacity of the object. 0 = transparent, 1 = opaque.

Implementation
`public function get alpha():Number`
`public function set alpha(value:Number):void`

base | property |

`base:DisplayObject` [read-only]

The topmost object in the display tree the object is part of.

Implementation
`public function get base():DisplayObject`

blendMode | property |

`blendMode:String`

The blend mode determines how the object is blended with the objects underneath.

The default value is `auto`.

Implementation
`public function get blendMode():String`
`public function set blendMode(value:String):void`

See also

starling.display.BlendMode

bounds | property |

`bounds:Rectangle` [read-only]

The bounds of the object relative to the local coordinates of the parent.

Implementation
`public function get bounds():Rectangle`

filter | property |

`filter:FragmentFilter`

The filter that is attached to the display object. The starling.filters package contains several classes that define specific filters you can use. Beware that you should NOT use the same filter on more than one object (for performance reasons).

Implementation
`public function get filter():FragmentFilter`
`public function set filter(value:FragmentFilter):void`

hasVisibleArea | property |

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

Implementation
`public function get hasVisibleArea():Boolean`

height | property |

`height:Number`

The height of the object in pixels.

Implementation
`public function get height():Number`
`public function set height(value:Number):void`

name | property |

`name:String`

The name of the display object (default: null). Used by 'getChildByName()' of display object containers.

Implementation
`public function get name():String`
`public function set name(value:String):void`

parent | property |

`parent:DisplayObjectContainer` [read-only]

The display object container that contains this display object.

Implementation
`public function get parent():DisplayObjectContainer`

pivotX | property |

`pivotX:Number`

The x coordinate of the object's origin in its own coordinate space (default: 0).

Implementation
`public function get pivotX():Number`
`public function set pivotX(value:Number):void`

pivotY | property |

`pivotY:Number`

The y coordinate of the object's origin in its own coordinate space (default: 0).

Implementation
`public function get pivotY():Number`
`public function set pivotY(value:Number):void`

root | property |

`root:DisplayObject` [read-only]

The root object the display object is connected to (i.e. an instance of the class that was passed to the Starling constructor), or null if the object is not connected to the stage.

Implementation
`public function get root():DisplayObject`

rotation | property |

`rotation:Number`

The rotation of the object in radians. (In Starling, all angles are measured in radians.)

Implementation
`public function get rotation():Number`
`public function set rotation(value:Number):void`

scaleX | property |

`scaleX:Number`

The horizontal scale factor. '1' means no scale, negative values flip the object.

Implementation
`public function get scaleX():Number`
`public function set scaleX(value:Number):void`

scaleY | property |

`scaleY:Number`

The vertical scale factor. '1' means no scale, negative values flip the object.

Implementation
`public function get scaleY():Number`
`public function set scaleY(value:Number):void`

skewX | property |

`skewX:Number`

The horizontal skew angle in radians.

Implementation
`public function get skewX():Number`
`public function set skewX(value:Number):void`

skewY | property |

`skewY:Number`

The vertical skew angle in radians.

Implementation
`public function get skewY():Number`
`public function set skewY(value:Number):void`

stage | property |

`stage:Stage` [read-only]

The stage the display object is connected to, or null if it is not connected to the stage.

Implementation
`public function get stage():Stage`

touchable | property |

`touchable:Boolean`

Indicates if this object (and its children) will receive touch events.

Implementation
`public function get touchable():Boolean`
`public function set touchable(value:Boolean):void`

transformationMatrix | property |

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

Implementation
`public function get transformationMatrix():Matrix`
`public function set transformationMatrix(value:Matrix):void`

useHandCursor | property |

`useHandCursor:Boolean`

Indicates if the mouse cursor should transform into a hand while it's over the sprite.

The default value is `false`.

Implementation
`public function get useHandCursor():Boolean`
`public function set useHandCursor(value:Boolean):void`

visible | property |

`visible:Boolean`

The visibility of the object. An invisible object will be untouchable.

Implementation
`public function get visible():Boolean`
`public function set visible(value:Boolean):void`

width | property |

`width:Number`

The width of the object in pixels.

Implementation
`public function get width():Number`
`public function set width(value:Number):void`

x | property |

`x:Number`

The x coordinate of the object relative to the local coordinates of the parent.

Implementation
`public function get x():Number`
`public function set x(value:Number):void`

y | property |

`y:Number`

The y coordinate of the object relative to the local coordinates of the parent.

Implementation
`public function get y():Number`
`public function set y(value:Number):void`
Method Detail

addEventListener | () | method

`override public function addEventListener(type:String, listener:Function):void`

Parameters

| `type:String`
| `listener:Function`

alignPivot | () | method |

`public function alignPivot(hAlign:String = center, vAlign:String = center):void`

Moves the pivot point to a certain position within the local coordinate system of the object. If you pass no arguments, it will be centered.

Parameters

| `hAlign:String` (default = `center`)``
| `vAlign:String` (default = `center`)``

dispose | () | method |

`public function dispose():void`

Disposes all resources of the display object. GPU buffers are released, event listeners are removed, filters are disposed.

getBounds | () | method |

`public function 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` (default = `null`)``

Returns

| `Rectangle`

getTransformationMatrix | () | method |

`public function getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix`

Creates a matrix that represents the transformation from the local coordinate system to another. If you pass a 'resultMatrix', the result will be stored in this matrix instead of creating a new object.

Parameters

| `targetSpace:DisplayObject`
| `resultMatrix:Matrix` (default = `null`)``

Returns

| `Matrix`

globalToLocal | () | method |

`public function globalToLocal(globalPoint:Point, resultPoint:Point = null):Point`

Transforms a point from global (stage) coordinates to the local coordinate system. If you pass a 'resultPoint', the result will be stored in this point instead of creating a new object.

Parameters

| `globalPoint:Point`
| `resultPoint:Point` (default = `null`)``

Returns

| `Point`

hitTest | () | method |

`public function 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` (default = `false`)``

Returns

| `DisplayObject`

localToGlobal | () | method |

`public function localToGlobal(localPoint:Point, resultPoint:Point = null):Point`

Transforms a point from the local coordinate system to global (stage) coordinates. If you pass a 'resultPoint', the result will be stored in this point instead of creating a new object.

Parameters

| `localPoint:Point`
| `resultPoint:Point` (default = `null`)``

Returns

| `Point`

removeEventListener | () | method |

`override public function removeEventListener(type:String, listener:Function):void`

Parameters

| `type:String`
| `listener:Function`

removeEventListeners | () | method |

`override public function removeEventListeners(type:String = null):void`

Parameters

| `type:String` (default = `null`)``

removeFromParent | () | method |

`public function removeFromParent(dispose:Boolean = false):void`

Removes the object from its parent, if it has one, and optionally disposes it.

Parameters

| `dispose:Boolean` (default = `false`)``

render | () | method |

`public function render(support:RenderSupport, parentAlpha:Number):void`

Renders the display object with the help of a support object. Never call this method directly, except from within another render method.

Parameters

| `support:RenderSupport` — Provides utility functions for rendering.
| `parentAlpha:Number` — The accumulated alpha value from the object's parent up to the stage.

Event Detail

added | Event

Event Object Type: `starling.events.Event`

Dispatched when an object is added to a parent.

addedToStage | Event |

Event Object Type: `starling.events.Event`

Dispatched when an object is connected to the stage (directly or indirectly).

enterFrame | Event |

Event Object Type: `starling.events.EnterFrameEvent`

Dispatched once every frame on every object that is connected to the stage.

keyDown | Event |

Event Object Type: `starling.events.KeyboardEvent`

Dispatched when a key on the keyboard is pressed.

keyUp | Event |

Event Object Type: `starling.events.KeyboardEvent`

Dispatched when a key on the keyboard is released.

removed | Event |

Event Object Type: `starling.events.Event`

Dispatched when an object is removed from its parent.

removedFromStage | Event |

Event Object Type: `starling.events.Event`

Dispatched when an object is removed from the stage and won't be rendered any longer.

touch | Event |

Event Object Type: `starling.events.TouchEvent`

Dispatched when an object is touched. Bubbles.

Thu Jan 16 2014, 01:11 PM +08:00