How to use the Feathers
Button class displays a button that may be triggered by pressing and releasing. It can display an optional label and an optional icon with a variety of layout options. Buttons have separate states for each of the different touch phases. The skin and icon can be customized for each state, and the label text renderer may display different font styles for each state too.
First, let's create a
Button control, give it a label, and add it to the display list:
If we want to know when the button is tapped or clicked, we can listen for
This event is dispatched when the touch ends and the touch was not dragged outside of the button's bounds. In other words, the button is only triggered when the touch both begins and ends over the button.
The listener function might look like this:
When the user interacts with a button, it's internal state changes. This may be used for skinning purposes, such as displaying different background skins or changing font styles. We'll look at some examples in a moment.
All buttons have the following states:
ButtonState.UPis the button's default state when the user is not interacting with it.
ButtonState.DOWNis the state when the user presses the button by touching it or clicking it with the mouse.
ButtonState.HOVERis the state when the mouse is hovering over the button. On a touchscreen, this state is not used.
ButtonState.DISABLEDis the state when the button's
isEnabledproperty has been set to
A number of styles may be customized on a button, including the font styles, the background skin, and an optional icon. For full details about which properties are available, see the
Button API reference. We'll look at a few of the most common ways of styling a button below.
The font styles of the button's label text renderer may be customized using the
Pass in a
starling.text.TextFormat object, which will work with any type of text renderer.
If the button's label should use different font styles when the button is disabled, you may set the
disabledFontStyles property too:
Finally, we can even customize the font styles for each of the button's specific states:
Using the code above, the color of the button's label will change when the button is pressed, and the state changes to
When font styles aren't available for a specific state, the button will use the default
fontStyles as a fallback. For example, we haven't provided font styles for
ButtonState.HOVER, so the default styles will be used.
Let's give our button its background skin. In the following example, we'll use an
ImageSkin, but the skin may be any Starling display object:
We can change the appearance of the button's skin when the state changes. In the next example, we provide another texture to the same
ImageSkin for the button's "down" state:
ImageSkin automatically listens for changes to the button's state and updates its appearance to match. When the user presses the button down, the
ImageSkin will display this texture instead of the default one.
We can also provide different display objects for specific states, if needed. In the next example, we have a texture for the "disabled" state that requires a different
scale9Grid than the other textures. We can create a separate
ImageSkin for this state:
Pass in skins for any state using the
If a skin is not provided for a specific state, the button will display its
defaultSkin. Similarly, when using an
ImageSkin, and a texture isn't provided for a specific state, it will display its default texture.
Let's also add an icon to the
Button. Icons may be customized for each of the button's states (just like the background skin), but let's simply use one icon. In this example, we'll pass in a
This icon will be displayed for all of the button's different states.
If we wanted to change the appearance of the icon when the button's state changes, we could use a
feathers.skins.ImageSkin with multiple textures, like we did in the example above that demonstrated how to set the button's background skin. Similarly, we could use
setIconForState() to pass in different display objects for each state.
Padding may be added on each side of the button:
If all four padding values should be the same, you may use the
padding property to quickly set them all at once:
The icon may be positioned on any side of the button's label. Let's move the icon above the label so that they are stacked vertically:
We set the
iconPosition property to
RelativePosition.TOP. We can easily position the icon to the top, right, bottom, or left of the label.
gap refers to the space, measured in pixels, between the icon and the label:
verticalAlign properties will adjust the alignment of the icon and label inside the button, allowing you to anchor them at the edges or in the center.