Packagefeathers.controls
Classpublic class Button
InheritanceButton Inheritance FeathersControl Inheritance starling.display.Sprite
Implements IFocusDisplayObject
Subclasses ToggleButton

A push button control that may be triggered when pressed and released.

The following example creates a button, gives it a label and listens for when the button is triggered:

     var button:Button = new Button();
     button.label = "Click Me";
     button.addEventListener( Event.TRIGGERED, button_triggeredHandler );
     this.addChild( button );

See also

How to use the Feathers Button component


Public Properties
 PropertyDefined By
  defaultIcon : DisplayObject
The icon used when no other icon is defined for the current state.
Button
  defaultLabelProperties : Object
An object that stores properties for the button's label text renderer when no specific properties are defined for the button's current state, and the properties will be passed down to the label text renderer when the button validates.
Button
  defaultSkin : DisplayObject
The skin used when no other skin is defined for the current state.
Button
 InheriteddefaultTextEditorFactory : Function
[static] A function used by all UI controls that support text editor to create an ITextEditor instance.
FeathersControl
 InheriteddefaultTextRendererFactory : Function
[static] A function used by all UI controls that support text renderers to create an ITextRenderer instance.
FeathersControl
 Inheriteddepth : int
[read-only] The component's depth in the display list, relative to the stage.
FeathersControl
  disabledIcon : DisplayObject
The icon used for the button's disabled state.
Button
  disabledLabelProperties : Object
An object that stores properties for the button's label text renderer when the button is in the Button.STATE_DISABLED state, and the properties will be passed down to the label text renderer when the button validates.
Button
  disabledSkin : DisplayObject
The skin used for the button's disabled state.
Button
  downIcon : DisplayObject
The icon used for the button's down state.
Button
  downLabelProperties : Object
An object that stores properties for the button's label text renderer when the button is in the Button.STATE_DOWN state, and the properties will be passed down to the label text renderer when the button validates.
Button
  downSkin : DisplayObject
The skin used for the button's down state.
Button
 InheritedfocusIndicatorSkin : DisplayObject
If this component supports focus, this optional skin will be displayed above the component when showFocus() is called.
FeathersControl
 InheritedfocusManager : IFocusManager
FeathersControl
 InheritedfocusOwner : IFocusDisplayObject
FeathersControl
 InheritedfocusPadding : Number
Quickly sets all focus padding properties to the same value.
FeathersControl
 InheritedfocusPaddingBottom : Number
The minimum space, in pixels, between the object's bottom edge and the bottom edge of the focus indicator skin.
FeathersControl
 InheritedfocusPaddingLeft : Number
The minimum space, in pixels, between the object's left edge and the left edge of the focus indicator skin.
FeathersControl
 InheritedfocusPaddingRight : Number
The minimum space, in pixels, between the object's right edge and the right edge of the focus indicator skin.
FeathersControl
 InheritedfocusPaddingTop : Number
The minimum space, in pixels, between the object's top edge and the top edge of the focus indicator skin.
FeathersControl
  gap : Number
The space, in pixels, between the icon and the label.
Button
  globalStyleProvider : IStyleProvider
[static] The default IStyleProvider for all Button components.
Button
  hasLabelTextRenderer : Boolean
Determines if the button's label text renderer is created or not.
Button
 Inheritedheight : Number
[override] The height of the component, in pixels.
FeathersControl
  horizontalAlign : String
The location where the button's content is aligned horizontally (on the x-axis).
Button
  hoverIcon : DisplayObject
The icon used for the button's hover state.
Button
  hoverLabelProperties : Object
An object that stores properties for the button's label text renderer when the button is in the Button.STATE_HOVER state, and the properties will be passed down to the label text renderer when the button validates.
Button
  hoverSkin : DisplayObject
The skin used for the button's hover state.
Button
  iconOffsetX : Number
Offsets the x position of the icon by a certain number of pixels.
Button
  iconOffsetY : Number
Offsets the y position of the icon by a certain number of pixels.
Button
  iconPosition : String
The location of the icon, relative to the label.
Button
 InheritedincludeInLayout : Boolean
Determines if the ILayout should use this object or ignore it.
FeathersControl
 InheritedisCreated : Boolean
[read-only] Determines if the component has been initialized and validated for the first time.
FeathersControl
 InheritedisEnabled : Boolean
Indicates whether the control is interactive or not.
FeathersControl
 InheritedisFocusEnabled : Boolean
FeathersControl
 InheritedisInitialized : Boolean
[read-only] Determines if the component has been initialized yet.
FeathersControl
  isLongPressEnabled : Boolean
Determines if FeathersEventType.LONG_PRESS will be dispatched.
Button
 InheritedisQuickHitAreaEnabled : Boolean
Similar to mouseChildren on the classic display list.
FeathersControl
  keepDownStateOnRollOut : Boolean = false
Determines if a pressed button should remain in the down state if a touch moves outside of the button's bounds.
Button
  label : String
The text displayed on the button.
Button
  labelFactory : Function
A function used to instantiate the button's label text renderer sub-component.
Button
  labelOffsetX : Number
Offsets the x position of the label by a certain number of pixels.
Button
  labelOffsetY : Number
Offsets the y position of the label by a certain number of pixels.
Button
 InheritedlayoutData : ILayoutData
Extra parameters associated with this display object that will be used by the layout algorithm.
FeathersControl
  longPressDuration : Number
The duration, in seconds, of a long press.
Button
 InheritedmaxHeight : Number
The maximum recommended height to be used for self-measurement and, optionally, by any code that is resizing this component.
FeathersControl
 InheritedmaxWidth : Number
The maximum recommended width to be used for self-measurement and, optionally, by any code that is resizing this component.
FeathersControl
  minGap : Number
If the value of the gap property is Number.POSITIVE_INFINITY, meaning that the gap will fill as much space as possible, the final calculated value will not be smaller than the value of the minGap property.
Button
 InheritedminHeight : Number
