| Package | starling.display |
| Class | public class Button |
| Inheritance | Button  DisplayObjectContainer DisplayObject EventDispatcher Object |
You can use different textures for various states of the button. If you're providing only an up state, the button is simply scaled a little when it is touched.
In addition, you can overlay text on the button. To customize the text, you can use
properties equivalent to those of the TextField class. Move the text to a certain position
by updating the textBounds property.
To react on touches on a button, there is special Event.TRIGGERED event.
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.
| Property | Defined By | ||
|---|---|---|---|
| abortDistance : Number The distance you can move away your finger before triggering is aborted. | Button | ||
 | alpha : Number The opacity of the object. | DisplayObject | |
| alphaWhenDisabled : Number The alpha value of the button when it is disabled. | Button | ||
| alphaWhenDown : Number The alpha value of the button on touch. | 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 | |
| color : uint The color of the button's state image. | Button | ||
| disabledState : Texture The texture that is displayed when the button is disabled. | Button | ||
| 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 | |
| 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 | |
| maskInverted : Boolean Indicates if the masked region of this object is set to be inverted. | DisplayObject | |
| minHitAreaSize : Number The button's hit area will be extended to have at least this width / height. | Button | ||
| name : String The name of the display object (default: null). | DisplayObject | |
| numChildren : int [read-only] The number of children of this container. | DisplayObjectContainer | |
| overlay : Sprite [read-only] The overlay sprite is displayed on top of the button contents. | Button | ||
| overState : Texture The texture that is displayed while mouse hovers over the button. | Button | ||
| 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 | |
| pixelSnapping : Boolean Controls whether or not the instance snaps to the nearest pixel. | Button | ||
| 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 | |
| scale9Grid : Rectangle The current scaling grid used for the button's state image. | Button | ||
| scaleWhenDown : Number The scale factor of the button on touch. | Button | ||
| scaleWhenOver : Number The scale factor of the button while the mouse cursor hovers over it. | 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 | |
| state : String The current state of the button. | Button | ||
| style : MeshStyle The style that is used to render the button. | Button | ||
| text : String The text that is displayed on the button. | Button | ||
| textBounds : Rectangle The bounds of the button's TextField. | Button | ||
| textFormat : TextFormat The format of the button's TextField. | Button | ||
| textStyle : MeshStyle The style that is used to render the button's TextField. | Button | ||
| textureSmoothing : String The smoothing type used for the button's state image. | Button | ||
| touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject | |
| touchGroup : Boolean If a container is a 'touchGroup', it will act as a single touchable object. | DisplayObjectContainer | |
| 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 | |
| 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 | |
| Method | Defined By | ||
|---|---|---|---|
Button(upState:Texture, text:String, downState:Texture = null, overState:Texture = null, disabledState:Texture = null) Creates a button with a set of state-textures and (optionally) some text. | Button | ||
| Adds a child to the container. | DisplayObjectContainer | |
| Adds a child to the container at a certain index. | DisplayObjectContainer | |
| 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 | |
| broadcastEvent(event:Event):void Dispatches an event on all children (recursively). | DisplayObjectContainer | |
| broadcastEventWith(eventType: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. | Button | ||
| drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData Draws the object into a BitmapData object. | DisplayObject | |
| getBounds(targetSpace:DisplayObject, out: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, 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 [override] Returns the object that is found topmost beneath a point in local coordinates, or nil
if the test fails. | DisplayObjectContainer | |
| 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 | |
readjustSize():void Readjusts the dimensions of the button according to its current state texture. | Button | ||
| 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] 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 | |
| [override] Renders the display object with the help of a painter object. | DisplayObjectContainer | |
| setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index. | DisplayObjectContainer | |
| setRequiresRedraw():void Forces the object to be redrawn in the next frame. | DisplayObject | |
| sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function
of the Vector class). | DisplayObjectContainer | |
| Swaps the indexes of two children. | DisplayObjectContainer | |
| swapChildrenAt(index1:int, index2:int):void Swaps the indexes of two children. | DisplayObjectContainer | |
| 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 | ||
| Dispatched when the user triggers the button. | Button | |||
| abortDistance | property |
Hide Inherited Public Properties
Show Inherited Public PropertiesabortDistance:NumberThe distance you can move away your finger before triggering is aborted.
The default value is 50.
public function get abortDistance():Number public function set abortDistance(value:Number):void| alphaWhenDisabled | property |
alphaWhenDisabled:NumberThe alpha value of the button when it is disabled.
The default value is 0.5.
public function get alphaWhenDisabled():Number public function set alphaWhenDisabled(value:Number):void| alphaWhenDown | property |
alphaWhenDown:NumberThe alpha value of the button on touch.
The default value is 1.0.
public function get alphaWhenDown():Number public function set alphaWhenDown(value:Number):void| color | property |
color:uintThe color of the button's state image. Just like every image object, each pixel's color is multiplied with this value.
The default value is white.
public function get color():uint public function set color(value:uint):void| disabledState | property |
disabledState:TextureThe texture that is displayed when the button is disabled.
public function get disabledState():Texture public function set disabledState(value:Texture):void| downState | property |
downState:TextureThe texture that is displayed while the button is touched.
public function get downState():Texture public function set downState(value:Texture):void| enabled | property |
enabled:BooleanIndicates if the button can be triggered.
public function get enabled():Boolean public function set enabled(value:Boolean):void| minHitAreaSize | property |
minHitAreaSize:NumberThe button's hit area will be extended to have at least this width / height.
The default value is on Desktop: 16, on mobile: 44.
public function get minHitAreaSize():Number public function set minHitAreaSize(value:Number):void| overlay | property |
overlay:Sprite [read-only] The overlay sprite is displayed on top of the button contents. It scales with the button when pressed. Use it to add additional objects to the button (e.g. an icon).
public function get overlay():Sprite| overState | property |
overState:TextureThe texture that is displayed while mouse hovers over the button.
public function get overState():Texture public function set overState(value:Texture):void| pixelSnapping | property |
pixelSnapping:BooleanControls whether or not the instance snaps to the nearest pixel. This can prevent the object from looking blurry when it's not exactly aligned with the pixels of the screen.
The default value is true.
public function get pixelSnapping():Boolean public function set pixelSnapping(value:Boolean):void| scale9Grid | property |
scale9Grid:RectangleThe current scaling grid used for the button's state image. Use this property to create buttons that resize in a smart way, i.e. with the four corners keeping the same size and only stretching the center area.
The default value is null.
public function get scale9Grid():Rectangle public function set scale9Grid(value:Rectangle):voidSee also
| scaleWhenDown | property |
scaleWhenDown:NumberThe scale factor of the button on touch. Per default, a button without a down state texture will be made slightly smaller, while a button with a down state texture remains unscaled.
public function get scaleWhenDown():Number public function set scaleWhenDown(value:Number):void| scaleWhenOver | property |
scaleWhenOver:NumberThe scale factor of the button while the mouse cursor hovers over it.
The default value is 1.0.
public function get scaleWhenOver():Number public function set scaleWhenOver(value:Number):void| state | property |
state:StringThe current state of the button. The corresponding strings are found in the ButtonState class.
public function get state():String public function set state(value:String):void| style | property |
style:MeshStyleThe style that is used to render the button. Note that a style instance may only be used on one mesh at a time.
public function get style():MeshStyle public function set style(value:MeshStyle):void| text | property |
text:StringThe text that is displayed on the button.
public function get text():String public function set text(value:String):void| textBounds | property |
textBounds:RectangleThe bounds of the button's TextField. Allows moving the text to a custom position. CAUTION: not a copy, but the actual object! Text will only update on re-assignment.
public function get textBounds():Rectangle public function set textBounds(value:Rectangle):void| textFormat | property |
textFormat:TextFormatThe format of the button's TextField.
public function get textFormat():TextFormat public function set textFormat(value:TextFormat):void| textStyle | property |
textStyle:MeshStyleThe style that is used to render the button's TextField.
public function get textStyle():MeshStyle public function set textStyle(value:MeshStyle):void| textureSmoothing | property |
textureSmoothing:StringThe smoothing type used for the button's state image.
public function get textureSmoothing():String public function set textureSmoothing(value:String):void| upState | property |
upState:TextureThe texture that is displayed when the button is not being touched.
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.
public function get useHandCursor():Boolean public function set useHandCursor(value:Boolean):void| Button | () | Constructor |
public function Button(upState:Texture, text:String, downState:Texture = null, overState:Texture = null, disabledState:Texture = null)Creates a button with a set of state-textures and (optionally) some text. Any state that is left 'null' will display the up-state texture. Beware that all state textures should have the same dimensions.
ParametersupState:Texture | |
text:String | |
downState:Texture (default = null) | |
overState:Texture (default = null) | |
disabledState:Texture (default = null) |
| dispose | () | method |
override public function dispose():voidDisposes the resources of all children.
| readjustSize | () | method |
public function readjustSize():voidReadjusts the dimensions of the button according to its current state texture. Call this method to synchronize button and texture size after assigning a texture with a different size.
| triggered | Event |