BeepDatePicker

Overview

Namespace: TheTechIdea.Beep.Winform.Controls

Assembly: TheTechIdea.Beep.Winform.Controls.dll

Inheritance: BeepDatePicker → BaseControl → Control

Implements: IBeepComponent (via BaseControl), IBeepUIComponent (via BaseControl)

Toolbox: Beep Controls category, display name "Beep Date Picker"

BeepDatePicker is a feature-rich date/time input control that provides a clean, headerless design where the entire control surface is rendered directly via owner-draw GDI+. There are no child TextBox or Button controls; instead, text, calendar icon, and dropdown button are all painted directly. It supports 15 predefined date format styles, custom format strings, culture-aware parsing/formatting, a calendar popup via BeepDatePickerView, business application features (min/max dates, weekends, excluded dates, auto-adjust to business days), validation with visual error feedback, keyboard navigation (F4/Alt+Down for popup), and auto-submit behavior.

The control is defined in a single source file: BeepDatePicker.cs (1082 lines). Related companion controls (BeepDatePickerView, BeepTimePicker, BeepDateDropDown, BeepDateTimePicker) live in the same Dates\ directory and provide extended calendar/time selection capabilities.

Key Features

• Owner-draw rendering: No child controls; all text, borders, and icon painted directly for maximum performance and theme integration
• 15 date format styles: ShortDate, LongDate, YearMonth, Custom, FullDateTime, ShortDateTime, DayMonthYear, ISODate, ISODateTime, TimeOnly, ShortTime, MonthDay, DayOfWeek, RFC1123, UniversalSortable
• Culture-aware: Respects the assigned CultureInfo for both formatting and parsing
• Inline keyboard editing: Type dates directly with character-level validation; press Enter to commit, Escape to cancel editing
• Calendar popup: Opens BeepDatePickerView inside a BeepPopupForm positioned below the control
• Popup time spinner: The calendar view includes an inline time spinner (up/down chevrons) for adjusting hours/minutes
• Date constraining: MinDate, MaxDate, ExcludedDates, Weekends
• Business context methods: Pre-built configurations for Due Date, Creation Date, Event Scheduling, Birth Date, Appointment
• Auto-adjust to business days: Skips weekends automatically when enabled
• Validation: Visual error highlighting (error backcolor, tooltip), DateValidationFailed event
• AutoSubmit: Fires DateSubmitted immediately when a date is selected from the popup
• Theme integration: Uses CalendarBackColor, CalendarForeColor, CalendarBorderColor, CalendarTitleForColor, DateFont / BodyMedium tokens
• Keyboard shortcuts: F4 or Alt+Down toggles popup; Escape cancels editing; F4 handled in KeyDown
• Placeholder text: Auto-generated from the format string (e.g., "DD/MM/YYYY" replaces format codes with placeholder letters)
• AutoHeight / AutoSize: Optional auto-sizing modes for height and width
• Material Design integration: Convenience property aliases (DatePickerLabel, DatePickerHelperText, DatePickerErrorText)
• Value binding: Implements SetValue/GetValue for data-binding; BoundProperty defaults to "SelectedDateTime"
• Highlighted dates list: Custom dates can be visually highlighted in the calendar

Properties

Methods

Events

Event Args Classes (defined in BeepDatePicker.cs)

Theming

BeepDatePicker integrates with the BeepThemesManager through the ApplyTheme() override. It reads from the following IBeepTheme tokens:

The calendar icon SVG is pre-rendered in multiple sizes (8, 12, 14, 16, 18, 20, 24, 28, 32 px) via Task.Run for smooth scaling. The ApplyTheme method also propagates themes to child objects (calendarIcon, _calendarView) and calls InvalidateOnce() for batched repaint. The _textFont is resolved with a safe fallback chain: DateFont token → BodyMedium token → SystemFonts.DefaultFont.

Examples

Example 1: Basic Usage with Due Date Configuration