The minimum recommended height to be used for self-measurement and, optionally, by any code that is resizing this component.
FeathersControl
 InheritedminTouchHeight : Number
If using isQuickHitAreaEnabled, and the hit area's height is smaller than this value, it will be expanded.
FeathersControl
 InheritedminTouchWidth : Number
If using isQuickHitAreaEnabled, and the hit area's width is smaller than this value, it will be expanded.
FeathersControl
 InheritedminWidth : Number
The minimum recommended width to be used for self-measurement and, optionally, by any code that is resizing this component.
FeathersControl
 InheritednextTabFocus : IFocusDisplayObject
FeathersControl
  padding : Number
Quickly sets all padding properties to the same value.
Button
  paddingBottom : Number
The minimum space, in pixels, between the button's bottom edge and the button's content.
Button
  paddingLeft : Number
The minimum space, in pixels, between the button's left edge and the button's content.
Button
  paddingRight : Number
The minimum space, in pixels, between the button's right edge and the button's content.
Button
  paddingTop : Number
The minimum space, in pixels, between the button's top edge and the button's content.
Button
 InheritedpreviousTabFocus : IFocusDisplayObject
FeathersControl
  scaleWhenDown : Number
The button renders at this scale in the down state.
Button
  scaleWhenHovering : Number
The button renders at this scale in the hover state.
Button
  stateToIconFunction : Function
Returns an icon for the current state.
Button
  stateToLabelPropertiesFunction : Function
Returns a text format for the current state.
Button
  stateToSkinFunction : Function
Returns a skin for the current state.
Button
 InheritedstyleName : String
The concatenated styleNameList, with values separated by spaces.
FeathersControl
 InheritedstyleNameList : TokenList
[read-only] Contains a list of all "styles" assigned to this control.
FeathersControl
 InheritedstyleProvider : IStyleProvider
When a component initializes, a style provider may be used to set properties that affect the component's visual appearance.
FeathersControl
  upIcon : DisplayObject
The icon used for the button's up state.
Button
  upLabelProperties : Object
An object that stores properties for the button's label text renderer when the button is in the Button.STATE_UP state, and the properties will be passed down to the label text renderer when the button validates.
Button
  upSkin : DisplayObject
The skin used for the button's up state.
Button
  verticalAlign : String
The location where the button's content is aligned vertically (on the y-axis).
Button
 Inheritedwidth : Number
[override] The width of the component, in pixels.
FeathersControl
Protected Properties
 PropertyDefined By
 InheritedactualHeight : Number = 0
The final height value that should be used for layout.
FeathersControl
 InheritedactualWidth : Number = 0
The final width value that should be used for layout.
FeathersControl
  currentIcon : DisplayObject
The currently visible icon.
Button
  currentSkin : DisplayObject
The currently visible skin.
Button
  currentState : String
The current touch state of the button.
Button
 InheriteddefaultStyleProvider : IStyleProvider
[read-only] When the FeathersControl constructor is called, the globalStyleProvider property is set to this value.
FeathersControl
 InheritedexplicitHeight : Number = NaN
The height value explicitly set by calling the height setter or setSize().
FeathersControl
 InheritedexplicitWidth : Number = NaN
The width value explicitly set by calling the width setter or setSize().
FeathersControl
  labelName : String
DEPRECATED: Replaced by labelStyleName.
Button
  labelStyleName : String = feathers-button-label
The value added to the styleNameList of the label text renderer.
Button
  labelTextRenderer : ITextRenderer
The text renderer for the button's label.
Button
  stateNames : Vector.<String>
[read-only] A list of all valid touch state names for use with currentState.
Button
  touchPointID : int = -1
The saved ID of the currently active touch.
Button
Public Methods
 MethodDefined By
  
Constructor.
Button
 Inherited
hideFocus():void
If the visual indicator of focus has been displayed by showFocus(), call this function to hide it.
FeathersControl
 Inherited
invalidate(flag:String):void
Call this function to tell the UI control that a redraw is pending.
FeathersControl
 Inherited
isInvalid(flag:String = null):Boolean
Indicates whether the control is pending validation or not.
FeathersControl
 Inherited
move(x:Number, y:Number):void
Sets both the x and the y positions of the control in a single function call.
FeathersControl
 Inherited
setSize(width:Number, height:Number):void
Sets both the width and the height of the control in a single function call.
FeathersControl
 Inherited
showFocus():void
If the object has focus, an additional visual indicator may optionally be displayed to highlight the object.
FeathersControl
 Inherited
validate():void
Immediately validates the display object, if it is invalid.
FeathersControl
Protected Methods
 MethodDefined By
  
If the component's dimensions have not been set explicitly, it will measure its content and determine an ideal size for itself.
Button
 Inherited
clearInvalidationFlag(flag:String):void
Clears an invalidation flag.
FeathersControl
  
Creates the label text renderer sub-component and removes the old instance, if one exists.
Button
 Inherited
draw():void
Override to customize layout and to adjust properties of children.
FeathersControl
 Inherited
focusInHandler(event:Event):void
Default event handler for FeathersEventType.FOCUS_IN that may be overridden in subclasses to perform additional actions when the component receives focus.
FeathersControl
 Inherited
focusOutHandler(event:Event):void
Default event handler for FeathersEventType.FOCUS_OUT that may be overridden in subclasses to perform additional actions when the component loses focus.
FeathersControl
 Inherited
initialize():void
Called the first time that the UI control is added to the stage, and you should override this function to customize the initialization process.
FeathersControl
  
Positions and sizes the button's content.
Button
 Inherited
Updates the focus indicator skin by showing or hiding it and adjusting its position and dimensions.
FeathersControl
  
Sets the currentIcon property.
Button
  
Sets the currentSkin property.
Button
 Inherited
