How to use the ToggleButton component
The ToggleButton class is a special type of button that may be selected and deselected when triggered. Similar to regular buttons, a toggle button can optionally display text, an icon, or both — with a variety of layout options. Toggle buttons have separate states for each of the different pointer phases — with additional variations when selected. The skin and icon can be customized for each state, and the text may be rendered with different font styles for each state too.
ToggleButton componentThe Basics
Start by creating a ToggleButton control, give it some text to display, and add it to the the display list.
var button = new ToggleButton();
button.text = "Click Me";
addChild(button);
A toggle button may be selected and deselected when it is triggered, or it can be changed programmatically by setting the selected property.
button.selected = true;
Add an event listener for Event.CHANGE to perform an action when the user changes the toggle button's selection.
button.addEventListener(Event.CHANGE, toggle_changeHandler);
Check for the new value of the selected property in the listener function.
function toggle_changeHandler(event:Event):Void {
var button = cast(event.currentTarget, ToggleButton);
trace("button.selected change: " + button.selected);
}
States
When the user interacts with a toggle button using the mouse, keyboard, or touchscreen, its state will change, which may affect its appearance. For instance, the toggle button's background skin, font styles, and icon may all be rendered differently in different states.
The ToggleButtonState enum defines the states available to all toggle button components.
UP(selected:Bool)is the toggle button's default state when the user is not interacting with it, and the toggle button is enabled.DOWN(selected:Bool)is the state when the user presses the toggle button with a mouse, touchscreen, or by pressingKeyboard.SPACEwhen the toggle button is focused.HOVER(selected:Bool)is the state when the mouse is hovering over the toggle button. This state is not used for touchscreens or keyboard interaction.DISABLED(selected:Bool)is the toggle button's state when itsenabledproperty has been set tofalse.
Notice that each state also defines a boolean value to indicate if the toggle button is selected or not. DOWN(true) and DOWN(false) both indicate that the toggle button is currently pressed down, but the value of true indicates that it is currently selected, while false means that it is not selected.
Styles
A number of styles may be customized on a ToggleButton component, including the font styles, the background skin, and an optional icon. Several more styles may be used to adjust the layout of the toggle button's children.
Font styles
The font styles of the toggle button's text may be customized by passing an openfl.text.TextFormat object to the textFormat property.
button.textFormat = new TextFormat("Helvetica", 20, 0x3c3c3c);
If the toggle button's text should use different font styles when the toggle button is selected, pass a TextFormat to the selectedTextFormat property.
button.selectedTextFormat = new TextFormat("Helvetica", 20, 0x9a9a9a, true);
Finally, the toggle button's text may use different font styles in a more fine-grained matter — by targeting an exact state. Use the setTextFormatForState() method to pass in a state value and a TextFormat.
button.setTextFormatForState(ToggleButtonState.DISABLED(false), new TextFormat("Helvetica", 20, 0xcc0000));
Using the code above, the color of the toggle button's text will change when the toggle button is disabled and not selected.
When font styles aren't available for a specific state, the toggle button will use the default textFormat as a fallback (preferring selectedTextFormat when selected, of course).
Background skin
Give the toggle button a background using the backgroundSkin property. The following example sets it to a RectangleSkin instance.
var skin = new RectangleSkin();
skin.border = SolidColor(1.0, 0x999999);
skin.fill = SolidColor(0xcccccc);
skin.width = 64.0;
skin.height = 32.0;
button.backgroundSkin = skin;
The border and fill properties of the RectangleSkin are used to adjust its appearance. They support a variety of values — from solid colors to gradients to bitmaps.
The button automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like the dimensions of the text and icon), so it's important to set a skin's width and height properties to appropriate values to use in this calculation.
See Skinning with common shapes for more details about how to use
RectangleSkinwith theLineStyleandFillStyleenums that change its border and fill appearance.
The appearance of the toggle button's border or fill may change when the toggle button is selected. In the next example, the same RectangleSkin displays a different fill when selected by setting the selectedFill property.
skin.selectedFill = SolidColor(0xcc9999);
Similarly, use the selectedBorder property to set the border when selected.
skin.selectedBorder = SolidColor(2.0, 0x999999);
The fill or border may be customized for an exact state too. In the next example, the same RectangleSkin displays a different border when the toggle button is down and not selected.
skin.setFillForState(ToggleButtonState.DOWN(false), SolidColor(0xaa9999));
skin.setBorderForState(ToggleButtonState.DOWN(false), SolidColor(1.0, 0x9999cc));
In the examples above, the toggle button uses the same RectangleSkin for all states, and that skin listens for changes to the toggle button's current state. Alternatively, the toggle button's selectedBackgroundSkin property and setSkinForState() method allow the toggle button to display a completely different display object when its current state changes.
var defaultSkin = new RectangleSkin();
// ... set border, fill, width, and height
button.backgroundSkin = defaultSkin;
var selectedSkin = new RectangleSkin();
// ... set border, fill, width, and height
button.selectedBackgroundSkin = selectedSkin;
var hoverSkin = new RectangleSkin();
// ... set border, fill, width, and height
button.setSkinForState(ToggleButtonState.HOVER(false), hoverSkin);
In the example above, the toggle button will display a custom skin when it is not selected and the mouse is hovering over it, the selected states will share the selectedBackgroundSkin, and all remaining states will share the default backgroundSkin.
Icon
A toggle button may display an icon with the text (or only an icon, without any text).
The following example loads an icon using its name registered with OpenFL's asset manager.
button.icon = new Bitmap(Assets.getBitmapData("myAssetName"));
Similar to the background skin, the toggle button's icon may be optionally customized for different states.
button.selectedIcon = new Bitmap(Assets.getBitmapData("anotherAssetName");
button.setIconForState(ToggleButtonState.DOWN(false), new Bitmap(Assets.getBitmapData("yetAnotherAssetName")));
This example uses a
Bitmapfor the toggle button's icon, but any type of display object may be used. Additionally, while it can be convenient to load icons with theAssetsclass, icons may come from anywhere — even by drawing them programatically.
Layout
Padding may be added on each side of the toggle button, including top, right, bottom, and left.
button.paddingTop = 5.0;
button.paddingRight = 8.0;
button.paddingBottom = 5.0;
button.paddingLeft = 8.0;
The icon may be positioned on any side of the toggle button's text. For instance, the following example moves the icon above the text, so that the icon and text are stacked vertically.
button.iconPosition = TOP;
Set the iconPosition property to any of the RelativePosition values.
The gap refers to the space, measured in pixels, between the icon and the text.
button.gap = 10.0;
The horizontalAlign and verticalAlign properties will adjust the alignment of the icon and text inside the toggle button, allowing you to anchor them at the edges or in the center.
button.horizontalAlign = CENTER;
button.verticalAlign = MIDDLE;