var datePicker = new BeepDatePicker
{
    Location = new Point(20, 20),
    Width = 250,
    Theme = myTheme // Optional IBeepTheme instance
};
datePicker.ConfigureForDueDate();
this.Controls.Add(datePicker);

datePicker.DateSubmitted += (s, e) =>
{
    Console.WriteLine($"Due date submitted: {e.SelectedDate} ({e.Context})");
};

Example 2: Custom Format with Validation

var datePicker = new BeepDatePicker
{
    DateFormatStyle = DateFormatStyle.ISODateTime,  // "yyyy-MM-dd HH:mm:ss"
    MinDate = DateTime.Today.AddYears(-1),
    MaxDate = DateTime.Today.AddYears(1),
    AutoAdjustToBusinessDays = true,
    Weekends = new[] { "Friday", "Saturday" }, // Custom weekend
    ShowValidationIcon = true
};

datePicker.DateValidationFailed += (s, e) =>
{
    MessageBox.Show(e.ErrorMessage, "Invalid Date",
        MessageBoxButtons.OK, MessageBoxIcon.Warning);
};

Example 3: Data-Binding and Value Integration

datePicker.SetValue(DateTime.Today.AddDays(7));
datePicker.SelectedDate = "2025-12-31";

var value = datePicker.GetValue(); // DateTime? (null if empty/cleared)

datePicker.Reset(); // Set to DateTime.Now
datePicker.Clear(); // Set to DateTime.MinValue (if AllowEmpty)

datePicker.AddBusinessHolidays(DateTime.Now.Year);
var nextBiz = datePicker.GetNextBusinessDay(DateTime.Today);

Example 4: Read-Only Display Mode

var displayPicker = new BeepDatePicker
{
    SelectedDateTime = new DateTime(2025, 6, 15, 14, 30, 0),
    DateFormatStyle = DateFormatStyle.ShortDateTime,
    ReadOnly = true,
    ShowDropDown = false,
    AllowEmpty = false
};
// User cannot edit or open the calendar popup

Example 5: Material Design Integration

var materialPicker = new BeepDatePicker
{
    PainterKind = BaseControlPainterKind.Material,
    DatePickerLabel = "Appointment Date",
    DatePickerHelperText = "Select a future date and time",
    DatePickerAutoSizeForMaterial = true
};

materialPicker.DatePickerHasError = true;
materialPicker.DatePickerErrorText = "Date is in the past";

Example 6: Business Date Range and Appointment Configuration

datePicker.ConfigureForAppointment();
datePicker.SetBusinessDateRange(
    DateTime.Today.AddDays(1),
    DateTime.Today.AddMonths(3));
datePicker.AddBusinessHolidays(DateTime.Now.Year);

Architecture

BeepDatePicker uses a headerless, owner-draw design with no child controls. The layout is computed in PaintCore using three layout constants: ButtonWidth=24, Padding=3. The right side of the control contains the dropdown area with a dividing line and a calendar SVG icon.

When the user clicks the dropdown area or presses F4/Alt+Down, a BeepPopupForm is created hosting a BeepDatePickerView which provides a full calendar grid with navigation, time spinner, and OK/Cancel footer links. The popup closes on OK (validates date, fires events) or Cancel (fires CancelClicked only).

File breakdown (Dates directory):

Companion Controls

BeepDatePickerView

A modern calendar view control (BaseControl) that displays a month calendar with navigation chevrons, responsive cell sizing, time spinner (up/down chevrons), and OK/Cancel action buttons. Used internally by BeepDatePicker as the popup calendar. Features responsive layout with minimum size enforcement (320x420 default, MinSize calculated from layout constants), theme-aware color tokens (CalendarSelectedDateBackColor, CalendarSelectedDateForColor, CalendarTodayForeColor, CalendarDaysHeaderForColor, CalendarTitleForColor), and font tokens (CalendarTitleFont, DaysHeaderFont, DateFont, CalendarSelectedFont, FooterFont). Properties: SelectedDateTime (DateTime?), ShowTime (bool, default true), Context (string). Events: DateTimeSelected, Cancelled, OkClicked, CancelClicked (both with DateTimeDialogResultEventArgs).