setInvalidationFlag(flag:String):void
Sets an invalidation flag.
FeathersControl
 Inherited
setSizeInternal(width:Number, height:Number, canInvalidate:Boolean):Boolean
Sets the width and height of the control, with the option of invalidating or not.
FeathersControl
  
trigger():void
Triggers the button.
Button
Events
 Event Summary Defined By
 InheritedDispatched after the component has validated for the first time.FeathersControl
 InheritedDispatched after initialize() has been called, but before the first time that draw() has been called.FeathersControl
  Dispatched when the button is pressed for a long time.Button
 InheritedDispatched when the width or height of the control changes.FeathersControl
  Dispatched when the the user taps or clicks the button.Button
Public Constants
 ConstantDefined By
  ALTERNATE_NAME_BACK_BUTTON : String = feathers-back-button
[static] DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_BACK_BUTTON.
Button
  ALTERNATE_NAME_CALL_TO_ACTION_BUTTON : String = feathers-call-to-action-button
[static] DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_CALL_TO_ACTION_BUTTON.
Button
  ALTERNATE_NAME_DANGER_BUTTON : String = feathers-danger-button
[static] DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_DANGER_BUTTON.
Button
  ALTERNATE_NAME_FORWARD_BUTTON : String = feathers-forward-button
[static] DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_FORWARD_BUTTON.
Button
  ALTERNATE_NAME_QUIET_BUTTON : String = feathers-quiet-button
[static] DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_QUIET_BUTTON.
Button
  ALTERNATE_STYLE_NAME_BACK_BUTTON : String = feathers-back-button
[static] An alternate style name to use with Button to allow a theme to give it a "back button" style, perhaps with an arrow pointing backward.
Button
  ALTERNATE_STYLE_NAME_CALL_TO_ACTION_BUTTON : String = feathers-call-to-action-button
[static] An alternate style name to use with Button to allow a theme to give it a more prominent, "call-to-action" style.
Button
  ALTERNATE_STYLE_NAME_DANGER_BUTTON : String = feathers-danger-button
[static] An alternate style name to use with Button to allow a theme to give it a highly prominent, "danger" style.
Button
  ALTERNATE_STYLE_NAME_FORWARD_BUTTON : String = feathers-forward-button
[static] An alternate style name to use with Button to allow a theme to give it a "forward" button style, perhaps with an arrow pointing forward.
Button
  ALTERNATE_STYLE_NAME_QUIET_BUTTON : String = feathers-quiet-button
[static] An alternate style name to use with Button to allow a theme to give it a less prominent, "quiet" style.
Button
  DEFAULT_CHILD_NAME_LABEL : String = feathers-button-label
[static] DEPRECATED: Replaced by Button.DEFAULT_CHILD_STYLE_NAME_LABEL.
Button
  DEFAULT_CHILD_STYLE_NAME_LABEL : String = feathers-button-label
[static] The default value added to the styleNameList of the label.
Button
  HORIZONTAL_ALIGN_CENTER : String = center
[static] The icon and label will be aligned horizontally to the center of the button.
Button
  HORIZONTAL_ALIGN_LEFT : String = left
[static] The icon and label will be aligned horizontally to the left edge of the button.
Button
  HORIZONTAL_ALIGN_RIGHT : String = right
[static] The icon and label will be aligned horizontally to the right edge of the button.
Button
  ICON_POSITION_BOTTOM : String = bottom
[static] The icon will be positioned below the label.
Button
  ICON_POSITION_LEFT : String = left
[static] The icon will be positioned to the left of the label.
Button
  ICON_POSITION_LEFT_BASELINE : String = leftBaseline
[static] The icon will be positioned to the left the label, and the bottom of the icon will be aligned to the baseline of the label text.
Button
  ICON_POSITION_MANUAL : String = manual
[static] The icon will be positioned manually with no relation to the position of the label.
Button
  ICON_POSITION_RIGHT : String = right
[static] The icon will be positioned to the right of the label.
Button
  ICON_POSITION_RIGHT_BASELINE : String = rightBaseline
[static] The icon will be positioned to the right the label, and the bottom of the icon will be aligned to the baseline of the label text.
Button
  ICON_POSITION_TOP : String = top
[static] The icon will be positioned above the label.
Button
 InheritedINVALIDATION_FLAG_ALL : String = all
[static] Flag to indicate that everything is invalid and should be redrawn.
FeathersControl
 InheritedINVALIDATION_FLAG_DATA : String = data
[static] Invalidation flag to indicate that the primary data displayed by the UI control has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_FOCUS : String = focus
[static] Invalidation flag to indicate that the focus of the UI control has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_LAYOUT : String = layout
[static] Invalidation flag to indicate that the layout of the UI control has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_SCROLL : String = scroll
[static] Invalidation flag to indicate that the scroll position of the UI control has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_SELECTED : String = selected
[static] Invalidation flag to indicate that the selection of the UI control has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_SIZE : String = size
[static] Invalidation flag to indicate that the dimensions of the UI control have changed.
FeathersControl
 InheritedINVALIDATION_FLAG_SKIN : String = skin
[static] Invalidation flag to indicate that the skin of the UI control has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_STATE : String = state
[static] Invalidation flag to indicate that the state has changed.
FeathersControl
 InheritedINVALIDATION_FLAG_STYLES : String = styles
[static] Invalidation flag to indicate that the styles or visual appearance of the UI control has changed.
FeathersControl
  STATE_DISABLED : String = disabled
[static] Identifier for the button's disabled state.
Button
  STATE_DOWN : String = down
[static] Identifier for the button's down state.
Button
  STATE_HOVER : String = hover
[static] Identifier for the button's hover state.
Button
  STATE_UP : String = up
[static] Identifier for the button's up state.
Button
  VERTICAL_ALIGN_BOTTOM : String = bottom
