HypernovaDesktop Components · docs
Binarymission
WinForms › Toggle Check Button › ToggleSwitch

ToggleSwitch

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.ToggleControls

An on/off switch for settings that take effect at once – "Notifications", "Dark mode", "Sync over mobile data" – drawn as a pill-shaped track with a sliding knob and a text or image showing the current state.

public class ToggleSwitch : Control

Inherits from / implements: Control

Remarks

Use it where a check box would do, but where the choice reads better as a switch that is either on or off. Read and set the state with IsChecked, and handle IsCheckedChanged to act on it.

How it looks

The control is split into two equal halves. One half is the knob, the part that moves: it sits on the left while the switch is off and on the right while it is on. The other half shows the state, either as text (CheckedText / UnCheckedText, "ON" and "OFF" by default) or, with ShouldUseImageForCheckedState on, as an image (CheckedStateImage / UnCheckedStateImage). The corners of the control are cut away to give the pill shape, so whatever is behind the switch shows through them.

Using it

A click anywhere on the switch toggles it, and so does Enter or Space while it has the focus. The switch has no default size: give it a Control.Size – a width of about two and a half times its height looks right.

Examples

A "Send me order updates" setting on a preferences form, saved as soon as it changes.

using System;
using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.ToggleControls;

public class PreferencesForm : Form
{
    private readonly ToggleSwitch _orderUpdates = new ToggleSwitch();

    public PreferencesForm()
    {
        Text = "Preferences";

        var caption = new Label { Text = "Send me order updates", Location = new Point(16, 22), AutoSize = true };

        _orderUpdates.Location = new Point(200, 16);
        _orderUpdates.Size = new Size(90, 32);
        _orderUpdates.CheckedText = "Yes";
        _orderUpdates.UnCheckedText = "No";
        _orderUpdates.CheckedStateBackColor = Color.SeaGreen;
        _orderUpdates.GradientColor = Color.MediumSeaGreen;
        _orderUpdates.OnHoverBackColor = Color.ForestGreen;
        _orderUpdates.UnCheckedStateBackColor = Color.WhiteSmoke;
        _orderUpdates.IsChecked = true;
        _orderUpdates.IsCheckedChanged += OnOrderUpdatesChanged;

        Controls.Add(caption);
        Controls.Add(_orderUpdates);
    }

    private void OnOrderUpdatesChanged(object sender, EventArgs e)
    {
        Console.WriteLine("Order updates are now " + (_orderUpdates.IsChecked ? "on" : "off"));
    }
}

See also

Members at a glance

Constructors
ToggleSwitchInitialises a new switch in the off state, showing "OFF", with a dark cyan knob and a white state half.
Properties
BorderColorGets or sets a border colour for the switch.
CheckedStateBackColorGets or sets the colour of the knob – the moving half of the switch.
CheckedStateImageGets or sets the image shown in the state half while the switch is on.
CheckedTextGets or sets the text shown in the state half while the switch is on.
GradientColorGets or sets the colour at the top of the knob, from which a vertical gradient runs down to CheckedStateBackColor.
IsCheckedGets or sets whether the switch is on.
OnHoverBackColorGets or sets the colour the knob takes while the pointer is over it.
ShouldDrawBorderGets or sets whether the switch leaves a one-pixel frame around its interior.
ShouldUseImageForCheckedStateGets or sets whether the state half of the switch shows an image rather than text.
UnCheckedStateBackColorGets or sets the background colour of the state half – the half that shows the text or image.
UnCheckedStateImageGets or sets the image shown in the state half while the switch is off.
UnCheckedTextGets or sets the text shown in the state half while the switch is off.
Methods
OnGotFocusRaises the Control.GotFocus event and repaints the switch.
OnKeyUpRaises the Control.KeyUp event, then toggles IsChecked when the key released is Enter or Space and the switch has the focus.
OnLostFocusRaises the Control.LostFocus event and repaints the switch.
OnPaintRaises the Control.Paint event and, while ShouldDrawBorder is on, keeps the knob and state half inset inside the frame.
OnResizeRaises the Control.Resize event and reshapes the rounded outline to the new size.
OnSizeChangedRaises the Control.SizeChanged event and sizes the switch's interior to the new size.
Events
IsCheckedChangedOccurs when IsChecked is set – by a click, by Enter or Space, or from code.

Constructors

ToggleSwitch

public ToggleSwitch()

Initialises a new switch in the off state, showing "OFF", with a dark cyan knob and a white state half.

Remarks

The switch starts with an empty Control.Size; set one before showing it.

Properties

BorderColor

public Color BorderColor

Gets or sets a border colour for the switch.

Value
The default is SystemColors.WindowText.
Remarks

The value is stored but not used when the switch is painted; the frame that ShouldDrawBorder leaves takes the control's Control.BackColor.

CheckedStateBackColor

public Color CheckedStateBackColor

Gets or sets the colour of the knob – the moving half of the switch.

Value
The knob colour, at the bottom of its gradient. The default is Color.DarkCyan.
Remarks

Despite its name, the knob keeps this colour in both states; it is what tells the knob apart from the state half, whose colour is UnCheckedStateBackColor. The knob changes to OnHoverBackColor while the pointer is over it.

See also

CheckedStateImage

public Bitmap CheckedStateImage

Gets or sets the image shown in the state half while the switch is on.

Value
The image for the on state, or null for none. The default is null.
Remarks

