BeepCheckBox

Overview

Namespace: TheTechIdea.Beep.Winform.Controls.CheckBoxes

Assembly: TheTechIdea.Beep.Winform.Controls

Inheritance: BeepCheckBox<T> → BaseControl → System.Windows.Forms.UserControl

Implements: IBeepComponent

BeepCheckBox<T> is a generic, themable checkbox control that supports a pluggable painter system for rendering styles (Material3, Fluent2, iOS, Classic, and more). It provides three-state checking (Unchecked / Checked / Indeterminate), typed value mapping, keyboard and mouse interaction, DPI scaling, grid-mode rendering, and full data-binding through the IBeepComponent interface.

The control is implemented as a generic BeepCheckBox<T> partial class split across six files. Three concrete non-generic wrappers are provided for design-time toolbox use. The painter system delegates all visual rendering to ICheckBoxPainter implementations selected by the CheckBoxStyle enum, allowing the same control to render as a classic checkbox, a Material3 checkmark, an iOS-style animated toggle, or a Windows Fluent2 checkbox.

State and value management is handled through a layered system: legacy CheckedValue / UncheckedValue properties coexist with explicit CheckedStateValue / UncheckedStateValue / IndeterminateStateValue properties, with automatic synchronisation controlled by MapStateValuesToLegacy. The CurrentValue property always resolves to the correct typed value for the current CheckBoxState.

Key Features

• Pluggable Painter System: Rendering delegated to ICheckBoxPainter implementations (Classic, Fluent2, iOS, Material3, Minimal, Modern, Switch, Button) via CheckBoxPainterFactory.
• Generic Value Mapping: BeepCheckBox<T> maps checked/unchecked/ indeterminate states to any typed value (bool, string, int, char, custom enums).
• Three-State Support: Cycles Unchecked → Checked → Indeterminate with full value resolution per state. ToggleState() handles the cycling logic.
• Eight Visual Styles: Classic, Fluent2, iOS, Material3, Minimal, Modern, Switch, Button — each with its own painter and layout recommendations.
• State-Aware Value Resolution: Explicit CheckedStateValue, UncheckedStateValue, IndeterminateStateValue with backward-compatible MapStateValuesToLegacy bridging.
• Grid-Mode Optimisation: When GridMode=true, DrawForGrid provides a simplified, cache-friendly rendering path without painter or rounded-corner overhead.
• DPI Scaling: All layout dimensions (checkbox size, spacing, border radius, check-mark thickness) scaled through DpiScalingHelper.
• Hit-Mode Control: CheckBoxMouseHitMode — WholeControl or CheckBoxGlyph — determines where clicks trigger toggling.
• Keyboard & Accessibility: Space/Enter toggle, arrow-key navigation, mnemonics, and custom BeepCheckBoxAccessibleObject for UIA/screen readers.
• Diagnostics: BeepCheckBoxDiagnostics with DEBUG-only counters for invalidation, toggle, cache-rebuild, and painter-fetch regression testing.
• IBeepComponent Integration: SetValue, GetValue, ClearValue, HasFilterValue, ToFilter, BoundProperty.
• Image Support: Custom check-mark via ImagePath (SVG, PNG, JPG) with theme-aware SVG recolouring through BeepImage.
• Auto-Sync: SyncLayoutMetricsWithStyle and SyncControlStyleWithCheckBoxStyle auto-apply recommendations when style changes.

Concrete (Non-Generic) Types

All three are decorated with [ToolboxItem(true)], [Category("Beep Controls")], and descriptive [DisplayName] / [Description] attributes for Visual Studio toolbox integration.

For custom typed values (e.g. enums, integers), instantiate BeepCheckBox<T> directly and configure CheckedStateValue / UncheckedStateValue as needed.

Properties (35 total)

Methods

Events

All three events are invoked through OnStateChanged(previousState, checkedChanged, raiseSubmitChanges), which also calls AccessibilityNotifyClients for UIA state/name change notifications, and optionally RaiseSubmitChanges() for the form-level submit pipeline.

Theming

BeepCheckBox supports two parallel theming axes:

1. CheckBoxStyle — selects the ICheckBoxPainter and applies style-specific layout recommendations via CheckBoxStyleHelpers:
   • Classic — Windows classic appearance with square glyph and etched border
   • Fluent2 — Microsoft Fluent 2 design language with rounded animated fill
   • iOS — iOS-style with animated scale/opacity on check
   • Material3 — Material Design 3 checkmark with ink ripple (default)
   • Minimal — Minimalist line-art with no fill
   • Modern — Rounded-square with gradient fill
   • Switch — Toggle-switch appearance with sliding thumb
   • Button — Push-button style with raised/lowered states
2. BeepControlStyle (via ControlStyle) — controls BaseControl-level rendering (borders, background, shadows). When SyncControlStyleWithCheckBoxStyle is true, mapped automatically via CheckBoxStyleHelpers.GetControlStyleForCheckBox().

