How to use the ToggleSwitch component

The ToggleSwitch class appears somewhat like a light switch, and it may be toggled between selected and deselected states. The thumb may be dragged from side to side, or it may be tapped to change selection. A toggle switch is often used as an alternative to a Check control — especially on devices with touchscreens.

Live preview of the ToggleSwitch component

The Basics

First, let's create an ToggleSwitch control, update its selection, and add it to the the display list.

var toggle = new ToggleSwitch();
toggle.selected = true;
addChild(toggle);

The selected property indicates if the toggle switch is on (true) or off (false).

Add an event listener for Event.CHANGE to perform an action when the selected property changes.

toggle.addEventListener(Event.CHANGE, toggleSwitch_changeHandler);

Listeners for Event.CHANGE have the following function signature.

function toggleSwitch_changeHandler(event:Event):Void {
    var toggle = cast(event.currentTarget, ToggleSwitch);
    trace("toggle.selected change: " + toggle.selected);
}

Styles

The skins for a ToggleSwitch component are divided into two main parts: the thumb and the track. The track may either fill the full length of the toggle switch, or it may be optionally divided in half — meeting at the center of the toggle switch's thumb.

Thumb

Style a toggle switch's thumb using the thumbSkin property. The following example sets it to a CircleSkin instance.

var thumbSkin = new CircleSkin();
thumbSkin.border = SolidColor(1.0, 0x999999);
thumbSkin.fill = SolidColor(0xcccccc);
thumbSkin.width = 32.0;
thumbSkin.height = 32.0;
toggle.thumbSkin = thumbSkin;

The border and fill properties of the CircleSkin are used to adjust its appearance. They support a variety of values — from solid colors to gradients to bitmaps.

The toggle switch automatically calculates its preferred size based on the initial dimensions of its skins, 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 CircleSkin (and RectangleSkin, which we'll use for the track below) with the LineStyle and FillStyle enums that change its border and fill appearance.

Track

Style a toggle switch's track using the trackSkin property. The following example sets it to a RectangleSkin instance.

var trackSkin = new RectangleSkin();
trackSkin.border = SolidColor(1.0, 0x999999);
trackSkin.fill = SolidColor(0xcccccc);
trackSkin.width = 64.0;
trackSkin.height = 32.0;
toggle.trackSkin = trackSkin;

By default, the trackSkin will fill the entire width of the toggle switch.

To give the track different a appearance on each side of the thumb, set the optional secondaryTrackSkin.

var trackSkin = new RectangleSkin();
trackSkin.border = SolidColor(1.0, 0x999999);
trackSkin.fill = SolidColor(0xccccff);
trackSkin.width = 48.0;
trackSkin.height = 32.0;
toggle.trackSkin = trackSkin;

var secondaryTrackSkin = new RectangleSkin();
secondaryTrackSkin.border = SolidColor(1.0, 0x999999);
secondaryTrackSkin.fill = SolidColor(0xcccccc);
secondaryTrackSkin.width = 48.0;
secondaryTrackSkin.height = 32.0;
toggle.secondaryTrackSkin = secondaryTrackSkin;

The trackSkin appears on the left side of the thumb, and the secondaryTrackSkin appears on the right side.