Packagestarling.display
Classpublic class Sprite
InheritanceSprite Inheritance DisplayObjectContainer Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

A Sprite is the most lightweight, non-abstract container class.

Use it as a simple means of grouping objects together in one coordinate system, or as the base class for custom display objects.

Flattened Sprites

The flatten-method allows you to optimize the rendering of static parts of your display list.

It analyzes the tree of children attached to the sprite and optimizes the rendering calls in a way that makes rendering extremely fast. The speed-up comes at a price, though: you will no longer see any changes in the properties of the children (position, rotation, alpha, etc.). To update the object after changes have happened, simply call flatten again, or unflatten the object.

Clipping Rectangle

The clipRect property allows you to clip the visible area of the sprite to a rectangular region. Only pixels inside the rectangle will be displayed. This is a very fast way to mask objects. However, there is one limitation: the clipRect only works with stage-aligned rectangles, i.e. you cannot rotate or skew the rectangle. This limitation is inherited from the underlying "scissoring" technique that is used internally.

See also

DisplayObject
DisplayObjectContainer


Public Properties
 PropertyDefined By
 Inheritedalpha : Number
The opacity of the object.
DisplayObject
 Inheritedbase : DisplayObject
[read-only] The topmost object in the display tree the object is part of.
DisplayObject
 InheritedblendMode : String
The blend mode determines how the object is blended with the objects underneath.
DisplayObject
 Inheritedbounds : Rectangle
[read-only] The bounds of the object relative to the local coordinates of the parent.
DisplayObject
  clipRect : Rectangle
The object's clipping rectangle in its local coordinate system.
Sprite
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
DisplayObject
 InheritedhasVisibleArea : Boolean
[read-only] Indicates if an object occupies any visible area.
DisplayObject
 Inheritedheight : Number
The height of the object in pixels.
DisplayObject
  isFlattened : Boolean
[read-only] Indicates if the sprite was flattened.
Sprite
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
 InheritednumChildren : int
[read-only] The number of children of this container.
DisplayObjectContainer
 Inheritedparent : DisplayObjectContainer
[read-only] The display object container that contains this display object.
DisplayObject
 InheritedpivotX : Number