[static] The icon and label will be aligned vertically to the bottom edge of the button.
Button
  VERTICAL_ALIGN_MIDDLE : String = middle
[static] The icon and label will be aligned vertically to the middle of the button.
Button
  VERTICAL_ALIGN_TOP : String = top
[static] The icon and label will be aligned vertically to the top edge of the button.
Button
Property Detail
currentIconproperty
protected var currentIcon:DisplayObject

The currently visible icon. The value will be null if there is no currently visible icon.

For internal use in subclasses.

currentSkinproperty 
protected var currentSkin:DisplayObject

The currently visible skin. The value will be null if there is no currently visible skin.

For internal use in subclasses.

currentStateproperty 
currentState:String

The current touch state of the button.

For internal use in subclasses.


Implementation
    protected function get currentState():String
    protected function set currentState(value:String):void
defaultIconproperty 
defaultIcon:DisplayObject

The icon used when no other icon is defined for the current state. Intended to be used when multiple states should share the same icon.

This property will be ignored if a function is passed to the stateToIconFunction property.

The following example gives the button a default icon to use for all states when no specific icon is available:

         button.defaultIcon = new Image( texture );

The default value is null.


Implementation
    public function get defaultIcon():DisplayObject
    public function set defaultIcon(value:DisplayObject):void

See also

defaultLabelPropertiesproperty 
defaultLabelProperties:Object

An object that stores properties for the button's label text renderer when no specific properties are defined for the button's current state, and the properties will be passed down to the label text renderer when the button validates. The available properties depend on which ITextRenderer implementation is returned by labelFactory. Refer to feathers.core.ITextRenderer for a list of available text renderer implementations.

The following example gives the button default label properties to use for all states when no specific label properties are available (this example assumes that the label text renderer is a BitmapFontTextRenderer):

         button.defaultLabelProperties.textFormat = new BitmapFontTextFormat( bitmapFont );
         button.defaultLabelProperties.wordWrap = true;

The default value is null.


Implementation
    public function get defaultLabelProperties():Object
    public function set defaultLabelProperties(value:Object):void

See also

defaultSkinproperty 
defaultSkin:DisplayObject

The skin used when no other skin is defined for the current state. Intended to be used when multiple states should share the same skin.

This property will be ignored if a function is passed to the stateToSkinFunction property.

The following example gives the button a default skin to use for all states when no specific skin is available:

         button.defaultSkin = new Image( texture );

The default value is null.


Implementation
    public function get defaultSkin():DisplayObject
    public function set defaultSkin(value:DisplayObject):void

See also

disabledIconproperty 
disabledIcon:DisplayObject

The icon used for the button's disabled state. If null, then defaultIcon is used instead.

This property will be ignored if a function is passed to the stateToIconFunction property.

The following example gives the button an icon for the disabled state:

         button.disabledIcon = new Image( texture );

The default value is null.


Implementation
    public function get disabledIcon():DisplayObject
    public function set disabledIcon(value:DisplayObject):void

See also

disabledLabelPropertiesproperty 
disabledLabelProperties:Object

An object that stores properties for the button's label text renderer when the button is in the Button.STATE_DISABLED state, and the properties will be passed down to the label text renderer when the button validates. The available properties depend on which ITextRenderer implementation is returned by labelFactory. Refer to feathers.core.ITextRenderer for a list of available text renderer implementations.

The following example gives the button label properties for the disabled state:

         button.disabledLabelProperties.textFormat = new BitmapFontTextFormat( bitmapFont );

The default value is null.


Implementation
    public function get disabledLabelProperties():Object
    public function set disabledLabelProperties(value:Object):void

See also

disabledSkinproperty 
disabledSkin:DisplayObject

The skin used for the button's disabled state. If null, then defaultSkin is used instead.

This property will be ignored if a function is passed to the stateToSkinFunction property.

The following example gives the button a skin for the disabled state:

         button.disabledSkin = new Image( texture );

The default value is null.


Implementation
    public function get disabledSkin():DisplayObject
    public function set disabledSkin(value:DisplayObject):void

See also

downIconproperty 
downIcon:DisplayObject

The icon used for the button's down state. If null, then defaultIcon is used instead.

This property will be ignored if a function is passed to the stateToIconFunction property.

The following example gives the button an icon for the down state:

         button.downIcon = new Image( texture );

The default value is null.


Implementation
    public function get downIcon():DisplayObject
    public function set downIcon(value:DisplayObject):void

See also

downLabelPropertiesproperty 
downLabelProperties:Object

An object that stores properties for the button's label text renderer when the button is in the Button.STATE_DOWN state, and the properties will be passed down to the label text renderer when the button validates. The available properties depend on which ITextRenderer implementation is returned by labelFactory. Refer to feathers.core.ITextRenderer for a list of available text renderer implementations.

The following example gives the button label properties for the down state:

         button.downLabelProperties.textFormat = new BitmapFontTextFormat( bitmapFont );

The default value is null.


Implementation
    public function get downLabelProperties():Object
    public function set downLabelProperties(value:Object):void

See also

downSkinproperty 
downSkin:DisplayObject

The skin used for the button's down state. If null, then defaultSkin is used instead.

This property will be ignored if a function is passed to the stateToSkinFunction property.

The following example gives the button a skin for the down state:

         button.downSkin = new Image( texture );

The default value is null.


Implementation
    public function get downSkin():DisplayObject
    public function set downSkin(value:DisplayObject):void

See also

gapproperty 
gap:Number

The space, in pixels, between the icon and the label. Applies to either horizontal or vertical spacing, depending on the value of iconPosition.

If gap is set to Number.POSITIVE_INFINITY, the label and icon will be positioned as far apart as possible. In other words, they will be positioned at the edges of the button, adjusted for padding.

The following example creates a gap of 50 pixels between the label and the icon:

         button.label = "Click Me";
         button.defaultIcon = new Image( texture );
         button.gap = 50;

