DTPicker class

A DTPicker is a date / time picker control. The inline field shows the current date or time formatted per Format; clicking the dropdown arrow opens a MonthView-style calendar for picking a new date, and dismissing the calendar updates Value.

Private Sub Form_Load()
    DTPicker1.Format = dtpShortDate
    DTPicker1.MinDate = DateSerial(2020, 1, 1)
    DTPicker1.MaxDate = DateSerial(2030, 12, 31)
    DTPicker1.Value = Date
End Sub

Private Sub DTPicker1_Change()
    Debug.Print "User picked: " & DTPicker1.Value
End Sub

The control inherits the focusable rect-dockable members from BaseControlFocusable — size, position, Anchors, Dock, Font, BackColor / ForeColor, Appearance, MousePointer / MouseIcon, ToolTipText, DragMode / DragIcon, Drag, Refresh, SetFocus, TabIndex / TabStop, ZOrder, CausesValidation, VisualStyles, hWnd, HelpContextID / WhatsThisHelpID.

Format and value

Format selects one of four display styles — long date, short date, time, or a custom format string supplied through CustomFormat. The inline value is always a Date, but Value is typed Variant because a CheckBox-equipped picker may have no date assigned (the user can clear the checkbox), in which case Value reads as Null.

The convenience accessors Year, Month, Week, Day, Hour, Minute, and Second decompose the current value into individual components; assigning to any of them rewrites Value with the requested component changed. The StartOfWeek property selects the first-day-of-week used by the calendar dropdown and by Week.

Custom format and callback events

When Format is set to dtpCustom, the CustomFormat string controls the display. The format syntax follows the Win32 GetDateFormat / GetTimeFormat picture string (e.g. "dddd, MMMM dd, yyyy"). Tokens enclosed in callback markers (X literals in the format) raise the Format, FormatSize, and CallbackKeyDown events so the application can render its own field content and respond to keyboard navigation across it.

Calendar appearance

When the dropdown calendar is shown, the CalendarBackColor, CalendarForeColor, CalendarTitleBackColor, CalendarTitleForeColor, and CalendarTrailingForeColor properties control the calendar’s colors via DTM_SETMCCOLOR. The CalendarShowToday, CalendarShowTodayCircle, CalendarShowWeekNumbers, and CalendarShowTrailingDates booleans toggle the corresponding MCS_… style flags on the embedded calendar.

hWndCalendar returns the Win32 handle of the dropped-down calendar window — useful for advanced customization. It is only valid between the DropDown and CloseUp events.

Properties

CalendarBackColor

The calendar dropdown’s background color. OLE_COLOR. Default: vbWindowBackground. Applied to the embedded month calendar via DTM_SETMCCOLOR / MCSC_MONTHBK.

CalendarForeColor

The calendar dropdown’s text color. OLE_COLOR. Default: vbButtonText.

CalendarShowToday

Whether the calendar dropdown shows the “Today: …” string at the bottom. Boolean. Default: True.

CalendarShowTodayCircle

Whether the calendar dropdown highlights today’s date with a circle. Boolean. Default: True.

CalendarShowTrailingDates

Whether the calendar dropdown shows the leading and trailing days of the previous and next month. Boolean. Default: True.

CalendarShowWeekNumbers

Whether the calendar dropdown shows a week-number column on the left. Boolean. Default: False.

CalendarTitleBackColor

The calendar dropdown’s title bar background color. OLE_COLOR. Default: vb3DFace.

CalendarTitleForeColor

The calendar dropdown’s title bar text color. OLE_COLOR. Default: vbButtonText.

CalendarTrailingForeColor

The text color used for trailing days from adjacent months when CalendarShowTrailingDates is True. OLE_COLOR. Default: vbGrayText.

CheckBox

Whether the picker includes a checkbox next to the date value. Boolean. Default: False. When True, the user can clear the checkbox to leave the picker without a value, in which case Value returns Null. Assigning Null to Value when CheckBox is False raises run-time error 35787 (“Can’t set Value to NULL when CheckBox property = FALSE”).

Changing this property at run time recreates the underlying Win32 window — the property cannot be flipped in the GWL_STYLE alone.

CustomFormat

The picture string used when Format is dtpCustom. String. Default: empty. Follows the Win32 GetDateFormat syntax (e.g. "dddd, MMMM dd, yyyy", "hh:mm:ss tt").

Day

The day-of-month component of Value. Integer (1–31). Reading returns the current day; assigning rewrites the date with the new day, raising run-time error 380 if the assigned value is out of range for the current month. See also DayCount.

DayCount

The number of days in the current value’s month. Long, read-only. Computed from Year and Month. Useful for bounds-checking before assigning Day.

DayOfWeek

The day-of-week the current Value falls on, as a VbDayOfWeek member (vbSunday through vbSaturday). Read-only.

Format

The display format. A member of DTPickerFormatConstants: dtpLongDate, dtpShortDate, dtpTime, dtpCustom. Default: dtpShortDate.

