Packagestarling.display
Classpublic class Button
InheritanceButton Inheritance DisplayObjectContainer Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

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

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.



Public Properties
 PropertyDefined By
  abortDistance : Number
The distance you can move away your finger before triggering is aborted.
Button
 Inheritedalpha : 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
 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
  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
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
DisplayObject
 Inheritedheight : Number
The height of the object in pixels.
DisplayObject
 Inheritedis3D : Boolean
[read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
DisplayObject
 Inheritedmask : DisplayObject
The display object that acts as a mask for the current object.
DisplayObject
 InheritedmaskInverted : 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
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
 InheritednumChildren : 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
 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
  pixelSnapping : Boolean
Controls whether or not the instance snaps to the nearest pixel.
Button
 InheritedrequiresRedraw : Boolean
[read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.
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
 Inheritedscale : 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
 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
  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
 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
 InheritedtransformationMatrix3D : 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
 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
  
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
 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] Registers an event listener at a certain object.
DisplayObject
 Inherited
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
broadcastEvent(event:Event):void
Dispatches an event on all children (recursively).
DisplayObjectContainer
 Inherited
broadcastEventWith(eventType: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
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
[override] Disposes the resources of all children.
Button
 Inherited
drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData
Draws the object into a BitmapData object.
DisplayObject
 Inherited
getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
DisplayObjectContainer
 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
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, out:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
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
 Inherited
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
 Inherited
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
 Inherited
local3DToGlobal(localPoint:Vector3D, out:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, out:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
Readjusts the dimensions of the button according to its current state texture.
Button
 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] Removes an event listener from the object.
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override] Removes all event listeners with a certain type, or all of them if type is null.
DisplayObject
 Inherited
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one, and optionally disposes it.
DisplayObject
 Inherited
render(painter:Painter):void
[override] Renders the display object with the help of a painter object.
DisplayObjectContainer
 Inherited
setChildIndex(child:DisplayObject, index:int):void
Moves a child to a certain index.
DisplayObjectContainer
 Inherited
Forces the object to be redrawn in the next frame.
DisplayObject
 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
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
 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
  Dispatched when the user triggers the button.Button
Property Detail
abortDistanceproperty
abortDistance:Number

The distance you can move away your finger before triggering is aborted.

The default value is 50.


Implementation
    public function get abortDistance():Number
    public function set abortDistance(value:Number):void
alphaWhenDisabledproperty 
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
alphaWhenDownproperty 
alphaWhenDown:Number

The alpha value of the button on touch.

The default value is 1.0.


Implementation
    public function get alphaWhenDown():Number
    public function set alphaWhenDown(value:Number):void
colorproperty 
color:uint

The 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.


Implementation
    public function get color():uint
    public function set color(value:uint):void
disabledStateproperty 
disabledState:Texture

The texture that is displayed when the button is disabled.


Implementation
    public function get disabledState():Texture
    public function set disabledState(value:Texture):void
downStateproperty 
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
enabledproperty 
enabled:Boolean

Indicates if the button can be triggered.


Implementation
    public function get enabled():Boolean
    public function set enabled(value:Boolean):void
minHitAreaSizeproperty 
minHitAreaSize:Number

The button's hit area will be extended to have at least this width / height.

The default value is on Desktop: 16, on mobile: 44.


Implementation
    public function get minHitAreaSize():Number
    public function set minHitAreaSize(value:Number):void
overlayproperty 
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).


Implementation
    public function get overlay():Sprite
overStateproperty 
overState:Texture

The texture that is displayed while mouse hovers over the button.


Implementation
    public function get overState():Texture
    public function set overState(value:Texture):void
pixelSnappingproperty 
pixelSnapping:Boolean

Controls 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.


Implementation
    public function get pixelSnapping():Boolean
    public function set pixelSnapping(value:Boolean):void
scale9Gridproperty 
scale9Grid:Rectangle

The 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.


Implementation
    public function get scale9Grid():Rectangle
    public function set scale9Grid(value:Rectangle):void

See also

scaleWhenDownproperty 
scaleWhenDown:Number

The 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.


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

The scale factor of the button while the mouse cursor hovers over it.

The default value is 1.0.


Implementation
    public function get scaleWhenOver():Number
    public function set scaleWhenOver(value:Number):void
stateproperty 
state:String

The current state of the button. The corresponding strings are found in the ButtonState class.


Implementation
    public function get state():String
    public function set state(value:String):void
styleproperty 
style:MeshStyle

The style that is used to render the button. Note that a style instance may only be used on one mesh at a time.


Implementation
    public function get style():MeshStyle
    public function set style(value:MeshStyle):void
textproperty 
text:String

The text that is displayed on the button.


Implementation
    public function get text():String
    public function set text(value:String):void
textBoundsproperty 
textBounds:Rectangle

The 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.


Implementation
    public function get textBounds():Rectangle
    public function set textBounds(value:Rectangle):void
textFormatproperty 
textFormat:TextFormat

The format of the button's TextField.


Implementation
    public function get textFormat():TextFormat
    public function set textFormat(value:TextFormat):void
textStyleproperty 
textStyle:MeshStyle

The style that is used to render the button's TextField.


Implementation
    public function get textStyle():MeshStyle
    public function set textStyle(value:MeshStyle):void
textureSmoothingproperty 
textureSmoothing:String

The smoothing type used for the button's state image.


Implementation
    public function get textureSmoothing():String
    public function set textureSmoothing(value:String):void
upStateproperty 
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
useHandCursorproperty 
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, 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.

Parameters
upState:Texture
 
text:String
 
downState:Texture (default = null)
 
overState:Texture (default = null)
 
disabledState:Texture (default = null)
Method Detail
dispose()method
override public function dispose():void

Disposes the resources of all children.

readjustSize()method 
public function readjustSize():void

Readjusts 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.

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

Dispatched when the user triggers the button. Bubbles.