BeepTimePicker

A standalone time picker with a borderless TextBox child for inline editing, a dropdown button (clock SVG icon) that opens a BeepPopupForm with hour/minute/AM-PM ListBoxes, and optional spin up/down BeepButton children. Supports 6 time format styles (TwelveHour, TwentyFourHour, TwelveHourWithSeconds, TwentyFourHourWithSeconds, HoursOnly, Custom), minute interval/snapping (1-60), business hours validation (BusinessStartTime 9:00, BusinessEndTime 17:00), 24-hour toggle, seconds editing toggle, and context configurations with pre-built methods: ConfigureForMeetingTime(), ConfigureForAppointment(), ConfigureForShiftTime(), ConfigureForDeadline(). Events: SelectedTimeChanged, TimeChanged (TimeChangedEventArgs), TimeSubmitted (TimeSubmittedEventArgs), TimeValidationFailed (TimeValidationEventArgs), TimePickerOpened, TimePickerClosed.

BeepDateDropDown

An inline-editing date dropdown inheriting from BeepTextBox for full text editing capabilities (input masking, AutoComplete, Undo/Redo, selection/caret management). Supports single dates, date ranges ("MM/dd/yyyy - MM/dd/yyyy"), and date-time ranges with proper formatting. The dropdown calendar is a BeepDateTimePicker shown in a popup. 7 partial files: Core, Properties, Events, Methods, Drawing, SegmentEditing, Sync. Features: inline masking, F4 dropdown shortcut, culture-specific formatting, min/max date constraints, theme integration, validation feedback.

BeepDateTimePicker

A full-featured date/time picker control supporting 18 functional modes (Single, SingleWithTime, Range, RangeWithTime, Multiple, Appointment, Timeline, Quarterly, Compact, ModernCard, DualCalendar, WeekView, MonthView, YearView, SidebarEvent, FlexibleRange, FilteredRange, Header). Uses a pluggable painter/hit-handler architecture with 20 painter strategies per mode and 20 hit handler strategies per mode. Incomplete implementation (stub state with 8 partial files).

Enumerations

DateFormatStyle (from Beep.Vis.Modules2.0)

TimeFormatStyle (from BeepTimePicker.cs)

DatePickerMode (from Models/enums.cs)

Defines functional mode for BeepDateTimePicker/BeepDateDropDown. 18 values: Single, SingleWithTime, Range, RangeWithTime, Multiple, Appointment, Timeline, Quarterly, Compact, ModernCard, DualCalendar, WeekView, MonthView, YearView, SidebarEvent, FlexibleRange, FilteredRange, Header.

ReturnDateTimeType (from Models/enums.cs)

Defines return value type: Date, DateTime, DateRange, DateTimeRange, MultipleDates, TimeOnly.

Additional Date Enums (from Models/enums.cs)

DateDropDownStyle: Default, Modern, Classic, Custom — DatePickerFormat: Long, Short, Time, Custom, ShortDate — DatePickerView: Days, Months, Years — DatePickerSelectionMode: Single, Multiple, Range — DatePickerCalendarType: Gregorian, Julian, Hebrew, Hijri, ThaiBuddhist, UmAlQura — DatePickerFirstDayOfWeek: Sunday through Saturday — DatePickerWeekNumbers: None, FirstDay, FirstFullWeek, FirstFourDayWeek, Left — DatePickerMonthDisplay: Full, Abbreviated, Numeric — DatePickerYearDisplay: Full, Abbreviated, TwoDigit — DatePickerHighlightCurrentDate: None, Background, Border, Both — DatePickerHighlightSelectedDate: None, Background, Border, Both — DatePickerDisabledDateStyle: GrayedOut, Hidden, Custom — DatePickerAnimationType: None, Fade, Slide, Zoom — DateTimePickerHitArea: 40+ hit areas covering all interactive zones (Header, DayCell, QuickButton, TimeSpinner, etc.).