DTPicker class

A DTPicker shows one date, one time, or both, in a box of fields. The user changes a field with the keyboard or the mouse and picks a date from a drop-down calendar, or from a pair of arrow buttons that stand in place of the calendar.

A date picker that shows 2026-03-15 in the custom format yyyy-MM-dd, with the button of its calendar at the right
DTPicker1.Value = DateSerial(2026, 3, 15) + TimeSerial(10, 20, 30)
Debug.Print Format$(DTPicker1.Value, "yyyy-mm-dd hh:nn:ss")
DTPicker1.Month = 7
DTPicker1.Day = 31
Debug.Print Format$(DTPicker1.Value, "yyyy-mm-dd hh:nn:ss")
' Output:
'  2026-03-15 10:20:30
'  2026-07-31 10:20:30

The control stands in place of the DTPicker of the Microsoft common controls (MSCOMCT2.OCX). The WinNativeCommonCtls package has a DTPicker too; this one adds AllowUserInput with its three events, CalendarAlignment, CalendarFont, CalendarDayState, CalendarUseShortestDayNames, DroppedDown, Selected, GetIdealSize and the context menu events.

Of the common members, the control has those under Name and place, Window handles, Font and visual styles, Mouse but its DblClick event, Keyboard and focus, Dragging the control, OLE drag and drop and Right-to-left, RightToLeftLayout included. Its hWnd is the window of the date picker of Windows.

The date and the time

Value is a Variant that holds a Date, with the time of day, or Null while the control has no date. A new control holds the date of the day it is made. Assigning a number gives the date with that serial number, as CDate does, and assigning Empty is assigning Null.

The box shows the date or the time by Format: a long or a short date, a time, or a custom format.

Value keeps the seconds of a time, and the control shows them if its format does. A value that is neither a date nor a number raises run-time error 380.

The parts of the date are also properties: Year, Month, Day, Hour, Minute, Second and Week. Each one reads the part of Value, and an assignment to it changes that part and nothing else, as an assignment to Value does. DayCount and DayOfWeek read the length of the month and the weekday.

A part outside its range raises run-time error 380: a Month from 1 to 12, a Day from 1 to the DayCount of the month, an Hour from 0 to 23, a Minute and a Second from 0 to 59, and a Week from 1 to 53.

The range of dates

MinDate and MaxDate limit the dates the control accepts, both from 1 January 1900 to the end of 31 December 9999, which is the default range. They limit what the user can pick and what a program assigns.

A Value outside the range raises run-time error 35773 and changes nothing. A MinDate after MaxDate raises 35775, a MaxDate before MinDate raises 35774, and a date before 1900 raises 380.

On Error Resume Next
DTPicker1.MinDate = DateSerial(2026, 1, 1)
DTPicker1.MaxDate = DateSerial(2026, 12, 31)
DTPicker1.Value = DateSerial(2027, 1, 1)
Debug.Print Err.Number
Err.Clear
DTPicker1.MaxDate = DateSerial(2025, 1, 1)
Debug.Print Err.Number
' Output:
'  35773
'  35774

A new MinDate after the current date, or a new MaxDate before it, moves Value to that limit. The move raises no Change.

No date: the check box

With CheckBox set to True the control shows a check box at the left of the date. While the box is not checked the control has no date: Value is Null and Selected is False. The user checks the box with the mouse or the space bar. A program unselects the date by assigning Null to Value, or False to Selected, and selects it again with Selected set to True, which brings back the date the control held before.

Two date pickers with CheckBox set to True: with the Value 2026-03-15 the box is checked and the date is black, with the Value Null the box is empty and the date is gray

Assigning Null to a control without a check box raises run-time error 35787. Setting CheckBox to False while no date is selected selects the date held before.

DTPicker1.CheckBox = True
DTPicker1.Value = DateSerial(2026, 3, 15)
DTPicker1.Value = Null
Debug.Print DTPicker1.Selected, IsNull(DTPicker1.Value)
DTPicker1.Selected = True
Debug.Print DTPicker1.Selected, Format$(DTPicker1.Value, "yyyy-mm-dd")
' Output:
'  False         True
'  True          2026-03-15

Custom formats

With Format set to DtpFormatCustom, CustomFormat says what the box shows. Each of these codes shows a field, and the user changes the field with the arrow keys.

