BeepNumericUpDown

Overview

Namespace: TheTechIdea.Beep.Winform.Controls.Numerics

Assembly: TheTechIdea.Beep.Winform.Controls

Inheritance: BeepNumericUpDown → BaseControl → UserControl

Implements: IBeepComponent

BeepNumericUpDown is a feature-rich numeric input control for business applications. It combines a themable spin-button interface with 20+ NumericStyle presets, four display modes (Standard, Percentage, Currency, ProgressValue), 30+ input mask presets (phone, SSN, credit card, ISBN, GPS coordinates, etc.), and a comprehensive multi-stage validation pipeline with 13 dedicated events.

It uses a pluggable painter system for layout and rendering, and supports both inline TextBox editing and mouse/keyboard increment/decrement with auto-repeat acceleration. The control is split across five partial class files for maintainability.

Key Features

• 20+ Numeric Styles: Standard, CompactStepper, Slider, Currency, Percentage, Phone, Decimal, Integer, Rating, Progress, Time, Scientific, Dial, VerticalStepper, Calculator, Temperature, Inline, TouchOptimized, Display, Chip.
• Pluggable Painter System: INumericUpDownPainter implementations (StandardNumericPainter, CompactStepperPainter, CurrencyPainter, PhoneNumberPainter, InlineStepperPainter) with hit-area management and layout.
• Four Display Modes: Standard, Percentage (auto %), Currency (auto $+decimals), CustomUnit (prefix+suffix+unit), ProgressValue (% with min/max/increment presets).
• 30+ Mask Presets: PhoneUS, PhoneInternational, SSN, CreditCard, ZipCode/Plus4, Currency, Percentage, Time24/12Hour, Date formats, IPAddress, MACAddress, Decimal2/4Places, IntegerWithCommas, AccountNumber, RoutingNumber, EIN, ISBN10/13, ProductCode, Latitude, Longitude, WeightKg/Lbs, TemperatureC/F, DistanceKm/Miles, FileSizeMB/GB, Scientific, Hex, Binary, Custom.
• 13-Event Validation Pipeline: ValueValidating (basic + extended), ValueValidated, RangeExceeded, InvalidInput, FormatValidation, StepValidationFailed, MinimumReached, MaximumReached, plus per-char and per-value comprehensive helpers.
• Keyboard Navigation: Arrow Up/Down, PageUp/PageDown (10×step), Home/End (min/max), Enter/Escape commit/cancel, mouse wheel, configurable arrow-key interception.
• Auto-Repeat Acceleration: 500ms initial delay, 50ms repeat, accelerates after 5 repeats. Direction tracked via _repeatIncrementDirection.
• Inline TextBox Editing: Transparent overlay for direct typing with SelectAllOnFocus, invalid-input highlighting (red background), and prefix/suffix stripping on commit.
• Percentage Auto-Calc: SetPercentageValue(part, total), GetActualValue() computes from TotalValue when AutoCalculateFromTotal is true.
• Value Wrapping: WrapValues wraps max→min and min→max on increment/decrement.
• Accessibility: AccessibleRole=SpinButton, configurable AccessibleName/Description.

Display Modes (NumericUpDownDisplayMode)

Numeric Styles (NumericStyle Enum — 22 values)

Mask Presets (NumericMaskPreset — 37 values)

Use Custom with CustomMask for user-defined patterns (e.g. "####-####").

Properties (29 total)

Methods

Events (13 total)

Validation Pipeline

The Value setter executes the following validation sequence:

1. Range Clamp: ValidateValueRange(newValue) — clamps or wraps value to [Min, Max].
2. Equality Check: Skip if old == new.
3. Basic Validation: ValueValidating?.Invoke(this, args) — user can cancel. On cancel: ValueValidationFailed fires, setter returns.
4. Value Commit: _value = newValue.
5. Change Notification: ValueChanged fires.
6. Boundary Events: MinimumReached / MaximumReached if at boundary.
7. Invalidation: Invalidate() triggers repaint.