The default value is 0.


Implementation
    public function get gap():Number
    public function set gap(value:Number):void

See also

globalStyleProviderproperty 
public static var globalStyleProvider:IStyleProvider

The default IStyleProvider for all Button components.

The default value is null.

See also

hasLabelTextRendererproperty 
hasLabelTextRenderer:Boolean

Determines if the button's label text renderer is created or not. Useful for button sub-components that may not display text, like slider thumbs and tracks, or similar sub-components on scroll bars.

The following example removed the label text renderer:

         button.hasLabelTextRenderer = false;

The default value is true.


Implementation
    public function get hasLabelTextRenderer():Boolean
    public function set hasLabelTextRenderer(value:Boolean):void
horizontalAlignproperty 
horizontalAlign:String

The location where the button's content is aligned horizontally (on the x-axis).

The following example aligns the button's content to the left:

         button.horizontalAlign = Button.HORIZONTAL_ALIGN_LEFT;

The default value is Button.HORIZONTAL_ALIGN_CENTER.


Implementation
    public function get horizontalAlign():String
    public function set horizontalAlign(value:String):void

See also

hoverIconproperty 
hoverIcon:DisplayObject

The icon used for the button's hover state. If null, then defaultIcon is used instead.

This property will be ignored if a function is passed to the stateToIconFunction property.

The following example gives the button an icon for the hover state:

         button.hoverIcon = new Image( texture );

The default value is null.


Implementation
    public function get hoverIcon():DisplayObject
    public function set hoverIcon(value:DisplayObject):void

See also

hoverLabelPropertiesproperty 
hoverLabelProperties:Object

An object that stores properties for the button's label text renderer when the button is in the Button.STATE_HOVER state, and the properties will be passed down to the label text renderer when the button validates. The available properties depend on which ITextRenderer implementation is returned by labelFactory. Refer to feathers.core.ITextRenderer for a list of available text renderer implementations.

The following example gives the button label properties for the hover state:

         button.hoverLabelProperties.textFormat = new BitmapFontTextFormat( bitmapFont );

The default value is null.


Implementation
    public function get hoverLabelProperties():Object
    public function set hoverLabelProperties(value:Object):void

See also

hoverSkinproperty 
hoverSkin:DisplayObject

The skin used for the button's hover state. If null, then defaultSkin is used instead.

This property will be ignored if a function is passed to the stateToSkinFunction property.

The following example gives the button a skin for the hover state:

         button.hoverSkin = new Image( texture );

The default value is null.


Implementation
    public function get hoverSkin():DisplayObject
    public function set hoverSkin(value:DisplayObject):void

See also

iconOffsetXproperty 
iconOffsetX:Number

Offsets the x position of the icon by a certain number of pixels. This does not affect the measurement of the button. The button will measure itself as if the icon were not offset from its original position.

The following example offsets the x position of the button's icon by 20 pixels:

         button.iconOffsetX = 20;

The default value is 0.


Implementation
    public function get iconOffsetX():Number
    public function set iconOffsetX(value:Number):void

See also

iconOffsetYproperty 
iconOffsetY:Number

Offsets the y position of the icon by a certain number of pixels. This does not affect the measurement of the button. The button will measure itself as if the icon were not offset from its original position.

The following example offsets the y position of the button's icon by 20 pixels:

         button.iconOffsetY = 20;

The default value is 0.


Implementation
    public function get iconOffsetY():Number
    public function set iconOffsetY(value:Number):void

See also

iconPositionproperty 
iconPosition:String

The location of the icon, relative to the label.

The following example positions the icon to the right of the label:

         button.label = "Click Me";
         button.defaultIcon = new Image( texture );
         button.iconPosition = Button.ICON_POSITION_RIGHT;

The default value is Button.ICON_POSITION_LEFT.


Implementation
    public function get iconPosition():String
    public function set iconPosition(value:String):void

See also

isLongPressEnabledproperty 
isLongPressEnabled:Boolean

Determines if FeathersEventType.LONG_PRESS will be dispatched.

The following example enables long presses:

         button.isLongPressEnabled = true;
         button.addEventListener( FeathersEventType.LONG_PRESS, function( event:Event ):void
         {
             // long press
         });

The default value is false.


Implementation
    public function get isLongPressEnabled():Boolean
    public function set isLongPressEnabled(value:Boolean):void

See also

keepDownStateOnRollOutproperty 
public var keepDownStateOnRollOut:Boolean = false

Determines if a pressed button should remain in the down state if a touch moves outside of the button's bounds. Useful for controls like Slider and ToggleSwitch to keep a thumb in the down state while it is dragged around.

The following example ensures that the button's down state remains active when the button is pressed but the touch moves outside the button's bounds:

         button.keepDownStateOnRollOut = true;

labelproperty 
label:String

The text displayed on the button.

The following example gives the button some label text:

         button.label = "Click Me";

The default value is null.


Implementation
    public function get label():String
    public function set label(value:String):void
labelFactoryproperty 
labelFactory:Function

A function used to instantiate the button's label text renderer sub-component. By default, the button will use the global text renderer factory, FeathersControl.defaultTextRendererFactory(), to create the label text renderer. The label text renderer must be an instance of ITextRenderer. To change properties on the label text renderer, see defaultLabelProperties and the other "LabelProperties" properties for each button state.

The factory should have the following function signature:

function():ITextRenderer

The following example gives the button a custom factory for the label text renderer:

         button.labelFactory = function():ITextRenderer
         {
             return new TextFieldTextRenderer();
         }

The default value is null.


Implementation
    public function get labelFactory():Function
    public function set labelFactory(value:Function):void

See also

labelNameproperty 
labelName:String

DEPRECATED: Replaced by labelStyleName.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.


Implementation
    protected function get labelName():String
    protected function set labelName(value:String):void

