ToggleSwitch

The ToggleSwitch is a control that is typically toggled between two states ("On" and "Off") and optionally supports a third state ("Indeterminate"").

The control is composed of a Knob element whose position indicates the state of the control, a Track which defines the bounds for the Knob, and one or more Content elements which display content associated with the current state.

Toggle States

Two states are supported by default: "On" and "Off". An optional "Indeterminate" state may also be enabled by setting the IsThreeState property to true.

The current state is defined by the IsChecked property. The type is a Nullable<Boolean> where the following defines which states are represented by each value:

To change the current state, set the IsChecked property to the desired value. Handle the Checked event to respond to changes in state.

Animation

The ToggleSwitch has several animations which are applied to elements of the control to improve the visualization. When the current state changes, the Knob element will move smoothly to the new position while transitioning the state-based System.Windows.Media.Brush properties for the Track and Knob. Changes in the Knob element size are also animated and can be observed when moving the pointer over the control.

Animations are automatically disabled, as appropriate, based on system settings. To manually turn off animations, set the IsAnimationEnabled property to false.

Knob Shadow

While not enabled by default, the ToggleSwitch uses ShadowChrome to support a drop shadow for the Knob element with the following important members:

The following example demonstrates adding a shadow:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:ToggleSwitch IsKnobShadowEnabled="True" KnobShadowElevation="2" />

Customize Layout

Several options are available to customize the layout of the control.

Orientation

The Orientation can be set to Horizontal (default) or Vertical.

When set to Horizontal, the switch moves from left ("Off") to right ("On"). Labels for current state are commonly displayed to the left and/or right of the switch, based on ContentPlacement.

When set to Vertical, the switch moves from bottom ("Off") to top ("On"). Labels for current state are commonly displayed above and/or below the switch, based on ContentPlacement.

Content Placement

The current state of the switch is typically complemented by a label on one side whose value corresponds to the state. Use the ContentPlacement property to control the position of the content or hide it completely. The following values are available:

Customize Appearance

Several options are available to customize the appearance of the control.

Understanding Extent and Ascent

Instead of Width and Height, the ToggleSwitch control uses Extent- and Ascent-related properties which work for any Orientation. The Extent-related properties are associated with the primary axis of the control (e.g., x-axis for Horizontal orientation, and y-axis for Vertical orientation). The Ascent-related properties are associated with the axis which is perpendicular to the primary axis (e.g., y-axis for Horizontal orientation, and x-axis for Vertical orientation).

For Horizontal orientation, the primary axis is the x-axis (left-to-right):

• Extent = Width
• Ascent = Height

For Vertical orientation, the primary axis is the y-axis (bottom-to-top):

• Extent = Height
• Ascent = Width

By using these Extent- and Ascent-related properties instead of Width and Height, values can be assigned which will be appropriate for the control at either orientation.

Track and Knob Size

Use the TrackExtent and TrackAscent properties to define the size of the Track element.

Use the KnobExtent and KnobAscent properties to define the size of the Knob element.

The following example for a horizontal ToggleSwitch demonstrates how to set the Knob element to a custom 30x30 size which grows to 32x32 on mouse over and then 34x32 when pressed:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:ToggleSwitch Orientation="Horizontal">
	<shared:ToggleSwitch.Style>
		<Style TargetType="shared:ToggleSwitch">
			<Setter Property="KnobExtent" Value="30" /><!-- Width (for Horizontal) -->
			<Setter Property="KnobAscent" Value="30" /><!-- Height (for Horizontal) -->
			<Setter Property="MaxKnobExtent" Value="34" />
			<Setter Property="MaxKnobAcent" Value="32" />
			<Style.Triggers>
				<MultiTrigger>
					<MultiTrigger.Conditions>
						<Condition Property="IsMouseOver" Value="True" />
						<Condition Property="IsPressed" Value="False" />
					</MultiTrigger.Conditions>
					<Setter Property="KnobExtent" Value="32" /><!-- Width (for Horizontal) -->
					<Setter Property="KnobAscent" Value="32" /><!-- Height (for Horizontal) -->
				</MultiTrigger>
				<Trigger Property="IsPressed" Value="True">
					<Setter Property="KnobExtent" Value="34" /><!-- Width (for Horizontal) -->
					<Setter Property="KnobAscent" Value="32" /><!-- Height (for Horizontal) -->
				</Trigger>
			</Style.Triggers>
		</Style>
	</shared:ToggleSwitch.Style>
</shared:ToggleSwitch>

Brushes

The Knob and Track elements have several System.Windows.Media.Brush properties available to customize the appearance of each element. These properties are defined with explicit values corresponding to "Off", "On", and "Indeterminate" state to simplify state-specific appearance without the need for defining an explicit Style.

For example, use the OffTrackBackground and OffKnobBackground properties to customize the Track and Knob elements when in the "Off" state.

Customize Content

The OffContent, OnContent, and IndeterminateContent properties are available to customize the content displayed for each state.

By default, each content property is initialized to a localizable String resource value. The following resources are configured:

This code shows how to set custom values for string resources.

ActiproSoftware.Products.Shared.SR.SetCustomString(ActiproSoftware.Products.Shared.SRName.UIToggleSwitchOffText.ToString(), "No");
ActiproSoftware.Products.Shared.SR.SetCustomString(ActiproSoftware.Products.Shared.SRName.UIToggleSwitchOnText.ToString(), "Yes");

See the Customizing String Resources topic for additional details.

Theme Assets

See the Theme Reusable Assets topic for more details on using and customizing theme assets. The following reusable assets are used by ToggleSwitch: