DatePickerControl

Locale-aware date picker with segmented editing, calendar popup, and min/max date constraints.

Overview

The DatePickerControl displays an inline date editor with segmented month/day/year fields. Users can type digits directly into each segment, use arrow keys to increment/decrement values, or open a calendar popup overlay for visual date selection. The segment order and separator are derived from the configured CultureInfo.

See also: TimePickerControl

Quick Start

var datePicker = Controls.DatePicker("Birthday:")
    .WithSelectedDate(new DateTime(2000, 1, 15))
    .OnSelectedDateChanged((s, date) =>
    {
        // date is DateTime?
    })
    .Build();

window.AddControl(datePicker);

Builder API

Create a DatePickerBuilder through the Controls factory:

var builder = Controls.DatePicker("Select date:");

Value Methods

.WithSelectedDate(DateTime? date)          // Set the initial date
.WithMinDate(DateTime? date)               // Set minimum allowed date
.WithMaxDate(DateTime? date)               // Set maximum allowed date

Format Methods

.WithCulture(CultureInfo culture)          // Set locale for format and first day of week
.WithFormat(string format)                 // Override the date format pattern (e.g. "yyyy-MM-dd")
.WithFirstDayOfWeek(DayOfWeek day)         // Override the first day of the week in the calendar

Layout Methods

.WithPrompt(string prompt)                 // Set the label text (default: "Date:")
.WithAlignment(HorizontalAlignment align)  // Horizontal alignment
.WithVerticalAlignment(VerticalAlignment)  // Vertical alignment
.WithMargin(int left, int top, int right, int bottom)
.WithMargin(int margin)                    // Uniform margin on all sides
.WithWidth(int width)                      // Fixed width
.Visible(bool visible)                     // Initial visibility

Identity Methods

.WithName(string name)                     // Name for FindControl<T>() lookups
.WithTag(object tag)                       // Arbitrary user data
.WithStickyPosition(StickyPosition pos)    // Sticky positioning
.StickyTop()                               // Shorthand for StickyPosition.Top
.StickyBottom()                            // Shorthand for StickyPosition.Bottom

Event Methods

.OnSelectedDateChanged(EventHandler<DateTime?> handler)
.OnSelectedDateChanged(WindowEventHandler<DateTime?> handler)  // includes Window reference
.OnGotFocus(EventHandler handler)
.OnGotFocus(WindowEventHandler<EventArgs> handler)
.OnLostFocus(EventHandler handler)
.OnLostFocus(WindowEventHandler<EventArgs> handler)

Building

DatePickerControl control = builder.Build();

// Implicit conversion is also supported:
DatePickerControl control = Controls.DatePicker("Date:")
    .WithSelectedDate(DateTime.Today);

Properties

Property Type Description
SelectedDate DateTime? The currently selected date. null means no date is set (displays today as placeholder).
MinDate DateTime? Minimum selectable date. Dates before this are clamped and grayed out in the calendar.
MaxDate DateTime? Maximum selectable date. Dates after this are clamped and grayed out in the calendar.
Culture CultureInfo Locale controlling date format and first day of week. Defaults to CultureInfo.CurrentCulture.
DateFormatOverride string? Overrides the short date pattern from the culture (e.g. "dd/MM/yyyy").
FirstDayOfWeekOverride DayOfWeek? Overrides the culture's first day of the week for the calendar grid.
Prompt string Label text displayed before the date segments.
IsEnabled bool Whether the control accepts input.
IsCalendarOpen bool Read-only. Whether the calendar popup is currently visible.
BackgroundColor Color Background color (unfocused).
ForegroundColor Color Foreground color (unfocused).
FocusedBackgroundColor Color Background color when focused.
FocusedForegroundColor Color Foreground color when focused.
SegmentBackgroundColor Color Background of the active date segment.
SegmentForegroundColor Color Foreground of the active date segment.

Events

Event Signature Description
SelectedDateChanged EventHandler<DateTime?> Fires when the selected date changes.
GotFocus EventHandler Fires when the control receives focus.
LostFocus EventHandler Fires when the control loses focus (also closes the calendar).

Keyboard Shortcuts

Inline Mode (segments)

Key Action
Left / Right Move between date segments (month, day, year)
Tab / Shift+Tab Move between segments (passes focus if at first/last segment)
Up Increment the focused segment by 1
Down Decrement the focused segment by 1
0-9 Type digits directly into the focused segment
Enter / Space Open the calendar popup