Two date pickers with custom formats: "yyyy-MM-dd HH:mm" shows 2026-03-15 10:30 with the button of the calendar, and "HH:mm" with UpDown set to True shows 10:30 with a pair of arrow buttons
Code Shows
d, dd the day of the month, without and with a leading zero
ddd, dddd the name of the weekday, short and long
M, MM the month number, without and with a leading zero
MMM, MMMM the name of the month, short and long
yy, yyyy the year, with two and with four digits
h, hh the hour from 1 to 12, without and with a leading zero
H, HH the hour from 0 to 23, without and with a leading zero
m, mm the minute, without and with a leading zero
s, ss the second, without and with a leading zero
t, tt the first letter of the AM or PM sign, and the whole sign
X, XX, … a callback field, described below

Any other text goes between single quotes, and a doubled quote is a quote. The names of weekdays and months, and the AM and PM signs, are those of the user’s language.

The text of the window of hWnd is the text the box shows:

Dim Shown As String, N As Long
Shown = String$(100, vbNullChar)
DTPicker1.Value = DateSerial(2026, 3, 5) + TimeSerial(14, 7, 0)
DTPicker1.Format = DtpFormatCustom
DTPicker1.CustomFormat = "yyyy-MM-dd HH:mm"
N = DtpGetWindowText(DTPicker1.hWnd, StrPtr(Shown), 100)
Debug.Print Left$(Shown, N)
DTPicker1.CustomFormat = "'Day 'd' of month 'M"
N = DtpGetWindowText(DTPicker1.hWnd, StrPtr(Shown), 100)
Debug.Print Left$(Shown, N)
' Output:
'  2026-03-05 14:07
'  Day 5 of month 3

A run of the letter X that is not between quotes is a field whose text the program supplies. The control raises FormatSize to learn how many characters the field needs, FormatString to learn its text, and CallbackKeyDown when the user presses a key in it.

FormatSize is raised when CustomFormat is set to a format with a callback field, with the run of X as CallbackField.

Private Sub DTPicker1_FormatSize(ByVal CallbackField As String, Size As Integer)
    Size = 6                                   ' room for "Spring"
End Sub

Private Sub DTPicker1_FormatString(ByVal CallbackField As String, FormattedString As String)
    FormattedString = "Spring"
End Sub

Typing a date

With AllowUserInput set to True the user can type the whole date into the box, after pressing F2 or clicking inside it. The control raises BeforeUserInput when typing starts, and when the user finishes it raises ParseUserInput with the typed text, so that the program turns the text into a date. AfterUserInput follows when the typing is over, whether the user finished or cancelled it.

Private Sub DTPicker1_ParseUserInput(ByVal Text As String, ParseDate As Variant)
    If Text = "today" Then
        ParseDate = Date
    ElseIf IsDate(Text) Then
        ParseDate = CDate(Text)
    Else
        ParseDate = Null                       ' only with CheckBox = True
    End If
End Sub

The calendar

The calendar drops down from a button at the right of the box, or when the user presses Alt+Down. DropDown is raised when it is about to open and CloseUp when it has closed. While it is open, DroppedDown is True and hWndCalendar is its handle. With UpDown set to True the control has a pair of arrow buttons in place of the calendar, and the time format has none either way.

A date picker with DroppedDown set to True: under the box that shows 2026-03-15 its calendar shows March 2026, with the 15th selected and the last days of February and the first of April in gray

The calendar has its own font, CalendarFont, its own colors, and the options of the Calendar properties: CalendarShowToday and CalendarShowTodayCircle for the day of the program’s run, CalendarShowWeekNumbers, CalendarShowTrailingDates, CalendarUseShortestDayNames and StartOfWeek.

The program opens the calendar by setting DroppedDown to True and closes it by setting it to False. Each raises its event.

With CalendarDayState set to True, the calendar raises CalendarGetDayBold before it shows a month, and draws in bold the days the program marks:

Private Sub DTPicker1_CalendarGetDayBold(ByVal StartDate As Date, ByVal Count As Long, State() As Boolean)
    Dim I As Long
    For I = 1 To Count
        If Weekday(StartDate + I - 1) = vbMonday Then State(I) = True
    Next
End Sub

Properties

AllowUserInput

Whether the user can type a date into the box. Boolean. Default: False. See Typing a date. A change makes the control draw again from a new window.

CalendarAlignment

Which edge of the control the calendar lines up with when it drops down. A member of CCLeftRightAlignmentConstants. Default: CCLeftRightAlignmentLeft.

Any other value raises run-time error 380. When RightToLeft and RightToLeftLayout are both True the control sets this to CCLeftRightAlignmentRight itself.

CalendarBackColor

