Packagestarling.display
Classpublic class DisplayObject
InheritanceDisplayObject Inheritance EventDispatcher Inheritance Object
Subclasses DisplayObjectContainer, Mesh

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:

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
 PropertyDefined 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
  height : Number
The height of the object in pixels.
DisplayObject
  is3D : Boolean
[read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
DisplayObject
  mask : DisplayObject
The display object that acts as a mask for the current object.
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
  requiresRedraw : Boolean
[read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.
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
  scale : Number
Sets both 'scaleX' and 'scaleY' to the same value.
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
  transformationMatrix3D : Matrix3D
[read-only] The 3D 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
 MethodDefined By
  
addEventListener(type:String, listener:Function):void
[override] Registers an event listener at a certain object.
DisplayObject
  
alignPivot(horizontalAlign:String = center, verticalAlign:String = center):void
Moves the pivot point to a certain position within the local coordinate system of the object.
DisplayObject
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 Inherited
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, out:Rectangle = null):Rectangle
Returns a rectangle that completely encloses the object as it appears in another coordinate system.
DisplayObject
  
getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
  
getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
  
globalToLocal(globalPoint:Point, out:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
  
globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
  
hitTest(localPoint:Point):DisplayObject
Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
DisplayObject
  
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
  
local3DToGlobal(localPoint:Vector3D, out:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
localToGlobal(localPoint:Point, out:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
removeEventListener(type:String, listener:Function):void
[override] Removes an event listener from the object.
DisplayObject
  
removeEventListeners(type:String = null):void
[override] Removes all event listeners with a certain type, or all of them if type is null.
DisplayObject
  
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one, and optionally disposes it.
DisplayObject
  
render(painter:Painter):void
Renders the display object with the help of a painter object.
DisplayObject
  
Forces the object to be redrawn in the next frame.
DisplayObject
Events
 Event Summary Defined By
  Dispatched when an object is added to a parent.DisplayObject
  Dispatched when an object is connected to the stage (directly or indirectly).DisplayObject
  Dispatched once every frame on every object that is connected to the stage.DisplayObject
  Dispatched when a key on the keyboard is pressed.DisplayObject
  Dispatched when a key on the keyboard is released.DisplayObject
  Dispatched when an object is removed from its parent.DisplayObject
  Dispatched when an object is removed from the stage and won't be rendered any longer.DisplayObject
  Dispatched when an object is touched.DisplayObject
Property Detail
alphaproperty
alpha:Number

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

The default value is 1.


Implementation
    public function get alpha():Number
    public function set alpha(value:Number):void
baseproperty 
base:DisplayObject  [read-only]

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


Implementation
    public function get base():DisplayObject
blendModeproperty 
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

boundsproperty 
bounds:Rectangle  [read-only]

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


Implementation
    public function get bounds():Rectangle
filterproperty 
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 a filter should NOT be attached to different objects simultaneously (for performance reasons). Furthermore, when you set this property to 'null' or assign a different filter, the previous filter is NOT disposed automatically (since you might want to reuse it).


Implementation
    public function get filter():FragmentFilter
    public function set filter(value:FragmentFilter):void
heightproperty 
height:Number

The height of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.


Implementation
    public function get height():Number
    public function set height(value:Number):void
is3Dproperty 
is3D:Boolean  [read-only]

Indicates if this object or any of its parents is a 'Sprite3D' object.


Implementation
    public function get is3D():Boolean
maskproperty 
mask:DisplayObject

The display object that acts as a mask for the current object. Assign null to remove it.

A pixel of the masked display object will only be drawn if it is within one of the mask's polygons. Texture pixels and alpha values of the mask are not taken into account. The mask object itself is never visible.

If the mask is part of the display list, masking will occur at exactly the location it occupies on the stage. If it is not, the mask will be placed in the local coordinate system of the target object (as if it was one of its children).

For rectangular masks, you can use simple quads; for other forms (like circles or arbitrary shapes) it is recommended to use a 'Canvas' instance.

Beware that a mask will typically cause at least two additional draw calls: one to draw the mask to the stencil buffer and one to erase it. However, if the mask object is an instance of starling.display.Quad and is aligned parallel to the stage axes, rendering will be optimized: instead of using the stencil buffer, the object will be clipped using the scissor rectangle. That's faster and reduces the number of draw calls, so make use of this when possible.

The default value is null.


Implementation
    public function get mask():DisplayObject
    public function set mask(value:DisplayObject):void

See also

nameproperty 
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
parentproperty 
parent:DisplayObjectContainer  [read-only]

The display object container that contains this display object.


Implementation
    public function get parent():DisplayObjectContainer
pivotXproperty 
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
pivotYproperty 
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
requiresRedrawproperty 
requiresRedraw:Boolean  [read-only]

Indicates if the object needs to be redrawn in the upcoming frame, i.e. if it has changed its location relative to the stage or some other aspect of its appearance since it was last rendered.


Implementation
    public function get requiresRedraw():Boolean
rootproperty 
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
rotationproperty 
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
scaleproperty 
scale:Number

Sets both 'scaleX' and 'scaleY' to the same value. The getter simply returns the value of 'scaleX' (even if the scaling values are different).

The default value is 1.


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

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

The default value is 1.


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

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

The default value is 1.


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

The horizontal skew angle in radians.


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

The vertical skew angle in radians.


Implementation
    public function get skewY():Number
    public function set skewY(value:Number):void
stageproperty 
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
touchableproperty 
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
transformationMatrixproperty 
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.

CAUTION: not a copy, but the actual object!


Implementation
    public function get transformationMatrix():Matrix
    public function set transformationMatrix(value:Matrix):void
transformationMatrix3Dproperty 
transformationMatrix3D:Matrix3D  [read-only]

The 3D transformation matrix of the object relative to its parent.

For 2D objects, this property returns just a 3D version of the 2D transformation matrix. Only the 'Sprite3D' class supports real 3D transformations.

CAUTION: not a copy, but the actual object!


Implementation
    public function get transformationMatrix3D():Matrix3D
useHandCursorproperty 
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
visibleproperty 
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
widthproperty 
width:Number

The width of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.


Implementation
    public function get width():Number
    public function set width(value:Number):void
xproperty 
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
yproperty 
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

Registers an event listener at a certain object.

Parameters

type:String
 
listener:Function

alignPivot()method 
public function alignPivot(horizontalAlign:String = center, verticalAlign: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

horizontalAlign:String (default = center)
 
verticalAlign: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 and masks are disposed.

getBounds()method 
public function getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle

Returns a rectangle that completely encloses the object as it appears in another coordinate system. If you pass an out-rectangle, the result will be stored in this rectangle instead of creating a new object.

Parameters

targetSpace:DisplayObject
 
out:Rectangle (default = null)

Returns
Rectangle
getTransformationMatrix()method 
public function getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix

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

Parameters

targetSpace:DisplayObject
 
out:Matrix (default = null)

Returns
Matrix
getTransformationMatrix3D()method 
public function getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D

Creates a matrix that represents the transformation from the local coordinate system to another. This method supports three dimensional objects created via 'Sprite3D'. If you pass an out-matrix, the result will be stored in this matrix instead of creating a new object.

Parameters

targetSpace:DisplayObject
 
out:Matrix3D (default = null)

Returns
Matrix3D
globalToLocal()method 
public function globalToLocal(globalPoint:Point, out:Point = null):Point

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

Parameters

globalPoint:Point
 
out:Point (default = null)

Returns
Point
globalToLocal3D()method 
public function globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D

Transforms a point from global (stage) coordinates to the 3D local coordinate system. If you pass an out-vector, the result will be stored in this vector instead of creating a new object.

Parameters

globalPoint:Point
 
out:Vector3D (default = null)

Returns
Vector3D
hitTest()method 
public function hitTest(localPoint:Point):DisplayObject

Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. Untouchable and invisible objects will cause the test to fail.

Parameters

localPoint:Point

Returns
DisplayObject
hitTestMask()method 
public function hitTestMask(localPoint:Point):Boolean

Checks if a certain point is inside the display object's mask. If there is no mask, this method always returns true (because having no mask is equivalent to having one that's infinitely big).

Parameters

localPoint:Point

Returns
Boolean
local3DToGlobal()method 
public function local3DToGlobal(localPoint:Vector3D, out:Point = null):Point

Transforms a 3D point from the local coordinate system to global (stage) coordinates. This is achieved by projecting the 3D point onto the (2D) view plane.

If you pass an out-point, the result will be stored in this point instead of creating a new object.

Parameters

localPoint:Vector3D
 
out:Point (default = null)

Returns
Point
localToGlobal()method 
public function localToGlobal(localPoint:Point, out:Point = null):Point

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

Parameters

localPoint:Point
 
out:Point (default = null)

Returns
Point
removeEventListener()method 
override public function removeEventListener(type:String, listener:Function):void

Removes an event listener from the object.

Parameters

type:String
 
listener:Function

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

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 (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(painter:Painter):void

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

Parameters

painter:Painter — Captures the current render state and provides utility functions for rendering.

setRequiresRedraw()method 
public function setRequiresRedraw():void

Forces the object to be redrawn in the next frame. This will prevent the object to be drawn from the render cache.

This method is called every time the object changes in any way. When creating custom mesh styles or any other custom rendering code, call this method if the object needs to be redrawn.

If the object needs to be redrawn just because it does not support the render cache, call painter.excludeFromCache() in the object's render method instead. That way, Starling's skipUnchangedFrames policy won't be disrupted.

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.