Hour

The hour component of Value, in 24-hour form. Integer (1–23 — note that 0 is rejected with run-time error 380 by the setter; read returns the live value). Reading is unrestricted.

hWndCalendar

The Win32 handle of the dropped-down calendar window. HWND, read-only. Valid only between the DropDown and CloseUp events; reads as 0 when the calendar is closed.

MaxDate

The upper bound of the navigable date range. Date. Default: 9999-12-31. Assigning a value lower than MinDate raises run-time error 35775. If the current Value exceeds the new MaxDate, Value is clamped down to MaxDate.

MinDate

The lower bound of the navigable date range. Date. Default: 1601-01-01. Assigning a value higher than MaxDate raises run-time error 35775. If the current Value is below the new MinDate, Value is clamped up to MinDate.

Minute

The minute component of Value. Integer (1–59 on assignment; 0–59 on read).

Month

The month-of-year component of Value. Integer (1–12). Assigning an out-of-range value raises run-time error 380.

RightToLeft

Note

RightToLeft is tagged [Unimplemented] and has no effect; reading and writing the property compiles but the underlying Win32 control’s RTL mode is not switched.

A Boolean.

Second

The seconds component of Value. Integer (1–59 on assignment; 0–59 on read).

StartOfWeek

Which day of the week is rendered as the leftmost column in the calendar dropdown. A VbDayOfWeek member. Defaults to the system’s first-day-of-week setting (resolved through vbUseSystemDayOfWeek).

UpDown

Whether the picker uses a spin-button widget instead of a dropdown calendar. Boolean. Default: False. When True, the user adjusts the date by clicking up / down arrows next to each field; the calendar dropdown is suppressed.

Changing this property at run time recreates the underlying Win32 window.

Value

The selected date / time. Variant. The default member.

Reads as a Date when the checkbox is checked (or CheckBox is False) or Null when the checkbox is cleared. Assigning Null when CheckBox is False raises run-time error 35787. Assigning a date outside [MinDate, MaxDate] raises run-time error 35773.

Assigning a numeric (non-Date) value implicitly converts via CDate. Assigning Empty is treated the same as assigning Null. Changing Value fires Change once the control is past its initialization phase.

Week

The ISO-style week-of-year for the current Value. Integer (1–53). The setter applies a delta of DateAdd("ww", …) so changing Week preserves the day-of-week within the week. Assigning out-of-range raises run-time error 380. Honors StartOfWeek when computing the week boundary.

Year

The year component of Value. Integer.

Events

CallbackKeyDown

Raised when the user presses a key while a custom callback field is focused. Lets the application interpret the key (e.g. arrow-up / arrow-down to cycle through enum values) and rewrite the date.

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

KeyCode
A KeyCodeConstants value identifying the pressed key.
Shift
A bitmask of ShiftConstants values.
CallbackField
The picture-string token identifying which callback field is focused.
CallbackDate
In / out — the current value the application can mutate before the event returns.

Change

Raised when Value has changed, either by user interaction or by code. Does not fire during the initial property-deserialization pass at form load.

Syntax: object_Change( )

Click

Raised on a mouse click inside the control’s rectangle.

Syntax: object_Click( )

CloseUp

Raised when the dropdown calendar closes — either by the user picking a date, by clicking outside the calendar, or by pressing Esc.

Syntax: object_CloseUp( )

DblClick

Raised on a double-click inside the control’s rectangle.

Syntax: object_DblClick( )

DragDrop

Inherited drag-drop event. See DragMode.

DragOver

Inherited drag-drop event.

Raised when the dropdown calendar opens. The handler can use hWndCalendar to customize the dropped-down calendar window.

Syntax: object_DropDown( )

Format

Raised for each custom callback field that needs rendering, when Format is dtpCustom and the CustomFormat string contains callback tokens.

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

CallbackField
The picture-string token identifying which callback field is being rendered.
FormattedString
Out — the application sets this to the text the picker should display in the field.

FormatSize

Raised before Format to ask how many character cells to reserve for the callback field. The picker uses the current Font to measure the rendered width.

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

CallbackField
The picture-string token identifying the callback field.
Size
Out — the application sets this to the expected character count.

GotFocus

Inherited focus event.

Initialize

Raised after the control’s window has been created and its properties initialised from persisted state. Fires once per form-load.

Syntax: object_Initialize( )

LostFocus

Inherited focus event.

MouseDown

Inherited mouse event.

Syntax: object_MouseDown( Button As Integer, Shift As Integer, X As Single, Y As Single )

MouseMove

Inherited mouse event.

MouseUp

Inherited mouse event.

OLECompleteDrag, OLEDragDrop, OLEDragOver, OLEGiveFeedback, OLESetData, OLEStartDrag

Inherited OLE drag-and-drop events. See OLEDropConstants for the OLEDropMode values.

Validate

Inherited validation event. Set Cancel to True to keep focus on the control.

Syntax: object_Validate( Cancel As Boolean )

See Also