The x coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 InheritedpivotY : Number
The y coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 Inheritedroot : DisplayObject
[read-only] The root object the display object is connected to (i.e.
DisplayObject
 Inheritedrotation : Number
The rotation of the object in radians.
DisplayObject
 InheritedscaleX : Number
The horizontal scale factor.
DisplayObject
 InheritedscaleY : Number
The vertical scale factor.
DisplayObject
 InheritedskewX : Number
The horizontal skew angle in radians.
DisplayObject
 InheritedskewY : Number
The vertical skew angle in radians.
DisplayObject
 Inheritedstage : Stage
[read-only] The stage the display object is connected to, or null if it is not connected to the stage.
DisplayObject
 Inheritedtouchable : Boolean
Indicates if this object (and its children) will receive touch events.
DisplayObject
 InheritedtouchGroup : Boolean
If a container is a 'touchGroup', it will act as a single touchable object.
DisplayObjectContainer
 InheritedtransformationMatrix : Matrix
The transformation matrix of the object relative to its parent.
DisplayObject
 InheriteduseHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
DisplayObject
 Inheritedvisible : Boolean
The visibility of the object.
DisplayObject
 Inheritedwidth : Number
The width of the object in pixels.
DisplayObject
 Inheritedx : Number
The x coordinate of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedy : Number
The y coordinate of the object relative to the local coordinates of the parent.
DisplayObject
Public Methods
 MethodDefined By
  
Creates an empty sprite.
Sprite
 Inherited
Adds a child to the container.
DisplayObjectContainer
 Inherited
Adds a child to the container at a certain index.
DisplayObjectContainer
 Inherited
addEventListener(type:String, listener:Function):void
[override]
DisplayObject
 Inherited
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
 Inherited
broadcastEvent(event:Event):void
Dispatches an event on all children (recursively).
DisplayObjectContainer
 Inherited
broadcastEventWith(type:String, data:Object = null):void
Dispatches an event with the given parameters on all children (recursively).
DisplayObjectContainer
 Inherited
contains(child:DisplayObject):Boolean
Determines if a certain object is a child of the container (recursively).
DisplayObjectContainer
 Inherited
dispatchEvent(event:Event):void
[override]
DisplayObject
 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
[override] Disposes the resources of all children.
Sprite
  
flatten():void
Optimizes the sprite for optimal rendering performance.
Sprite
  
getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
Sprite
 Inherited
Returns a child object at a certain index.
DisplayObjectContainer
 Inherited
Returns a child object with a certain name (non-recursively).
DisplayObjectContainer
 Inherited
Returns the index of a child within the container, or "-1" if it is not found.
DisplayObjectContainer
  
getClipRect(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle
Returns the bounds of the container's clipRect in the given coordinate space, or null if the sprite doens't have a clipRect.
Sprite
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, resultPoint:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String):Boolean
Returns if there are listeners registered for a certain event type.
EventDispatcher
  
hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject
[override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
Sprite
 Inherited
localToGlobal(localPoint:Point, resultPoint:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject
Removes a child from the container.
DisplayObjectContainer
 Inherited
removeChildAt(index:int, dispose:Boolean = false):DisplayObject
Removes a child at a certain index.
DisplayObjectContainer
 Inherited
removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void
Removes a range of children from the container (endIndex included).
DisplayObjectContainer
 Inherited
removeEventListener(type:String, listener:Function):void
[override]
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override]
DisplayObject
 Inherited
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
[override] Renders the display object with the help of a support object.
Sprite
 Inherited
setChildIndex(child:DisplayObject, index:int):void
Moves a child to a certain index.
DisplayObjectContainer
 Inherited
sortChildren(compareFunction:Function):void
Sorts the children according to a given function (that works just like the sort function of the Vector class).
DisplayObjectContainer
 Inherited
Swaps the indexes of two children.
DisplayObjectContainer
 Inherited
swapChildrenAt(index1:int, index2:int):void
Swaps the indexes of two children.
DisplayObjectContainer
  
unflatten():void
Removes the rendering optimizations that were created when flattening the sprite.
Sprite
Events
 Event Summary Defined By
 InheritedDispatched when an object is added to a parent.DisplayObject
 InheritedDispatched when an object is connected to the stage (directly or indirectly).DisplayObject
 InheritedDispatched once every frame on every object that is connected to the stage.DisplayObject
  Dispatched on all children when the object is flattened.Sprite
 InheritedDispatched when a key on the keyboard is pressed.DisplayObject
 InheritedDispatched when a key on the keyboard is released.DisplayObject
 InheritedDispatched when an object is removed from its parent.DisplayObject
 InheritedDispatched when an object is removed from the stage and won't be rendered any longer.DisplayObject
 InheritedDispatched when an object is touched.DisplayObject
Property Detail
clipRectproperty
clipRect:Rectangle

The object's clipping rectangle in its local coordinate system. Only pixels within that rectangle will be drawn. Note: clip rects are axis aligned with the screen, so they will not be rotated or skewed if the Sprite is.


Implementation
    public function get clipRect():Rectangle
    public function set clipRect(value:Rectangle):void
isFlattenedproperty 
isFlattened:Boolean  [read-only]

Indicates if the sprite was flattened.


Implementation
    public function get isFlattened():Boolean
Constructor Detail
Sprite()Constructor
public function Sprite()

Creates an empty sprite.

Method Detail
dispose()method
override public function dispose():void

Disposes the resources of all children.

flatten()method 
public function flatten():void

Optimizes the sprite for optimal rendering performance. Changes in the children of a flattened sprite will not be displayed any longer. For this to happen, either call flatten again, or unflatten the sprite. Beware that the actual flattening will not happen right away, but right before the next rendering.

When you flatten a sprite, the result of all matrix operations that are otherwise executed during rendering are cached. For this reason, a flattened sprite can be rendered with much less strain on the CPU. However, a flattened sprite will always produce at least one draw call; if it were merged together with other objects, this would cause additional matrix operations, and the optimization would have been in vain. Thus, don't just blindly flatten all your sprites, but reserve flattening for sprites with a big number of children.

getBounds()method 
override 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
getClipRect()method 
public function getClipRect(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle

Returns the bounds of the container's clipRect in the given coordinate space, or null if the sprite doens't have a clipRect.

Parameters

targetSpace:DisplayObject
 
resultRect:Rectangle (default = null)

Returns
Rectangle
hitTest()method 
override 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
render()method 
override 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.

unflatten()method 
public function unflatten():void

Removes the rendering optimizations that were created when flattening the sprite. Changes to the sprite's children will immediately become visible again.

Event Detail
flatten Event
Event Object Type: starling.events.Event

Dispatched on all children when the object is flattened.