BeepToggle

Overview

BeepToggle is a fully themed toggle switch control that replaces traditional checkboxes with a modern on/off sliding switch. It provides smooth animated transitions, multiple visual styles, and full integration with the Beep theming system.

Built on BaseControl, BeepToggle exposes an IsOn boolean state, fires IsOnChanged and Toggled events, and supports optional text labels alongside the switch. Animation speed, thumb colors, track colors, and toggle styles can all be configured at design time or runtime.

Key Features

Visual Preview

Basic Usage

Designer (Drag & Drop)

1. Open the Visual Studio Toolbox and find BeepToggle under Beep Controls.
2. Drag it onto your form.
3. In the Properties panel, set IsOn, ToggleStyle, OnColor, and OffColor as needed.
4. Double-click the control to wire up the IsOnChanged event handler.

Code — Minimum Setup

var toggle = new BeepToggle
{
    IsOn          = false,
    ToggleStyle   = ToggleStyle.Classic,
    OnColor       = Color.FromArgb(76, 175, 80),   // green
    OffColor      = Color.FromArgb(204, 204, 204),  // grey
    ShowLabels    = true,
    OnText        = "ON",
    OffText       = "OFF",
    AnimateTransition = true,
    AnimationDuration = 200
};

toggle.IsOnChanged += (s, e) =>
{
    MessageBox.Show($"Toggle is now: {toggle.IsOn}");
};

this.Controls.Add(toggle);

Reading and Setting State at Runtime

// Read current state
bool currentState = toggle.IsOn;

// Programmatically change state (fires events)
toggle.IsOn = true;

Properties

Inherited properties from BaseControl (Theme, BorderStyle, BorderThickness, ShowTitle, etc.) are also available. Refer to the BaseControl API reference.

Events

Code Examples

Settings Panel Toggle (Enable/Disable Feature)

var darkModeToggle = new BeepToggle
{
    IsOn          = Properties.Settings.Default.DarkMode,
    ToggleStyle   = ToggleStyle.iOS,
    OnColor       = Color.FromArgb(33, 150, 243),
    OffColor      = Color.FromArgb(189, 189, 189),
    ShowLabels    = false,
    AnimationDuration = 150
};

darkModeToggle.Toggled += (s, e) =>
{
    Properties.Settings.Default.DarkMode = e.IsOn;
    Properties.Settings.Default.Save();
    ApplyTheme(e.IsOn ? "Dark" : "Light");
};

settingsPanel.Controls.Add(darkModeToggle);

Multiple Toggles Bound to Settings Object

void BindToggle(BeepToggle toggle, Func<bool> getter, Action<bool> setter)
{
    toggle.IsOn = getter();
    toggle.IsOnChanged += (s, e) => setter(toggle.IsOn);
}

BindToggle(tglNotifications, () => settings.EnableNotifications,
           v => settings.EnableNotifications = v);
BindToggle(tglAutoSave,      () => settings.AutoSave,
           v => settings.AutoSave = v);
BindToggle(tglDarkMode,      () => settings.DarkMode,
           v => settings.DarkMode = v);

Programmatic State Change Without Firing Events

// Temporarily suppress events when loading saved state
tglFeature.IsOnChanged -= OnFeatureToggled;
tglFeature.IsOn = savedSettings.FeatureEnabled;
tglFeature.IsOnChanged += OnFeatureToggled;

Custom Colors Per State

var alarmToggle = new BeepToggle
{
    ToggleStyle   = ToggleStyle.Classic,
    OnColor       = Color.FromArgb(244, 67, 54),  // red when armed
    OffColor      = Color.FromArgb(76, 175, 80),  // green when safe
    OnThumbColor  = Color.White,
    OffThumbColor = Color.White,
    OnText        = "ARM",
    OffText       = "SAFE",
    ShowLabels    = true
};

Theming

BeepToggle integrates with the Beep theming system via BeepThemesManager. When a theme is applied, the OnColor and OffColor are automatically mapped to the theme's primary and surface colours unless you have explicitly set them.

// Apply a named theme to the toggle
BeepThemesManager.ApplyTheme(toggle, "Ocean");

// Or apply to the whole form (propagates to all Beep controls)
BeepThemesManager.ApplyTheme(this, "Ocean");

To keep custom colors after a theme change, set UseThemeColors = false (inherited from BaseControl).

Best Practices

• Use for binary settings — BeepToggle is ideal for on/off, enabled/disabled, active/inactive choices. For multi-state options use BeepComboBox or BeepRadioButton.
• Label your intent — For accessibility and clarity set ShowLabels = true with descriptive OnText/OffText values, or place a BeepLabel next to the toggle.
• Keep animation fast — Use AnimationDuration between 100–250 ms for a responsive feel. Values above 400 ms will feel sluggish.
• Suppress events when loading — Unsubscribe from IsOnChanged before setting IsOn programmatically to avoid triggering side-effects during initialization.
• Respect disabled state — Set Enabled = false to prevent user interaction; the control will render at reduced opacity.
• Test with high-DPI — The default 60×28 size scales automatically; avoid overriding AutoSize unless you have an explicit fixed-size requirement.

Related Controls