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

Package | starling.display
Class | public class Button
Inheritance | Button DisplayObjectContainer DisplayObject EventDispatcher Object

A simple button composed of an image and, optionally, text.

You can pass a texture for up- and downstate of the button. If you do not provide a down state, the button is simply scaled a little when it is touched. In addition, you can overlay a text on the button. To customize the text, almost the same options as those of text fields are provided. In addition, you can move the text to a certain position with the help of the `textBounds` property.

To react on touches on a button, there is special `triggered`-event type. Use this event instead of normal touch events - that way, users can cancel button activation by moving the mouse/finger away from the button before releasing.

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | alpha : Number The opacity of the object. | DisplayObject
|  | alphaWhenDisabled : Number The alpha value of the button when it is disabled. | Button
|  | 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
|  | downState : Texture The texture that is displayed while the button is touched. | Button
|  | enabled : Boolean Indicates if the button can be triggered. | Button
|  | filter : FragmentFilter The filter that is attached to the display object. | DisplayObject
|  | fontBold : Boolean Indicates if the font should be bold. | Button
|  | fontColor : uint The color of the font. | Button
|  | fontName : String The name of the font displayed on the button. | Button
|  | fontSize : Number The size of the font. | Button
|  | 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
|  | numChildren : int [read-only] The number of children of this container. | DisplayObjectContainer
|  | 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
|  | scaleWhenDown : Number The scale factor of the button on touch. | Button
|  | 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
|  | text : String The text that is displayed on the button. | Button
|  | textBounds : Rectangle The bounds of the textfield on the button. | Button
|  | textHAlign : String The horizontal alignment of the text on the button. | Button
|  | textVAlign : String The vertical alignment of the text on the button. | Button
|  | 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
|  | upState : Texture The texture that is displayed when the button is not being touched. | Button
|  | useHandCursor : Boolean [override] Indicates if the mouse cursor should transform into a hand while it's over the button. | Button
|  | 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
--- | --- | ---
|  | Button(upState:Texture, text:String, downState:Texture = null) Creates a button with textures for up- and down-state or text. | Button
|  | addChild(child:DisplayObject):DisplayObject Adds a child to the container. | DisplayObjectContainer
|  | addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child to the container at a certain index. | DisplayObjectContainer
|  | 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
|  | broadcastEvent(event:Event):void Dispatches an event on all children (recursively). | DisplayObjectContainer
|  | broadcastEventWith(type:String, data:Object = null):void Dispatches an event with the given parameters on all children (recursively). | DisplayObjectContainer
|  | contains(child:DisplayObject):Boolean Determines if a certain object is a child of the container (recursively). | DisplayObjectContainer
|  | 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 [override] Disposes the resources of all children. | DisplayObjectContainer
|  | getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle [override] Returns a rectangle that completely encloses the object as it appears in another coordinate system. | DisplayObjectContainer
|  | getChildAt(index:int):DisplayObject Returns a child object at a certain index. | DisplayObjectContainer
|  | getChildByName(name:String):DisplayObject Returns a child object with a certain name (non-recursively). | DisplayObjectContainer
|  | getChildIndex(child:DisplayObject):int Returns the index of a child within the container, or "-1" if it is not found. | DisplayObjectContainer
|  | 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 [override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. | DisplayObjectContainer
|  | localToGlobal(localPoint:Point, resultPoint:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject
|  | removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject Removes a child from the container. | DisplayObjectContainer
|  | removeChildAt(index:int, dispose:Boolean = false):DisplayObject Removes a child at a certain index. | DisplayObjectContainer
|  | removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void Removes a range of children from the container (endIndex included). | DisplayObjectContainer
|  | 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 [override] Renders the display object with the help of a support object. | DisplayObjectContainer
|  | setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index. | DisplayObjectContainer
|  | sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function of the Vector class). | DisplayObjectContainer
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void Swaps the indexes of two children. | DisplayObjectContainer
|  | swapChildrenAt(index1:int, index2:int):void Swaps the indexes of two children. | DisplayObjectContainer

Events
Hide Inherited Events
Show Inherited 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
|  | triggered | Dispatched when the user triggers the button. | Button

Property Detail

alphaWhenDisabled | property

`alphaWhenDisabled:Number`

The alpha value of the button when it is disabled.

The default value is `0.5`.

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

downState | property |

`downState:Texture`

The texture that is displayed while the button is touched.

Implementation
`public function get downState():Texture`
`public function set downState(value:Texture):void`

enabled | property |

`enabled:Boolean`

Indicates if the button can be triggered.

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

fontBold | property |

`fontBold:Boolean`

Indicates if the font should be bold.

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

fontColor | property |

`fontColor:uint`

The color of the font.

Implementation
`public function get fontColor():uint`
`public function set fontColor(value:uint):void`

fontName | property |

`fontName:String`

The name of the font displayed on the button. May be a system font or a registered bitmap font.

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

fontSize | property |

`fontSize:Number`

The size of the font.

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

scaleWhenDown | property |

`scaleWhenDown:Number`

The scale factor of the button on touch. Per default, a button with a down state texture won't scale.

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

text | property |

`text:String`

The text that is displayed on the button.

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

textBounds | property |

`textBounds:Rectangle`

The bounds of the textfield on the button. Allows moving the text to a custom position.

Implementation
`public function get textBounds():Rectangle`
`public function set textBounds(value:Rectangle):void`

textHAlign | property |

`textHAlign:String`

The horizontal alignment of the text on the button.

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

textVAlign | property |

`textVAlign:String`

The vertical alignment of the text on the button.

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

upState | property |

`upState:Texture`

The texture that is displayed when the button is not being touched.

Implementation
`public function get upState():Texture`
`public function set upState(value:Texture):void`

useHandCursor | property |

`useHandCursor:Boolean`[override]

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

The default value is `true`.

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

Button | () | Constructor

`public function Button(upState:Texture, text:String, downState:Texture = null)`

Creates a button with textures for up- and down-state or text.

Parameters

| `upState:Texture`
| `text:String`
| `downState:Texture` (default = `null`)``

Event Detail

triggered | Event

Event Object Type: `starling.events.Event`

Dispatched when the user triggers the button. Bubbles.

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