Returns the text baseline measurement, in pixels.

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

For internal use in subclasses.

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.

See also

The default IStyleProvider for all Button components.

The default value is null.

See also

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.

See also

The text displayed on the button.

The following example gives the button some label text:

button.label = "Click Me";

The default value is null.

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.

See also

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.

To customize the label text renderer style name without subclassing, see customLabelStyleName.

See also

The text renderer for the button's label.

For internal use in subclasses.

See also

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.

See also

The number of text lines displayed by the button. The component may contain multiple text lines if the text contains line breaks or if the wordWrap property is enabled.

See also

Constructor.

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

Gets the font styles to be used to display the button's text when the button's currentState property matches the specified state value.

If font styles are not defined for a specific state, returns null.

Parameters

See also

Gets the icon to be used by the button when the button's currentState property matches the specified state value.

If a icon is not defined for a specific state, returns null.

Parameters

See also

Gets the scale to be used by the button when the button's currentState property matches the specified state value.

If a scale is not defined for a specific state, returns NaN.

Parameters

See also

Positions and sizes the button's content.

For internal use in subclasses.

Sets the currentIcon property.

For internal use in subclasses.

Sets the font styles to be used to display the button's text when the button's currentState property matches the specified state value.

If font styles are not defined for a specific state, the value of the fontStyles property will be used instead.

Note: if the text renderer has been customized with advanced font formatting, it may override the values specified with setFontStylesForState() and properties like fontStyles and disabledFontStyles.

Parameters

See also

Sets the icon to be used by the button when the button's currentState property matches the specified state value.

If an icon is not defined for a specific state, the value of the defaultIcon property will be used instead.

Parameters

See also

Sets the scale to be used by the button when the button's currentState property matches the specified state value.

If an icon is not defined for a specific state, the value of the defaultIcon property will be used instead.

Parameters

See also

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:

See also

Determines if the text wraps to the next line when it reaches the width (or max width) of the component.

In the following example, the button's text is wrapped:

button.wordWrap = true;

The default value is false.

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 = VerticalAlign.TOP;

Note: The VerticalAlign.JUSTIFY constant is not supported.

The default value is feathers.layout.VerticalAlign.MIDDLE.

See also

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 );

Alternatively, you may use setIconForState() with ButtonState.UP to set the same icon:

var icon:Image = new Image( texture );
button.setIconForState( ButtonState.UP, icon );

The default value is null.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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 = RelativePosition.RIGHT;

The default value is feathers.layout.RelativePosition.LEFT.

See also

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.

See also

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.

See also

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 );

Alternatively, you may use setIconForState() with ButtonState.HOVER to set the same icon:

var icon:Image = new Image( texture );
button.setIconForState( ButtonState.HOVER, icon );

The default value is null.

See also

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 = HorizontalAlign.LEFT;

Note: The HorizontalAlign.JUSTIFY constant is not supported.

The default value is feathers.layout.HorizontalAlign.CENTER.

See also

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.

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.

See also

The font styles used to display the button's text.

In the following example, the font styles are customized:

button.fontStyles = new TextFormat( "Helvetica", 20, 0xcc0000 );

Note: The starling.text.TextFormat class defines a number of common font styles, but the text renderer being used may support a larger number of ways to be customized. Use the labelFactory to set more advanced styles.

The default value is null.

See also

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 );

Alternatively, you may use setIconForState() with ButtonState.DOWN to set the same icon:

var icon:Image = new Image( texture );
button.setIconForState( ButtonState.DOWN, icon );

The default value is null.

See also

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 );

Alternatively, you may use setIconForState() with ButtonState.DISABLED to set the same icon:

var icon:Image = new Image( texture );
button.setIconForState( ButtonState.DISABLED, icon );

The default value is null.

See also

The font styles used to display the button's text when the button is disabled.

In the following example, the disabled font styles are customized:

button.disabledFontStyles = new TextFormat( "Helvetica", 20, 0x999999 );

Alternatively, you may use setFontStylesForState() with ButtonState.DISABLED to set the same font styles:

var fontStyles:TextFormat = new TextFormat( "Helvetica", 20, 0x999999 );
button.setFontStylesForState( ButtonState.DISABLED, fontStyles );

Note: The starling.text.TextFormat class defines a number of common font styles, but the text renderer being used may support a larger number of ways to be customized. Use the labelFactory to set more advanced styles on the text renderer.

The default value is null.

See also

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.

See also

A style name to add to the button's label text renderer sub-component. Typically used by a theme to provide different styles to different buttons.

In the following example, a custom label style name is passed to the button:

button.customLabelStyleName = "my-custom-button-label";

In your theme, you can target this sub-component style name to provide different styles than the default:

getStyleProviderForClass( BitmapFontTextRenderer ).setFunctionForStyleName( "my-custom-button-label", setCustomButtonLabelStyles );

The default value is null.

See also

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

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

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

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

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

The default value added to the styleNameList of the label text renderer.

Note: the label text renderer is not a feathers.controls.Label. It is an instance of one of the ITextRenderer implementations.

See also