The CheckBoxRenderOptions struct carries theme-derived values to the painter: Theme, UseThemeColors, ControlStyle, CheckBoxStyle, CheckBoxSize, Spacing, Padding, BorderRadius, BorderWidth, CheckMarkThickness, GlyphSizeRatio, CheckIconPath, IndeterminateIconPath, TextFont, Text, HideText, TextAlignment, RightToLeft.

Layout geometry is computed by CheckBoxLayoutCalculator.Compute() and CheckBoxLayoutCalculator.ComputeGrid(). Theme colours are resolved by CheckBoxThemeHelpers for background (checked/unchecked), foreground, border, check-mark, and indeterminate fill. Fonts are resolved by CheckBoxFontHelpers.GetCheckBoxFont(). Icons default via CheckBoxIconHelpers.GetCheckIconPath() and GetIndeterminateIconPath().

Examples

Basic Usage — BeepCheckBoxBool

var checkBox = new BeepCheckBoxBool
{
    Text = "Enable feature",
    Checked = true,
    TextAlignRelativeToCheckBox = TextAlignment.Right,
    CheckBoxStyle = CheckBoxStyle.Material3,
    AutoSize = true
};
checkBox.CheckedChanged += (s, e) =>
    Console.WriteLine($"Checked: {checkBox.Checked}");

Three-State Toggle

var triCheck = new BeepCheckBoxBool
{
    Text = "Include all sub-items",
    ThreeState = true,
    CheckBoxStyle = CheckBoxStyle.iOS
};
triCheck.State = CheckBoxState.Indeterminate;

Generic with Custom Typed Values

var statusCheck = new BeepCheckBox<string>
{
    Text = "Approval Status",
    CheckedStateValue = "APPROVED",
    UncheckedStateValue = "REJECTED",
    IndeterminateStateValue = "PENDING",
    MapStateValuesToLegacy = true
};
Console.WriteLine(statusCheck.CurrentValue); // "REJECTED"
statusCheck.State = CheckBoxState.Checked;
Console.WriteLine(statusCheck.CurrentValue); // "APPROVED"

Data Binding via IBeepComponent

var checkBox = new BeepCheckBoxBool { BoundProperty = "CurrentValue" };
checkBox.SetValue(true);   // sets Checked = true
object val = checkBox.GetValue(); // returns true
var filter = checkBox.ToFilter(); // FieldName="CurrentValue", FilterValue="True", Operator="="

Hit-Mode: Glyph-Only Toggling

var checkBox = new BeepCheckBoxBool
{
    Text = "Click the box only — label won't toggle",
    MouseHitMode = CheckBoxMouseHitMode.CheckBoxGlyph
};

Custom Image as Check Mark

var imgCheck = new BeepCheckBoxBool
{
    Text = "Favourite",
    ImagePath = @"C:\icons\star.svg",
    CheckBoxStyle = CheckBoxStyle.Modern
};
// SVG is loaded, theme-coloured, and rendered as the checked glyph

Grid-Mode Rendering (for BeepGridPro cells)

// BeepGridPro sets GridMode=true for hosted cells automatically
// No user code needed — DrawForGrid handles simplified rendering
// Key: flat glyph, no rounded corners, no shadows, cached brush/pen reuse

BeepCheckBoxString for Data-Backed Forms

var ynCheck = new BeepCheckBoxString
{
    Text = "Export to CSV",
    BoundProperty = "CurrentValue"
};
ynCheck.SetValue("YES"); // Checked = true
ynCheck.SetValue("NO");  // Checked = false

Architecture

Painter Details

Each ICheckBoxPainter implementation receives a CheckBoxItemState (IsChecked, IsIndeterminate, IsHovered, IsPressed, IsFocused, IsDisabled) and a CheckBoxRenderOptions (all theme-derived visual parameters). The painter's PaintCheckBox method draws the glyph, and PaintText draws the label.

Painters are stateless — they hold no GDI resources and are allocated per CheckBoxStyle change. The factory (CheckBoxPainterFactory.GetPainter) returns the cached painter instance for the requested style, recording a diagnostic PainterFetch on each call.

Grid-Mode Rendering

When GridMode = true (set by BeepGridPro when hosting the checkbox in a cell), the Draw method delegates to DrawForGrid which provides a deliberately simplified rendering path:

• No painter system — flat rectangles, simple lines
• No rounded corners, shadows, or animations
• Brush and pen caching for repeated colour access
• DPI-scaled glyph size clamped to min(16, CheckBoxSize)
• EndEllipsis text with RTL support
• Colours resolved via CheckBoxThemeHelpers with disabled-state luminance shift

This keeps grid-cell overhead minimal when hundreds of cells may share the same control instance.