See also

labelOffsetXproperty 
labelOffsetX:Number

Offsets the x position of the label by a certain number of pixels. This does not affect the measurement of the button. The button will measure itself as if the label were not offset from its original position.

The following example offsets the x position of the button's label by 20 pixels:

         button.labelOffsetX = 20;

The default value is 0.


Implementation
    public function get labelOffsetX():Number
    public function set labelOffsetX(value:Number):void

See also

labelOffsetYproperty 
labelOffsetY:Number

Offsets the y position of the label by a certain number of pixels. This does not affect the measurement of the button. The button will measure itself as if the label were not offset from its original position.

The following example offsets the y position of the button's label by 20 pixels:

         button.labelOffsetY = 20;

The default value is 0.


Implementation
    public function get labelOffsetY():Number
    public function set labelOffsetY(value:Number):void

See also

labelStyleNameproperty 
protected var labelStyleName:String = feathers-button-label

The value added to the styleNameList of the label text renderer. This variable is protected so that sub-classes can customize the label text renderer style name in their constructors instead of using the default style name defined by DEFAULT_CHILD_STYLE_NAME_LABEL.

See also

labelTextRendererproperty 
protected var labelTextRenderer:ITextRenderer

The text renderer for the button's label.

For internal use in subclasses.

See also

longPressDurationproperty 
longPressDuration:Number

The duration, in seconds, of a long press.

The following example changes the long press duration to one full second:

         button.longPressDuration = 1.0;

The default value is 0.5.


Implementation
    public function get longPressDuration():Number
    public function set longPressDuration(value:Number):void

See also

minGapproperty 
minGap:Number

If the value of the gap property is Number.POSITIVE_INFINITY, meaning that the gap will fill as much space as possible, the final calculated value will not be smaller than the value of the minGap property.

The following example ensures that the gap is never smaller than 20 pixels:

         button.gap = Number.POSITIVE_INFINITY;
         button.minGap = 20;

The default value is 0.


Implementation
    public function get minGap():Number
    public function set minGap(value:Number):void

See also

paddingproperty 
padding:Number

Quickly sets all padding properties to the same value. The padding getter always returns the value of paddingTop, but the other padding values may be different.

The following example gives the button 20 pixels of padding on all sides:

         button.padding = 20;

The default value is 0.


Implementation
    public function get padding():Number
    public function set padding(value:Number):void

See also

paddingBottomproperty 
paddingBottom:Number

The minimum space, in pixels, between the button's bottom edge and the button's content.

The following example gives the button 20 pixels of padding on the bottom edge only:

         button.paddingBottom = 20;

The default value is 0.


Implementation
    public function get paddingBottom():Number
    public function set paddingBottom(value:Number):void
paddingLeftproperty 
paddingLeft:Number

The minimum space, in pixels, between the button's left edge and the button's content.

The following example gives the button 20 pixels of padding on the left edge only:

         button.paddingLeft = 20;

The default value is 0.


Implementation
    public function get paddingLeft():Number
    public function set paddingLeft(value:Number):void
paddingRightproperty 
paddingRight:Number

The minimum space, in pixels, between the button's right edge and the button's content.

The following example gives the button 20 pixels of padding on the right edge only:

         button.paddingRight = 20;

The default value is 0.


Implementation
    public function get paddingRight():Number
    public function set paddingRight(value:Number):void
paddingTopproperty 
paddingTop:Number

The minimum space, in pixels, between the button's top edge and the button's content.

The following example gives the button 20 pixels of padding on the top edge only:

         button.paddingTop = 20;

The default value is 0.


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

The button renders at this scale in the down state.

The following example scales the button in the down state:

         button.scaleWhenDown = 0.9;

The default value is 1.


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

The button renders at this scale in the hover state.

The following example scales the button in the hover state:

         button.scaleWhenHovering = 0.9;

The default value is 1.


Implementation
    public function get scaleWhenHovering():Number
    public function set scaleWhenHovering(value:Number):void
stateNamesproperty 
stateNames:Vector.<String>  [read-only]

A list of all valid touch state names for use with currentState.

For internal use in subclasses.


Implementation
    protected function get stateNames():Vector.<String>

See also

stateToIconFunctionproperty 
stateToIconFunction:Function

Returns an icon for the current state. Can be used instead of individual icon properties for different states, like upIcon or hoverIcon, to reuse the same display object for all states. the function should simply change the display object's properties. For example, a function could reuse the the same starling.display.Image instance among all button states, and change its texture for each state.

The following function signature is expected:

function(target:Button, state:Object, oldIcon:DisplayObject = null):DisplayObject

The default value is null.


Implementation
    public function get stateToIconFunction():Function
    public function set stateToIconFunction(value:Function):void
stateToLabelPropertiesFunctionproperty 
stateToLabelPropertiesFunction:Function

Returns a text format for the current state.

The following function signature is expected:

function(target:Button, state:Object):Object

The default value is null.


Implementation
    public function get stateToLabelPropertiesFunction():Function
    public function set stateToLabelPropertiesFunction(value:Function):void
stateToSkinFunctionproperty 
stateToSkinFunction:Function

Returns a skin for the current state. Can be used instead of individual skin properties for different states, like upSkin or hoverSkin, to reuse the same display object for all states. The function should simply change the display object's properties. For example, a function could reuse the the same starling.display.Image instance among all button states, and change its texture for each state.

The following function signature is expected:

function(target:Button, state:Object, oldSkin:DisplayObject = null):DisplayObject

The default value is null.


Implementation
    public function get stateToSkinFunction():Function
    public function set stateToSkinFunction(value:Function):void
touchPointIDproperty 
protected var touchPointID:int = -1

The saved ID of the currently active touch. The value will be -1 if there is no currently active touch.

For internal use in subclasses.

upIconproperty 
upIcon:DisplayObject