The background color of the days in the calendar. OLE_COLOR. Default: vbWindowBackground. Windows ignores it while the calendar is drawn with visual styles, so it shows with VisualStyles set to False.

CalendarDayState

Whether the calendar asks the program which days to draw in bold. Boolean. Default: False. With True the calendar raises CalendarGetDayBold.

CalendarFont

The font of the calendar. A StdFont object. A new control has the font of its container. Assigning Nothing gives the container’s font again.

CalendarForeColor

The color of the text of the days in the calendar. OLE_COLOR. Default: vbButtonText. It shows with visual styles off, as CalendarBackColor does.

CalendarShowToday

Whether the calendar shows a line with the current date at its bottom. Boolean. Default: True.

CalendarShowTodayCircle

Whether the calendar draws a circle round the current date. Boolean. Default: True.

CalendarShowTrailingDates

Whether the calendar shows the days of the months before and after the one it displays, in the cells that month leaves free. Boolean. Default: True.

CalendarShowWeekNumbers

Whether the calendar shows the week numbers at the left of the weeks. Boolean. Default: False.

CalendarTitleBackColor

The background color of the calendar’s title, with the month and the year. OLE_COLOR. Default: vbActiveTitleBar. It shows with visual styles off.

CalendarTitleForeColor

The color of the text of the calendar’s title. OLE_COLOR. Default: vbActiveTitleBarText. It shows with visual styles off.

CalendarTrailingForeColor

The color of the days of the neighbouring months. OLE_COLOR. Default: vbGrayText. It shows with visual styles off.

CalendarUseShortestDayNames

Whether the calendar writes the names of the weekdays with the shortest form the user’s language has, one or two letters, in place of the short form. Boolean. Default: False.

CheckBox

Whether the control shows a check box at the left of the date, so that it can have no date. Boolean. Default: False. See No date: the check box. A change makes the control draw again from a new window, and keeps the value and the selection.

CustomFormat

The format of the box when Format is DtpFormatCustom. String. Default: empty. See Custom formats.

Day

The day of the month of Value. Variant, a number from 1 to DayCount; Null while no date is selected. An assignment changes the day, and a number outside the month raises run-time error 380.

DayCount

The number of days in the month of Value. Variant, read-only.

DayOfWeek

The day of the week of Value, as a number from 0 for Sunday to 6 for Saturday. Integer, read-only.

Reading it while no date is selected raises run-time error 94.

DroppedDown

Whether the calendar is open. Boolean. Setting it to True opens the calendar as Alt+Down does, and False closes it. A control with UpDown set to True has no calendar and stays False.

Format

What the box shows. A member of DtpFormatConstants. Default: DtpFormatShortDate.

Any other value raises run-time error 380. A change makes the control draw again from a new window, and keeps the value and the selection.

Hour

The hour of Value, from 0 to 23. Variant; Null while no date is selected.

hWndCalendar

The handle of the window of the calendar while it is open, and 0 otherwise. LongPtr, read-only.

hWndUpDown

The handle of the window of the arrow buttons when UpDown is True, and 0 otherwise. LongPtr, read-only.

MaxDate

The last date the control accepts. Date. Default: 31 December 9999. See The range of dates.

MinDate

The first date the control accepts. Date. Default: 1 January 1900. See The range of dates.

Minute

The minute of Value, from 0 to 59. Variant; Null while no date is selected.

Month

The month of Value, from 1 to 12. Variant; Null while no date is selected.

Second

The second of Value, from 0 to 59. Variant; Null while no date is selected.

Selected

Whether the control has a date. Boolean. It is always True for a control without CheckBox. With a check box it is the state of the box: setting it to False assigns Null to Value, and setting it to True brings back the date held before.

StartOfWeek

The day shown in the leftmost column of the calendar. Integer: 0 for the first day of the week of the user’s language (the default), or 1 for Monday to 7 for Sunday.

Any other value raises run-time error 380.

While the calendar is open it reads the day the calendar shows, from 1 to 7, and otherwise it reads the setting. The setting is applied when the calendar opens.

SystemStartOfWeek

The first day of the week of the user’s language, from 1 for Monday to 7 for Sunday. Integer, read-only.

UpDown

Whether a pair of arrow buttons, which change the selected field, stands in place of the drop-down calendar. Boolean. Default: False. It has no effect with the time format. A change makes the control draw again from a new window.

Value

The date and the time. Variant: a Date, or Null while no date is selected. It is the control’s default property. See The date and the time, The range of dates and No date: the check box.

A change raises Change.

Week

