TimePickerControl

Locale-aware time picker with segmented editing, 12h/24h modes, and min/max time constraints.

Overview

The TimePickerControl displays segmented hour/minute (and optionally second) fields with an optional AM/PM segment. Users type digits directly or use arrow keys to adjust values. The 12h/24h format and AM/PM designators are derived from the configured CultureInfo.

See also: DatePickerControl

Quick Start

var timePicker = Controls.TimePicker("Alarm:")
    .WithSelectedTime(new TimeSpan(8, 30, 0))
    .With12HourFormat()
    .OnSelectedTimeChanged((s, time) =>
    {
        // time is TimeSpan?
    })
    .Build();

window.AddControl(timePicker);

Builder API

Create a TimePickerBuilder through the Controls factory:

var builder = Controls.TimePicker("Start time:");

Value Methods

.WithSelectedTime(TimeSpan time)           // Set the initial time
.WithMinTime(TimeSpan minTime)             // Set minimum allowed time
.WithMaxTime(TimeSpan maxTime)             // Set maximum allowed time

Format Methods

.WithCulture(CultureInfo culture)          // Set locale for time format and AM/PM designators
.With24HourFormat()                        // Force 24-hour display
.With12HourFormat()                        // Force 12-hour display with AM/PM
.WithSeconds(bool show = true)             // Show or hide the seconds segment

Layout Methods

.WithPrompt(string prompt)                 // Set the label text (default: "Time:")
.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
.Enabled(bool enabled)                     // Initial enabled state

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

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

Building

TimePickerControl control = builder.Build();

// Implicit conversion is also supported:
TimePickerControl control = Controls.TimePicker("Time:")
    .WithSelectedTime(new TimeSpan(14, 30, 0));

Properties

Property	Type	Description
SelectedTime	TimeSpan?	The currently selected time. null defaults to TimeSpan.Zero for display.
MinTime	TimeSpan?	Minimum selectable time. Values are clamped on set.
MaxTime	TimeSpan?	Maximum selectable time. Values are clamped on set.
Culture	CultureInfo	Locale controlling time separator and AM/PM designators. Defaults to CultureInfo.CurrentCulture.
Use24HourFormat	bool?	Override the culture's default. null = auto-detect from culture, true = 24h, false = 12h.
ShowSeconds	bool	Whether to display the seconds segment. Default: false.
Prompt	string	Label text displayed before the time segments.
IsEnabled	bool	Whether the control accepts input.
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 time segment.
SegmentForegroundColor	Color	Foreground of the active time segment.
DisabledForegroundColor	Color	Foreground color when the control is disabled.

Events

Event	Signature	Description
SelectedTimeChanged	EventHandler<TimeSpan?>	Fires when the selected time changes.
GotFocus	EventHandler	Fires when the control receives focus.
LostFocus	EventHandler	Fires when the control loses focus.

Keyboard Shortcuts

Key	Action
Left / Right	Move between time segments
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
Page Up	Increment the focused segment by a large step
Page Down	Decrement the focused segment by a large step
Home	Set the focused segment to its minimum value
End	Set the focused segment to its maximum value
0-9	Type digits directly into the focused segment
A	Set to AM (when AM/PM segment is focused)
P	Set to PM (when AM/PM segment is focused)

Digit entry uses a two-keystroke model: the first digit is held as a pending value, and the second digit completes the entry. If the first digit is too large to be a valid tens place, it commits immediately. After a complete two-digit entry, focus auto-advances to the next segment.

Mouse Interaction

• Click on a segment focuses that segment for editing
• Mouse wheel increments/decrements the focused segment

12-Hour and 24-Hour Modes

By default, the format is auto-detected from the culture's ShortTimePattern. You can override this explicitly:

// 24-hour format
Controls.TimePicker("Departure:")
    .With24HourFormat()
    .WithSeconds()
    .Build();
// Displays: Departure: 14:30:00

// 12-hour format
Controls.TimePicker("Departure:")
    .With12HourFormat()
    .Build();
// Displays: Departure: 02:30 PM

In 12-hour mode, an additional AM/PM segment appears. Navigate to it with arrow keys and press A or P to toggle, or use Up/Down to cycle.

Locale and CultureInfo

The time separator and AM/PM designators are derived from the culture:

// US English: 2:30 PM (colon separator, AM/PM)
Controls.TimePicker()
    .WithCulture(new CultureInfo("en-US"))

// German: 14:30 (colon separator, 24h by default)
Controls.TimePicker()
    .WithCulture(new CultureInfo("de-DE"))

// Korean: 14:30 (24h, culture-specific designators available)
Controls.TimePicker()
    .WithCulture(new CultureInfo("ko-KR"))

Theme Properties

Theme Property	Description	ClassicTheme Default
TimePickerBackgroundColor	Unfocused background	null (inherits from window)
TimePickerForegroundColor	Unfocused foreground	null (inherits from window)
TimePickerFocusedBackgroundColor	Focused background	Color.Blue
TimePickerFocusedForegroundColor	Focused foreground	Color.White
TimePickerSegmentBackgroundColor	Active segment background	Color.DarkBlue
TimePickerSegmentForegroundColor	Active segment foreground	Color.White
TimePickerDisabledForegroundColor	Disabled text	Color.Grey

Common Patterns

Time Range with Business Hours

var businessStart = new TimeSpan(8, 0, 0);
var businessEnd = new TimeSpan(18, 0, 0);

window.AddControl(Controls.TimePicker("Appointment:")
    .WithMinTime(businessStart)
    .WithMaxTime(businessEnd)
    .WithSelectedTime(new TimeSpan(9, 0, 0))
    .With24HourFormat()
    .Build());

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 | DatePickerControl