Calendar Popup Mode

Key Action
Left / Right Move highlight by one day
Up / Down Move highlight by one week
Page Up Previous month
Page Down Next month
Ctrl+Page Up Previous year
Ctrl+Page Down Next year
Home Jump to first day of the month
End Jump to last day of the month
T Jump to today
Enter / Space Select the highlighted day and close the calendar
Escape Close the calendar without changing the date

Mouse Interaction

  • Click on a segment focuses that segment for editing
  • Click on the ▼ indicator toggles the calendar popup open/closed
  • Click a day in the calendar selects it and closes the popup
  • Click ◄/► in the calendar header navigates months
  • Click [ Today ] jumps to today and selects it
  • Mouse wheel on calendar scrolls months

Calendar Popup

Pressing Enter or Space on the inline date, or clicking the ▼ indicator, opens a calendar overlay rendered through the portal system. Clicking on date segments focuses them for editing without opening the calendar. The calendar displays:

  • A month/year header with navigation arrows
  • Day-of-week column headers (locale-aware abbreviations)
  • A grid of days with highlighting for today and the selected date
  • Out-of-range days grayed out when MinDate/MaxDate are set
  • A "Today" button to jump to the current date

The calendar supports both keyboard and mouse interaction. Clicking a day selects it and closes the popup. Clicking outside the calendar dismisses it.

Locale and CultureInfo

The date format, separator character, and first day of week are all derived from the Culture property:

// US format: MM/dd/yyyy, week starts Sunday
Controls.DatePicker("Date:")
    .WithCulture(new CultureInfo("en-US"))

// German format: dd.MM.yyyy, week starts Monday
Controls.DatePicker("Datum:")
    .WithCulture(new CultureInfo("de-DE"))

// Japanese format: yyyy/MM/dd
Controls.DatePicker()
    .WithCulture(new CultureInfo("ja-JP"))

// ISO format override regardless of culture
Controls.DatePicker()
    .WithFormat("yyyy-MM-dd")
    .WithFirstDayOfWeek(DayOfWeek.Monday)

Theme Properties

Theme Property Description ClassicTheme Default
DatePickerBackgroundColor Unfocused background null (inherits from window)
DatePickerForegroundColor Unfocused foreground null (inherits from window)
DatePickerFocusedBackgroundColor Focused background Color.Blue
DatePickerFocusedForegroundColor Focused foreground Color.White
DatePickerSegmentBackgroundColor Active segment background Color.DarkBlue
DatePickerSegmentForegroundColor Active segment foreground Color.White
DatePickerDisabledForegroundColor Disabled text Color.Grey
DatePickerCalendarTodayColor Today highlight in calendar Color.Cyan1
DatePickerCalendarSelectedColor Selected day highlight Color.Blue
DatePickerCalendarHeaderColor Calendar header text Color.Yellow

Common Patterns

Date Range Validation

DatePickerControl? startPicker = null;
DatePickerControl? endPicker = null;

startPicker = Controls.DatePicker("From:")
    .WithSelectedDate(DateTime.Today)
    .OnSelectedDateChanged((s, date) =>
    {
        if (endPicker != null && date.HasValue)
            endPicker.MinDate = date;
    })
    .Build();

endPicker = Controls.DatePicker("To:")
    .WithMinDate(DateTime.Today)
    .OnSelectedDateChanged((s, date) =>
    {
        if (startPicker != null && date.HasValue)
            startPicker.MaxDate = date;
    })
    .Build();

window.AddControl(startPicker);
window.AddControl(endPicker);

Combined Date and Time Form

window.AddControl(Controls.DatePicker("Date:")
    .WithName("meetingDate")
    .WithMinDate(DateTime.Today)
    .Build());

window.AddControl(Controls.TimePicker("Start:")
    .WithName("startTime")
    .With24HourFormat()
    .WithSelectedTime(new TimeSpan(9, 0, 0))
    .Build());

window.AddControl(Controls.Button("Schedule")
    .OnClick((s, e, w) =>
    {
        var date = w.FindControl<DatePickerControl>("meetingDate")?.SelectedDate;
        var start = w.FindControl<TimePickerControl>("startTime")?.SelectedTime;
        if (date.HasValue && start.HasValue)
        {
            var dateTime = date.Value + start.Value;
            // Process...
        }
    })
    .Build());

Back to Controls Reference | TimePickerControl

Edit this page