The week of the year of Value, from 1 to 53, counted as StartOfWeek says, with the first week the one that has at least four days of the new year. Variant; Null while no date is selected. An assignment moves Value by the number of weeks between the two numbers, and a number outside 1 to 53 raises run-time error 380.

Year

The year of Value. Variant; Null while no date is selected. Assigning a value that is not a number raises run-time error 380.

Methods

GetIdealSize

Gives the width and the height the control needs to show its text.

Syntax: object.GetIdealSize Width, Height

Width, Height
required Single variables that receive the size, in the scale units of the control’s container.

Events

AfterUserInput

Raised when the user has finished typing a date, or has cancelled it. See Typing a date.

Syntax: object_AfterUserInput( )

BeforeUserInput

Raised when the user starts typing a date, which needs AllowUserInput.

Syntax: object_BeforeUserInput( ByVal hWndEdit As LongPtr )

hWndEdit
The handle of the window of the box that takes the typing.

CalendarContextMenu

Raised when the user asks for the menu of the open calendar, with the right mouse button or with Shift+F10.

Syntax: object_CalendarContextMenu( Handled As Boolean, ByVal X As Single, ByVal Y As Single )

Handled
False when the event is raised. A handler that sets it to True keeps the control from going on with the request.
X, Y
The place of the click, measured from the top left corner of the calendar in the scale units of the control’s container. Both are -1 when the user asked with the keyboard.

CalendarGetDayBold

Raised when the calendar needs to know which days to draw in bold, with CalendarDayState set to True. See The calendar.

Syntax: object_CalendarGetDayBold( ByVal StartDate As Date, ByVal Count As Long, State() As Boolean )

StartDate
The first day the calendar shows.
Count
The number of days the calendar shows.
State
An array of Count elements, indexed from 1, one for each day from StartDate. A handler sets an element to True to draw that day in bold.

CallbackKeyDown

Raised when the user presses a key while a callback field has the focus.

Syntax: object_CallbackKeyDown( ByVal KeyCode As Integer, ByVal Shift As Integer, ByVal CallbackField As String, CallbackDate As Date )

KeyCode, Shift
The key, as the KeyDown event gives it.
CallbackField
The run of X that makes the field.
CallbackDate
The date of the control. A handler changes it to change the date.

Change

Raised when Value has changed, by an assignment or by the user, and when the user checks or unchecks the check box. A change of the seconds counts. Assigning the value the control already holds raises nothing.

Syntax: object_Change( )

CloseUp

Raised when the calendar has closed.

Syntax: object_CloseUp( )

ContextMenu

Raised when the user asks for the menu of the control, with the right mouse button or with Shift+F10.

Syntax: object_ContextMenu( Handled As Boolean, ByVal X As Single, ByVal Y As Single )

Handled
False when the event is raised. A handler that sets it to True keeps the control from going on with the request.
X, Y
The place of the click, measured from the top left corner of the control in the scale units of the control’s container. Both are -1 when the user asked with the keyboard.

Raised when the calendar is about to open.

Syntax: object_DropDown( )

FormatSize

Raised when the control needs the greatest width of a callback field.

Syntax: object_FormatSize( ByVal CallbackField As String, Size As Integer )

CallbackField
The run of X that makes the field.
Size
The greatest number of characters the field will show. A handler sets it. A control that is given 0 uses 1.

FormatString

Raised when the control needs the text of a callback field.

Syntax: object_FormatString( ByVal CallbackField As String, FormattedString As String )

CallbackField
The run of X that makes the field.
FormattedString
The text to show, up to 63 characters. A handler sets it.

ParseUserInput

Raised when the user has finished typing a date, with AllowUserInput set to True. See Typing a date.

Syntax: object_ParseUserInput( ByVal Text As String, ParseDate As Variant )

Text
What the user typed.
ParseDate
The date of the control when the event is raised. A handler sets it to the date the text means: a Date, a number, or Null (or Empty) to select no date, which needs CheckBox. The date must be within MinDate and MaxDate.

DtpFormatConstants

The values of Format.

Member Value Description
DtpFormatLongDate 0 The date in the long form of the user’s language, with the names of the weekday and of the month.
DtpFormatShortDate 1 The date in the short form of the user’s language, with numbers.
DtpFormatTime 2 The time of day, in the form of the user’s language. The control has no calendar and no arrow buttons.
DtpFormatCustom 3 The format of CustomFormat.

See Also

  • Common members – the members this control shares with the package’s other controls
  • MonthView – a calendar that stays on the form
  • DTPicker – the control of the same name in the WinNativeCommonCtls package