| Package | starling.display |
| Class | public class DisplayObject |
| Inheritance | DisplayObject  EventDispatcher Object |
| Subclasses | DisplayObjectContainer, Mesh |
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 coordinatesWithin 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.
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):void
function getBounds(targetSpace:DisplayObject,
out: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
| 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 | ||
| 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 | ||
| Method | Defined 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 | ||
 | 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, 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 | ||
| 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 | ||
Renders the display object with the help of a painter object. | DisplayObject | ||
setRequiresRedraw():void Forces the object to be redrawn in the next frame. | DisplayObject | ||
| 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 | |||
| alpha | property |
Hide Inherited Public Methods
Show Inherited Public Methodsalpha:NumberThe opacity of the object. 0 = transparent, 1 = opaque.
The default value is 1.
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.
public function get base():DisplayObject| blendMode | property |
blendMode:StringThe blend mode determines how the object is blended with the objects underneath.
The default value is auto.
public function get blendMode():String public function set blendMode(value:String):voidSee also
| bounds | property |
bounds:Rectangle [read-only] The bounds of the object relative to the local coordinates of the parent.
public function get bounds():Rectangle| filter | property |
filter:FragmentFilterThe 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).
public function get filter():FragmentFilter public function set filter(value:FragmentFilter):void| height | property |
height:NumberThe 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.
public function get height():Number public function set height(value:Number):void| is3D | property |
is3D:Boolean [read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
public function get is3D():Boolean| mask | property |
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.
public function get mask():DisplayObject public function set mask(value:DisplayObject):voidSee also
| name | property |
name:StringThe name of the display object (default: null). Used by 'getChildByName()' of display object containers.
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.
public function get parent():DisplayObjectContainer| pivotX | property |
pivotX:NumberThe x coordinate of the object's origin in its own coordinate space (default: 0).
public function get pivotX():Number public function set pivotX(value:Number):void| pivotY | property |
pivotY:NumberThe y coordinate of the object's origin in its own coordinate space (default: 0).
public function get pivotY():Number public function set pivotY(value:Number):void| requiresRedraw | property |
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.
public function get requiresRedraw():Boolean| 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.
public function get root():DisplayObject| rotation | property |
rotation:NumberThe rotation of the object in radians. (In Starling, all angles are measured in radians.)
public function get rotation():Number public function set rotation(value:Number):void| scale | property |
scale:NumberSets 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.
public function get scale():Number public function set scale(value:Number):void| scaleX | property |
scaleX:NumberThe horizontal scale factor. '1' means no scale, negative values flip the object.
The default value is 1.
public function get scaleX():Number public function set scaleX(value:Number):void| scaleY | property |
scaleY:NumberThe vertical scale factor. '1' means no scale, negative values flip the object.
The default value is 1.
public function get scaleY():Number public function set scaleY(value:Number):void| skewX | property |
skewX:NumberThe horizontal skew angle in radians.
public function get skewX():Number public function set skewX(value:Number):void| skewY | property |
skewY:NumberThe vertical skew angle in radians.
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.
public function get stage():Stage| touchable | property |
touchable:BooleanIndicates if this object (and its children) will receive touch events.
public function get touchable():Boolean public function set touchable(value:Boolean):void| transformationMatrix | property |
transformationMatrix:MatrixThe 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!
public function get transformationMatrix():Matrix public function set transformationMatrix(value:Matrix):void| transformationMatrix3D | property |
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!
public function get transformationMatrix3D():Matrix3D| useHandCursor | property |
useHandCursor:BooleanIndicates if the mouse cursor should transform into a hand while it's over the sprite.
The default value is false.
public function get useHandCursor():Boolean public function set useHandCursor(value:Boolean):void| visible | property |
visible:BooleanThe visibility of the object. An invisible object will be untouchable.
public function get visible():Boolean public function set visible(value:Boolean):void| width | property |
width:NumberThe 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.
public function get width():Number public function set width(value:Number):void| x | property |
x:NumberThe x coordinate of the object relative to the local coordinates of the parent.
public function get x():Number public function set x(value:Number):void| y | property |
y:NumberThe y coordinate of the object relative to the local coordinates of the parent.
public function get y():Number public function set y(value:Number):void| addEventListener | () | method |
override public function addEventListener(type:String, listener:Function):voidRegisters an event listener at a certain object.
Parameters
type:String | |
listener:Function |
| alignPivot | () | method |
public function alignPivot(horizontalAlign:String = center, verticalAlign:String = center):voidMoves 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():voidDisposes 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) |
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) |
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) |
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) |
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) |
Vector3D |
| hitTest | () | method |
public function hitTest(localPoint:Point):DisplayObjectReturns 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 |
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 |
Boolean |
| local3DToGlobal | () | method |
public function local3DToGlobal(localPoint:Vector3D, out:Point = null):PointTransforms 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) |
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) |
Point |
| removeEventListener | () | method |
override public function removeEventListener(type:String, listener:Function):voidRemoves an event listener from the object.
Parameters
type:String | |
listener:Function |
| removeEventListeners | () | method |
override public function removeEventListeners(type:String = null):voidRemoves 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):voidRemoves 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):voidRenders 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():voidForces 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.
| added | Event |
| addedToStage | Event |
starling.events.EventDispatched when an object is connected to the stage (directly or indirectly).
| enterFrame | Event |
starling.events.EnterFrameEventDispatched once every frame on every object that is connected to the stage.
| keyDown | Event |
| keyUp | Event |
| removed | Event |
| removedFromStage | Event |
starling.events.EventDispatched when an object is removed from the stage and won't be rendered any longer.
| touch | Event |