The icon used for the button's up state. If null, then defaultIcon is used instead.

This property will be ignored if a function is passed to the stateToIconFunction property.

The following example gives the button an icon for the up state:

         button.upIcon = new Image( texture );

The default value is null.


Implementation
    public function get upIcon():DisplayObject
    public function set upIcon(value:DisplayObject):void

See also

upLabelPropertiesproperty 
upLabelProperties:Object

An object that stores properties for the button's label text renderer when the button is in the Button.STATE_UP state, and the properties will be passed down to the label text renderer when the button validates. The available properties depend on which ITextRenderer implementation is returned by labelFactory. Refer to feathers.core.ITextRenderer for a list of available text renderer implementations.

The following example gives the button label properties for the up state:

         button.upLabelProperties.textFormat = new BitmapFontTextFormat( bitmapFont );

The default value is null.


Implementation
    public function get upLabelProperties():Object
    public function set upLabelProperties(value:Object):void

See also

upSkinproperty 
upSkin:DisplayObject

The skin used for the button's up state. If null, then defaultSkin is used instead.

This property will be ignored if a function is passed to the stateToSkinFunction property.

The following example gives the button a skin for the up state:

         button.upSkin = new Image( texture );

The default value is null.


Implementation
    public function get upSkin():DisplayObject
    public function set upSkin(value:DisplayObject):void

See also

verticalAlignproperty 
verticalAlign:String

The location where the button's content is aligned vertically (on the y-axis).

The following example aligns the button's content to the top:

         button.verticalAlign = Button.VERTICAL_ALIGN_TOP;

The default value is Button.VERTICAL_ALIGN_MIDDLE.


Implementation
    public function get verticalAlign():String
    public function set verticalAlign(value:String):void

See also

Constructor Detail
Button()Constructor
public function Button()

Constructor.

Method Detail
autoSizeIfNeeded()method
protected function autoSizeIfNeeded():Boolean

If the component's dimensions have not been set explicitly, it will measure its content and determine an ideal size for itself. If the explicitWidth or explicitHeight member variables are set, those value will be used without additional measurement. If one is set, but not the other, the dimension with the explicit value will not be measured, but the other non-explicit dimension will still need measurement.

Calls setSizeInternal() to set up the actualWidth and actualHeight member variables used for layout.

Meant for internal use, and subclasses may override this function with a custom implementation.

Returns
Boolean
createLabel()method 
protected function createLabel():void

Creates the label text renderer sub-component and removes the old instance, if one exists.

Meant for internal use, and subclasses may override this function with a custom implementation.

See also

layoutContent()method 
protected function layoutContent():void

Positions and sizes the button's content.

For internal use in subclasses.

refreshIcon()method 
protected function refreshIcon():void

Sets the currentIcon property.

For internal use in subclasses.

refreshSkin()method 
protected function refreshSkin():void

Sets the currentSkin property.

For internal use in subclasses.

trigger()method 
protected function trigger():void

Triggers the button.

Event Detail
longPress Event
Event Object Type: starling.events.Event
Event.type property = feathers.events.FeathersEventType.LONG_PRESS

Dispatched when the button is pressed for a long time. The property isLongPressEnabled must be set to true before this event will be dispatched.

The following example enables long presses:

     button.isLongPressEnabled = true;
     button.addEventListener( FeathersEventType.LONG_PRESS, function( event:Event ):void
     {
         // long press
     });

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

The FeathersEventType.LONG_PRESS event type is used by the Feathers Button when it is pressed for a long time.

See also

triggered Event  
Event Object Type: starling.events.Event
Event.type property = starling.events.Event.TRIGGERED

Dispatched when the the user taps or clicks the button. The touch must remain within the bounds of the button on release to register as a tap or a click. If focus management is enabled, the button may also be triggered by pressing the spacebar while the button has focus.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Constant Detail
ALTERNATE_NAME_BACK_BUTTONConstant
public static const ALTERNATE_NAME_BACK_BUTTON:String = feathers-back-button

DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_BACK_BUTTON.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.

See also

ALTERNATE_NAME_CALL_TO_ACTION_BUTTONConstant 
public static const ALTERNATE_NAME_CALL_TO_ACTION_BUTTON:String = feathers-call-to-action-button

DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_CALL_TO_ACTION_BUTTON.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.

See also

ALTERNATE_NAME_DANGER_BUTTONConstant 
public static const ALTERNATE_NAME_DANGER_BUTTON:String = feathers-danger-button

DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_DANGER_BUTTON.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.

See also

ALTERNATE_NAME_FORWARD_BUTTONConstant 
public static const ALTERNATE_NAME_FORWARD_BUTTON:String = feathers-forward-button

DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_FORWARD_BUTTON.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.

See also

ALTERNATE_NAME_QUIET_BUTTONConstant 
public static const ALTERNATE_NAME_QUIET_BUTTON:String = feathers-quiet-button

DEPRECATED: Replaced by Button.ALTERNATE_STYLE_NAME_QUIET_BUTTON.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.

See also

ALTERNATE_STYLE_NAME_BACK_BUTTONConstant 
public static const ALTERNATE_STYLE_NAME_BACK_BUTTON:String = feathers-back-button

An alternate style name to use with Button to allow a theme to give it a "back button" style, perhaps with an arrow pointing backward. If a theme does not provide a style for a back button, the theme will automatically fall back to using the default button skin.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the back button style is applied to a button:

         var button:Button = new Button();
         button.styleNameList.add( Button.ALTERNATE_STYLE_NAME_BACK_BUTTON );
         this.addChild( button );

See also

ALTERNATE_STYLE_NAME_CALL_TO_ACTION_BUTTONConstant 
public static const ALTERNATE_STYLE_NAME_CALL_TO_ACTION_BUTTON:String = feathers-call-to-action-button