Shown only while ShouldUseImageForCheckedState is true. The switch does not take ownership of the bitmap and does not dispose it.

See also

CheckedText

public string CheckedText

Gets or sets the text shown in the state half while the switch is on.

Value
The on-state caption. The default is "ON".
Remarks

Not shown while ShouldUseImageForCheckedState is true. A new value is shown the next time the switch is turned on; it does not replace the text of a switch that is already on.

See also

GradientColor

public Color GradientColor

Gets or sets the colour at the top of the knob, from which a vertical gradient runs down to CheckedStateBackColor.

Value
The colour the knob's gradient starts from. The default is Color.Empty, and until it is set the gradient starts from the system control colour (SystemColors.Control).
Remarks

Set it to the same colour as CheckedStateBackColor for a flat knob, or to a lighter shade of it for a gentle raised look.

See also

IsChecked

public bool IsChecked

Gets or sets whether the switch is on.

Value
true when the switch is on (knob on the right); false when it is off (knob on the left). The default is false.
Remarks

Setting it moves the knob, updates the state text or image, and raises IsCheckedChanged – every time, even when the value is unchanged.

Example
emailAlertsSwitch.IsChecked = settings.EmailAlertsEnabled;

OnHoverBackColor

public Color OnHoverBackColor

Gets or sets the colour the knob takes while the pointer is over it.

Value
The hover colour of the knob. The default is Color.Empty, which makes the knob take the switch's own Control.BackColor while hovered.
Remarks

When the pointer leaves the knob it returns to CheckedStateBackColor. The hover colour replaces the bottom of the knob's gradient; the top stays GradientColor.

ShouldDrawBorder

public bool ShouldDrawBorder

Gets or sets whether the switch leaves a one-pixel frame around its interior.

Value
true to inset the knob and state half so the switch's own Control.BackColor shows as a thin frame round them; the default is false.
Remarks

The frame is the control's background showing through, not a line drawn in BorderColor: to colour it, set Control.BackColor.

The interior is resized for the frame only when the switch's size changes, so set this before Control.Size (the Windows Forms designer does).

ShouldUseImageForCheckedState

public bool ShouldUseImageForCheckedState

Gets or sets whether the state half of the switch shows an image rather than text.

Value
true to show CheckedStateImage while on and UnCheckedStateImage while off; false to show CheckedText and UnCheckedText. The default is false.
Remarks

The image is centred in the state half at its own size and is not scaled, so supply images that fit the control's height. With no image set for the current state, the state half is left empty.

Example
wifiSwitch.CheckedStateImage = Properties.Resources.WifiOn16;
wifiSwitch.UnCheckedStateImage = Properties.Resources.WifiOff16;
wifiSwitch.ShouldUseImageForCheckedState = true;

UnCheckedStateBackColor

public Color UnCheckedStateBackColor

Gets or sets the background colour of the state half – the half that shows the text or image.

Value
The state half's background. The default is Color.White.
Remarks

Despite its name, the state half keeps this colour in both states.

See also

UnCheckedStateImage

public Bitmap UnCheckedStateImage

Gets or sets the image shown in the state half while the switch is off.

Value
The image for the off state, or null for none. The default is null.
Remarks

Shown only while ShouldUseImageForCheckedState is true. The switch does not take ownership of the bitmap and does not dispose it.

See also

UnCheckedText

public string UnCheckedText

Gets or sets the text shown in the state half while the switch is off.

Value
The off-state caption. The default is "OFF".
Remarks

Not shown while ShouldUseImageForCheckedState is true. Setting it puts the new text into the state half at once, whatever the current state – so on a switch that is already on, set UnCheckedText before IsChecked, or the off caption shows until the switch is next toggled.

See also

Methods

OnGotFocus

protected override void OnGotFocus(EventArgs e)

Raises the Control.GotFocus event and repaints the switch.

Parameters
e
The event data.

OnKeyUp

protected override void OnKeyUp(KeyEventArgs e)

Raises the Control.KeyUp event, then toggles IsChecked when the key released is Enter or Space and the switch has the focus.

Parameters
e
The key that was released.
Remarks

A derived class that overrides this should call the base implementation to keep the keyboard toggle.

OnLostFocus

protected override void OnLostFocus(EventArgs e)

Raises the Control.LostFocus event and repaints the switch.

Parameters
e
The event data.

OnPaint

protected override void OnPaint(PaintEventArgs e)

Raises the Control.Paint event and, while ShouldDrawBorder is on, keeps the knob and state half inset inside the frame.

Parameters
e
The graphics surface and clip rectangle to paint.

OnResize

protected override void OnResize(EventArgs e)

Raises the Control.Resize event and reshapes the rounded outline to the new size.

Parameters
e
The event data.

OnSizeChanged

protected override void OnSizeChanged(EventArgs e)

Raises the Control.SizeChanged event and sizes the switch's interior to the new size.

Parameters
e
The event data.

Events

IsCheckedChanged

public event EventHandler IsCheckedChanged

Occurs when IsChecked is set – by a click, by Enter or Space, or from code.

Remarks

The event is raised every time the property is set, including when it is set to the value it already has, so compare against your own saved state if you only want real changes. IsChecked already holds the new state when the event is raised.

Example
autoBackupSwitch.IsCheckedChanged += (sender, e) =>
{
    backupScheduleCombo.Enabled = autoBackupSwitch.IsChecked;
};