WinForms › Toggle Check Button › Win8ToggleSwitch

Win8ToggleSwitch

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

A flat, square-cornered on/off switch in the Windows 8 style: a framed track with a gradient interior and a solid bar – the stick – that sits at the left end while off and at the right end while on.

public class Win8ToggleSwitch : Control

Inherits from / implements: Control

Remarks

Use it for settings that take effect at once, where a check box would do but a switch reads better – "Auto-save", "Show completed tasks", "Use proxy server". Read and set the state with IsChecked and handle Toggled to act on it.

The parts and their colours

Every part has one colour for the on state and one for the off state, so the switch can say which state it is in by colour as well as by the stick's position. The two sets start out identical; set the on-state colours to something brighter to make the difference plain.

Part	On / off colour properties
Outer border – the frame round the track	`OuterBorderColor` / `OuterBorderColorUnchecked`, `OuterBorderThickness` wide
Inner border – the line inside the frame	`InnerBorderColor` / `InnerBorderColorUnchecked`, `InnerBorderThickness` wide
Track interior – a top-to-bottom gradient	`BackgroundStartColor` and `BackgroundEndColor` / `BackgroundStartColorUnchecked` and `BackgroundEndColorUnchecked`
Stick – the full-height bar that moves	`ToggleStickColor` / `ToggleStickColorUnchecked`, `ToggleSwitchStickWidth` wide

ShouldDrawGapBetweenSwitchStickAndTrack cuts a slot between the stick and the track, and ShouldDrawFocusRectangleWhenFocused shows a dotted rectangle while the switch has the keyboard focus. All widths are in logical pixels and are scaled for the display.

Using it

A click 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, such as 60 by 24.

Examples

An "Auto-save" switch on a document editor's toolbar panel, green while on and grey while off.

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

public class EditorOptionsPanel : Panel
{
    private readonly Win8ToggleSwitch _autoSave = new Win8ToggleSwitch();