An alternate style name to use with Button to allow a theme to give it a more prominent, "call-to-action" style. If a theme does not provide a style for a call-to-action button, the theme will automatically fall back to using the default button style.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the call-to-action style is applied to a button:

         var button:Button = new Button();
         button.styleNameList.add( Button.ALTERNATE_STYLE_NAME_CALL_TO_ACTION_BUTTON );
         this.addChild( button );

See also

ALTERNATE_STYLE_NAME_DANGER_BUTTONConstant 
public static const ALTERNATE_STYLE_NAME_DANGER_BUTTON:String = feathers-danger-button

An alternate style name to use with Button to allow a theme to give it a highly prominent, "danger" style. An example would be a delete button or some other button that has a destructive action that cannot be undone if the button is triggered. If a theme does not provide a style for the danger button, the theme will automatically fall back to using the default button style.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the danger button style is applied to a button:

         var button:Button = new Button();
         button.styleNameList.add( Button.ALTERNATE_STYLE_NAME_DANGER_BUTTON );
         this.addChild( button );

See also

ALTERNATE_STYLE_NAME_FORWARD_BUTTONConstant 
public static const ALTERNATE_STYLE_NAME_FORWARD_BUTTON:String = feathers-forward-button

An alternate style name to use with Button to allow a theme to give it a "forward" button style, perhaps with an arrow pointing forward. If a theme does not provide a style for a forward button, the theme will automatically fall back to using the default button style.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the forward button style is applied to a button:

         var button:Button = new Button();
         button.styleNameList.add( Button.ALTERNATE_STYLE_NAME_FORWARD_BUTTON );
         this.addChild( button );

See also

ALTERNATE_STYLE_NAME_QUIET_BUTTONConstant 
public static const ALTERNATE_STYLE_NAME_QUIET_BUTTON:String = feathers-quiet-button

An alternate style name to use with Button to allow a theme to give it a less prominent, "quiet" style. If a theme does not provide a style for a quiet button, the theme will automatically fall back to using the default button style.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the quiet button style is applied to a button:

         var button:Button = new Button();
         button.styleNameList.add( Button.ALTERNATE_STYLE_NAME_QUIET_BUTTON );
         this.addChild( button );

See also

DEFAULT_CHILD_NAME_LABELConstant 
public static const DEFAULT_CHILD_NAME_LABEL:String = feathers-button-label

DEPRECATED: Replaced by Button.DEFAULT_CHILD_STYLE_NAME_LABEL.

DEPRECATION WARNING: This property is deprecated starting with Feathers 2.1. It will be removed in a future version of Feathers according to the standard Feathers deprecation policy.

See also

DEFAULT_CHILD_STYLE_NAME_LABELConstant 
public static const DEFAULT_CHILD_STYLE_NAME_LABEL:String = feathers-button-label

The default value added to the styleNameList of the label.

See also

HORIZONTAL_ALIGN_CENTERConstant 
public static const HORIZONTAL_ALIGN_CENTER:String = center

The icon and label will be aligned horizontally to the center of the button.

See also

HORIZONTAL_ALIGN_LEFTConstant 
public static const HORIZONTAL_ALIGN_LEFT:String = left

The icon and label will be aligned horizontally to the left edge of the button.

See also

HORIZONTAL_ALIGN_RIGHTConstant 
public static const HORIZONTAL_ALIGN_RIGHT:String = right

The icon and label will be aligned horizontally to the right edge of the button.

See also

ICON_POSITION_BOTTOMConstant 
public static const ICON_POSITION_BOTTOM:String = bottom

The icon will be positioned below the label.

See also

ICON_POSITION_LEFTConstant 
public static const ICON_POSITION_LEFT:String = left

The icon will be positioned to the left of the label.

See also

ICON_POSITION_LEFT_BASELINEConstant 
public static const ICON_POSITION_LEFT_BASELINE:String = leftBaseline

The icon will be positioned to the left the label, and the bottom of the icon will be aligned to the baseline of the label text.

See also

ICON_POSITION_MANUALConstant 
public static const ICON_POSITION_MANUAL:String = manual

The icon will be positioned manually with no relation to the position of the label. Use iconOffsetX and iconOffsetY to set the icon's position.

See also

ICON_POSITION_RIGHTConstant 
public static const ICON_POSITION_RIGHT:String = right

The icon will be positioned to the right of the label.

See also

ICON_POSITION_RIGHT_BASELINEConstant 
public static const ICON_POSITION_RIGHT_BASELINE:String = rightBaseline

The icon will be positioned to the right the label, and the bottom of the icon will be aligned to the baseline of the label text.

See also

ICON_POSITION_TOPConstant 
public static const ICON_POSITION_TOP:String = top

The icon will be positioned above the label.

See also

STATE_DISABLEDConstant 
public static const STATE_DISABLED:String = disabled

Identifier for the button's disabled state. Can be used for styling purposes.

See also

STATE_DOWNConstant 
public static const STATE_DOWN:String = down

Identifier for the button's down state. Can be used for styling purposes.

See also

STATE_HOVERConstant 
public static const STATE_HOVER:String = hover

Identifier for the button's hover state. Can be used for styling purposes.

See also

STATE_UPConstant 
public static const STATE_UP:String = up

Identifier for the button's up state. Can be used for styling purposes.

See also

VERTICAL_ALIGN_BOTTOMConstant 
public static const VERTICAL_ALIGN_BOTTOM:String = bottom

The icon and label will be aligned vertically to the bottom edge of the button.

See also

VERTICAL_ALIGN_MIDDLEConstant 
public static const VERTICAL_ALIGN_MIDDLE:String = middle

The icon and label will be aligned vertically to the middle of the button.

See also

VERTICAL_ALIGN_TOPConstant 
public static const VERTICAL_ALIGN_TOP:String = top

The icon and label will be aligned vertically to the top edge of the button.

See also