Programmatic validation is available through public methods: ValidateRange, ValidateFormat, ValidateStep, ValidateNumericInput, ValidateDecimalPlaces, and the comprehensive ValidateValue which chains range+step+ValueValidating+ValueValidatingEx+ValueValidated.

Theming

BeepNumericUpDown uses dedicated theme helpers under Numerics.Helpers:

• NumericThemeHelpers.GetNumericBackgroundColor(theme, useTheme, isHovered) — background.
• NumericThemeHelpers.GetNumericTextColor(theme, useTheme, isHovered) — foreground.
• NumericThemeHelpers.GetNumericBorderColor(theme, useTheme, isHovered) — border.
• NumericThemeHelpers.GetErrorColor(theme, useTheme) — invalid-input background.
• NumericFontHelpers.GetNumericFont(controlStyle) — font for TextBox overlay.

ApplyTheme() updates BackColor, ForeColor, BorderColor, HoverBackColor, HoverForeColor, HoverBorderColor, and the internal TextBox's BackColor, ForeColor, and Font. BeepStyling handles background, border, and shadow at the BaseControl level.

Examples

Basic Numeric

var n = new BeepNumericUpDown { Min=0, Max=100, Increment=5, Value=50, Decimals=1, Width=150 };
n.ValueChanged += (s, e) => Console.WriteLine($"New: {n.Value}");

Phone with Mask

var phone = new BeepNumericUpDown { MaskPreset = NumericMaskPreset.PhoneUS, NumericStyle = NumericStyle.Phone, Width = 200 };

Currency with Validation

var cur = new BeepNumericUpDown(); cur.ConfigureForCurrency("£");
cur.Min=0; cur.Max=1000000;
cur.ValueValidating += (s, e) => { if (e.NewValue > 50000) e.Cancel = true; };

Percentage Auto-Calc

var pct = new BeepNumericUpDown { IsPercentageMode=true, AutoCalculateFromTotal=true, TotalValue=1000m };
pct.Value = 25; decimal actual = pct.GetActualValue(); // 250.0

Bulk Configuration

new BeepNumericUpDown().ConfigureForPercentage();
new BeepNumericUpDown().ConfigureForTaskProgress();
new BeepNumericUpDown().ConfigureForCurrency("€");

Wrap Values

var w = new BeepNumericUpDown { Min=0, Max=10, WrapValues=true, Value=10 };
w.PerformStep(); // wraps to 0

GPS Latitude

var lat = new BeepNumericUpDown { MaskPreset = NumericMaskPreset.Latitude, Width = 180 };
// Auto: Decimals=6, min=-90, max=90

Architecture

Inline TextBox Editing

The control uses a transparent TextBox overlay (_textBox) for direct numeric entry. Key behaviours:

• Creation: Lazily created in StartEditing() with BorderStyle=None, theme-derived BackColor/ForeColor, and font from NumericFontHelpers.
• Positioning: Centred vertically, inset by padding, accounting for both left and right spin-button widths when visible.
• Focus Behaviour: SelectAllOnFocus selects all text. OnLostFocus calls EndEditing(true) to commit.
• Commit: EndEditing(true) strips prefix/suffix/unit symbols and percent signs, parses via decimal.TryParse. On failure, highlights via _invalidInputColor and fires InvalidInput + ValueValidationFailed.
• Cancel: EndEditing(false) (Escape key) discards the edit and hides the TextBox without changing Value.

Auto-Repeat System

When a spin button is held down, StartRepeatTimer fires an immediate action, then uses a System.Windows.Forms.Timer with the following progression:

• Initial delay: 500ms (INITIAL_DELAY)
• Repeat interval: 50ms (REPEAT_DELAY)
• Acceleration: After 5 repeats, maintains 50ms interval (can reach 10ms theoretical MAX_REPEAT_SPEED)
• Direction: Tracked via _repeatIncrementDirection (true=up, false=down)
• Cleanup: StopRepeatTimer on MouseUp, OnEnabledChanged(false), or Dispose