    public EditorOptionsPanel()
    {
        Size = new Size(260, 48);

        var caption = new Label { Text = "Auto-save", Location = new Point(12, 16), AutoSize = true };

        _autoSave.Location = new Point(120, 12);
        _autoSave.Size = new Size(60, 24);

        // On: a green stick on a light green track.
        _autoSave.ToggleStickColor = Color.SeaGreen;
        _autoSave.BackgroundStartColor = Color.Honeydew;
        _autoSave.BackgroundEndColor = Color.LightGreen;

        // Off: a grey stick on a grey track.
        _autoSave.ToggleStickColorUnchecked = Color.DimGray;
        _autoSave.BackgroundStartColorUnchecked = Color.White;
        _autoSave.BackgroundEndColorUnchecked = Color.Gainsboro;

        _autoSave.ShouldDrawFocusRectangleWhenFocused = true;
        _autoSave.Toggled += (sender, e) => Console.WriteLine("Auto-save " + (_autoSave.IsChecked ? "on" : "off"));

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

Members at a glance

Constructors
`Win8ToggleSwitch`	Initialises a new switch in the off state, with an orange-red stick, a light grey frame and a white to dark grey track.
Properties
`BackgroundEndColor`	Gets or sets the colour of the bottom of the track's gradient interior while the switch is on.
`BackgroundEndColorUnchecked`	Gets or sets the colour of the bottom of the track's gradient interior while the switch is off.
`BackgroundStartColor`	Gets or sets the colour of the top of the track's gradient interior while the switch is on.
`BackgroundStartColorUnchecked`	Gets or sets the colour of the top of the track's gradient interior while the switch is off.
`InnerBorderColor`	Gets or sets the colour of the line just inside the outer frame while the switch is on.
`InnerBorderColorUnchecked`	Gets or sets the colour of the line just inside the outer frame while the switch is off.
`InnerBorderThickness`	Gets or sets the width of the line drawn just inside the outer frame.
`IsChecked`	Gets or sets whether the switch is on.
`OuterBorderColor`	Gets or sets the colour of the outer frame round the track while the switch is on.
`OuterBorderColorUnchecked`	Gets or sets the colour of the outer frame round the track while the switch is off.
`OuterBorderThickness`	Gets or sets the width of the outer frame round the track.
`ShouldDrawFocusRectangleWhenFocused`	Gets or sets whether a dotted focus rectangle is drawn round the switch while it has the keyboard focus.
`ShouldDrawGapBetweenSwitchStickAndTrack`	Gets or sets whether a slot is cut between the stick and the track.
`SwitchStickControlGapWidth`	Gets or sets the width of the slot between the stick and the track.
`ToggleStickColor`	Gets or sets the colour of the stick while the switch is on.
`ToggleStickColorUnchecked`	Gets or sets the colour of the stick while the switch is off.
`ToggleSwitchStickWidth`	Gets or sets the width of the stick – the full-height bar that marks the switch's state.
Methods
`Dispose`	Releases the switch's drawing surface and the resources of the underlying control.
`OnGotFocus`	Raises the `Control.GotFocus` event and repaints the switch.
`OnHandleCreated`	Raises the `Control.HandleCreated` event and prepares the switch's drawing surface.
`OnKeyDown`	Raises the `Control.KeyDown` event, and repaints when the focus arrives by the Tab key so the focus rectangle appears.
`OnKeyUp`	Raises the `Control.KeyUp` event, then toggles `IsChecked` when the key released is Enter or Space and the switch has the focus.
`OnLostFocus`	Raises the `Control.LostFocus` event and repaints the switch.
`OnMouseEnter`	Raises the `Control.MouseEnter` event and repaints the switch.
`OnMouseLeave`	Raises the `Control.MouseLeave` event and repaints the switch.
`OnMouseUp`	Raises the `Control.MouseUp` event, then toggles `IsChecked`.
`OnPaint`	Raises the `Control.Paint` event, then draws the frame, track, stick and focus rectangle in the colours for the current state.
`OnParentChanged`	Raises the `Control.ParentChanged` event and prepares the switch's drawing surface.
Events
`Toggled`	Occurs when `IsChecked` is set – by a click, by Enter or Space, or from code.

Constructors

Win8ToggleSwitch

public Win8ToggleSwitch()

Initialises a new switch in the off state, with an orange-red stick, a light grey frame and a white to dark grey track.

Remarks

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

Properties

BackgroundEndColor

public Color BackgroundEndColor

Gets or sets the colour of the bottom of the track's gradient interior while the switch is on.

Value: The default is Color.DarkGray.

BackgroundEndColorUnchecked

public Color BackgroundEndColorUnchecked

Gets or sets the colour of the bottom of the track's gradient interior while the switch is off.

Value: The default is Color.DarkGray.

BackgroundStartColor

public Color BackgroundStartColor

Gets or sets the colour of the top of the track's gradient interior while the switch is on.

Value: The default is Color.White.

BackgroundStartColorUnchecked

public Color BackgroundStartColorUnchecked

Gets or sets the colour of the top of the track's gradient interior while the switch is off.

Value: The default is Color.White.

InnerBorderColor

public Color InnerBorderColor

Gets or sets the colour of the line just inside the outer frame while the switch is on.

Value: The default is Color.Black.

InnerBorderColorUnchecked

public Color InnerBorderColorUnchecked

Gets or sets the colour of the line just inside the outer frame while the switch is off.

Value: The default is Color.Black.

InnerBorderThickness

public int InnerBorderThickness

Gets or sets the width of the line drawn just inside the outer frame.

Value: The line width in logical pixels. The default is 1.

IsChecked

public bool IsChecked

Gets or sets whether the switch is on.

Value: true when the switch is on (stick at the right end); false when it is off (stick at the left end). The default is false.

Remarks

Setting it raises Toggled – every time, even when the value is unchanged – and repaints the switch straight away in the colours for the new state.

OuterBorderColor

public Color OuterBorderColor

Gets or sets the colour of the outer frame round the track while the switch is on.

Value: The default is Color.LightGray.

OuterBorderColorUnchecked

public Color OuterBorderColorUnchecked

Gets or sets the colour of the outer frame round the track while the switch is off.

Value: The default is Color.LightGray.

OuterBorderThickness

public int OuterBorderThickness

Gets or sets the width of the outer frame round the track.

Value: The frame width in logical pixels. The default is 3.

Remarks

The frame is drawn in OuterBorderColor or OuterBorderColorUnchecked. Borders too thick for the switch's size leave no room for the track, and the switch is then not painted at all – keep the two border widths well under half the switch's height.

ShouldDrawFocusRectangleWhenFocused

public bool ShouldDrawFocusRectangleWhenFocused

Gets or sets whether a dotted focus rectangle is drawn round the switch while it has the keyboard focus.

Value: true to show the focus rectangle; the default is false.

Remarks

Turn it on where people move through the form with the Tab key, so they can see which switch Enter or Space will toggle.

ShouldDrawGapBetweenSwitchStickAndTrack

public bool ShouldDrawGapBetweenSwitchStickAndTrack

Gets or sets whether a slot is cut between the stick and the track.

Value: true to draw the slot, SwitchStickControlGapWidth wide; the default is false.

Remarks

The slot is painted in the background colour of the switch's parent (or the switch's own Control.BackColor before it has a parent), so it looks like a gap through which the form shows. It has no visible width until SwitchStickControlGapWidth is set above zero.

SwitchStickControlGapWidth

public int SwitchStickControlGapWidth

Gets or sets the width of the slot between the stick and the track.

Value: The slot width in logical pixels. The default is 0.

Remarks

Drawn only while ShouldDrawGapBetweenSwitchStickAndTrack is true.

A value below zero, or above half the switch's current width, is ignored and the old value kept. Because the test uses the width at the moment the value is set, set Control.Size first – on a switch that has not been sized yet, every value above zero is ignored.

Example

darkModeSwitch.Size = new Size(60, 24);
darkModeSwitch.SwitchStickControlGapWidth = 2;
darkModeSwitch.ShouldDrawGapBetweenSwitchStickAndTrack = true;

ToggleStickColor

public Color ToggleStickColor

Gets or sets the colour of the stick while the switch is on.

Value: The default is Color.OrangeRed.

ToggleStickColorUnchecked

public Color ToggleStickColorUnchecked

Gets or sets the colour of the stick while the switch is off.

Value: The default is Color.OrangeRed.

ToggleSwitchStickWidth

public int ToggleSwitchStickWidth

Gets or sets the width of the stick – the full-height bar that marks the switch's state.

Value: The stick width in logical pixels. The default is 13.

Methods

Dispose

protected override void Dispose(bool disposing)

Releases the switch's drawing surface and the resources of the underlying control.

Parameters

disposing: true when called from Dispose(); false when called from a finaliser.

OnGotFocus

protected override void OnGotFocus(EventArgs e)

Raises the Control.GotFocus event and repaints the switch.

Parameters

e: The event data.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Raises the Control.HandleCreated event and prepares the switch's drawing surface.

Parameters

e: The event data.

OnKeyDown

protected override void OnKeyDown(KeyEventArgs e)

Raises the Control.KeyDown event, and repaints when the focus arrives by the Tab key so the focus rectangle appears.

Parameters

e: The key that was pressed.

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.

OnLostFocus

protected override void OnLostFocus(EventArgs e)

Raises the Control.LostFocus event and repaints the switch.

Parameters

e: The event data.

OnMouseEnter

protected override void OnMouseEnter(EventArgs e)

Raises the Control.MouseEnter event and repaints the switch.

Parameters

e: The event data.

OnMouseLeave

protected override void OnMouseLeave(EventArgs e)

Raises the Control.MouseLeave event and repaints the switch.

Parameters

e: The event data.

OnMouseUp

protected override void OnMouseUp(MouseEventArgs e)

Raises the Control.MouseUp event, then toggles IsChecked.

Parameters

e: The mouse button and position.

Remarks

Any mouse button toggles the switch, the right button included.

OnPaint

protected override void OnPaint(PaintEventArgs pe)

Raises the Control.Paint event, then draws the frame, track, stick and focus rectangle in the colours for the current state.

Parameters

pe: The graphics surface and clip rectangle to paint.

OnParentChanged

protected override void OnParentChanged(EventArgs e)

Raises the Control.ParentChanged event and prepares the switch's drawing surface.

Parameters

e: The event data.

Events

Toggled

public event EventHandler Toggled

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, and before the switch is repainted. IsChecked already holds the new state.

Example

proxySwitch.Toggled += (sender, e) =>
{
    proxyAddressTextBox.Enabled = proxySwitch.IsChecked;
};

Win8ToggleSwitch

Remarks

The parts and their colours

Using it

Examples

See also

Members at a glance

Constructors

Win8ToggleSwitch

Remarks

Properties

BackgroundEndColor

See also

BackgroundEndColorUnchecked

See also

BackgroundStartColor

See also

BackgroundStartColorUnchecked

See also

InnerBorderColor

See also

InnerBorderColorUnchecked

See also

InnerBorderThickness

See also

IsChecked

Remarks

OuterBorderColor

See also

OuterBorderColorUnchecked

See also

OuterBorderThickness

Remarks

See also

ShouldDrawFocusRectangleWhenFocused

Remarks

ShouldDrawGapBetweenSwitchStickAndTrack

Remarks

SwitchStickControlGapWidth

Remarks

Example

ToggleStickColor

See also

ToggleStickColorUnchecked

See also

ToggleSwitchStickWidth

Methods

Dispose

Parameters

OnGotFocus

Parameters

OnHandleCreated

Parameters

OnKeyDown

Parameters

OnKeyUp

Parameters

OnLostFocus

Parameters

OnMouseEnter

Parameters

OnMouseLeave

Parameters

OnMouseUp

Parameters

Remarks

OnPaint

Parameters

OnParentChanged

Parameters

Events

Toggled

Remarks

Example