CoreSuite.DateTimeBox 1.0.0

CoreSuite DateTimeBox

CoreSuite.DateTimeBox is a culture-aware Windows Forms control for entering and selecting a complete date and time in a single field. It combines masked keyboard input with a dropdown editor containing a calendar, a time selector, and explicit confirmation and cancellation actions.

Features

• Culture-aware date and time parsing and formatting
• Short date pattern obtained from the configured culture
• Short or long time pattern depending on ShowSeconds
• Masked keyboard input
• Combined calendar and time dropdown editor
• Explicit OK and Cancel actions
• Optional custom dropdown button image
• Built-in calendar and clock glyph when no image is assigned
• Data binding through the DateTime property
• Windows Forms designer and smart tag support
• Empty-value support through DateTime.MinValue and ClearDateTime()

Requirements

• .NET 8
• Windows Forms
• Windows operating system

Installation

Install the package from NuGet:

dotnet add package CoreSuite.DateTimeBox

Or use the NuGet Package Manager:

Install-Package CoreSuite.DateTimeBox

The package automatically includes its required CoreSuite dependencies.

Basic usage

Dim AppointmentBox As New DateTimeBox With {
    .DateTimeCulture = Globalization.CultureInfo.GetCultureInfo("pt-BR"),
    .ShowSeconds = False,
    .DateTime = New DateTime(2026, 8, 2, 14, 30, 0),
    .Width = 180
}

AddHandler AppointmentBox.DateTimeValueChanged,
    Sub(sender As Object, e As EventArgs)
        If AppointmentBox.HasDateTime Then
            Console.WriteLine(AppointmentBox.DateTime)
        End If
    End Sub

Main properties

Event

DateTimeValueChanged

Occurs whenever the represented value changes, including when a valid value is entered, selected from the dropdown, or cleared.

Private Sub AppointmentBox_DateTimeValueChanged(sender As Object, e As EventArgs) Handles AppointmentBox.DateTimeValueChanged
    If AppointmentBox.HasDateTime Then
        Text = AppointmentBox.DateTime.ToString("F", AppointmentBox.DateTimeCulture)
    Else
        Text = "No appointment selected"
    End If
End Sub

Clearing the value

Use either ClearDateTime() or assign DateTime.MinValue:

AppointmentBox.ClearDateTime()

' Equivalent behavior:
AppointmentBox.DateTime = DateTime.MinValue

Culture examples

AppointmentBox.DateTimeCulture = Globalization.CultureInfo.GetCultureInfo("pt-BR")
' Example: 02/08/2026 14:30

AppointmentBox.DateTimeCulture = Globalization.CultureInfo.GetCultureInfo("en-US")
' Example: 08/02/2026 02:30 PM

Single-character date and time components are normalized internally so they can be represented consistently by the masked input control.

Showing seconds

AppointmentBox.ShowSeconds = True
AppointmentBox.DateTime = New DateTime(2026, 8, 2, 14, 30, 45)

When ShowSeconds is False, seconds remain part of a programmatically assigned or dropdown-selected value but are not shown by the control.

Data binding

DateTime is the control's default binding property:

AppointmentBox.DataBindings.Add(
    NameOf(AppointmentBox.DateTime),
    ViewModel,
    NameOf(ViewModel.AppointmentDateTime),
    formattingEnabled:=True,
    updateMode:=DataSourceUpdateMode.OnPropertyChanged)

Because an empty control exposes DateTime.MinValue, convert that sentinel value when binding to a nullable model property.

Dropdown behavior

The dropdown starts with the current control value. If the control is empty, it starts with the current local date and time.

• OK combines the selected calendar date with the selected time and updates the control.
• Cancel closes the dropdown without changing the control.
• Closing the dropdown by clicking elsewhere also leaves the existing value unchanged.
• Pressing Enter while the field is focused opens the dropdown editor.

License

This project is licensed under the MIT License.