PsDatePicker

An owner-drawn date picker: an editable date field with a calendar icon on the right, and a popup calendar the control owns. Typing a date and picking one from the calendar are two routes to the same SYSTEMTIME value.

The field is a real editing control — a borderless PsTextBox — so typing, the caret, selection, undo, paste and the right-click menu all behave the way a text box does. The calendar is a separate top-level window: a month grid with prev/next navigation, a clickable title that drills down from days to months to a decade of years, an optional second month side by side, week-start choice, a min/max range, a today ring, and an optional clickable "Today" band at the foot.

The host owns date format and parsing. The control stores a SYSTEMTIME and imposes no locale: you supply a Format callback that renders a date into field text and a Parse callback that resolves typed text back into a date. Without a Format callback it falls back to ISO yyyy-MM-dd so it is usable before you wire anything; without a Parse callback typed text is never accepted and only the calendar can set the date.

If you want a calendar embedded in your window rather than dropping out of a field, that is PsCalendar — no text box, no popup, and no pump obligation.

Repository: <https://github.com/PaulSquires/PsDatePicker>

---

What it looks like

Four pickers: a single month, two months side by side with the Today footer, a Monday-start calendar limited to a 60-day range, and an empty-allowed field with a host day painter.

---

Requirements

This control both wraps a real child and owns a second top-level window, so its file list is longer than most. Copy all of these:

It also needs the AfxNova framework on the include path (fbc -i "C:\dev" if AfxNova lives at C:\dev\AfxNova).

Include order

PsDatePicker.bi names types from PsBufferPaint, PsTipHost and PsTextBox and includes those headers itself, but the implementations must be pulled in ahead of it, in this order:

#include once "windows.bi"
#include once "AfxNova\CWindow.inc"
#include once "AfxNova\AfxStr.inc"
#include once "AfxNova\AfxGdiplus.inc"
using AfxNova

#include once "PsBufferPaint.inc"
#include once "PsPopupMenu.inc"
#include once "PsTextBox.inc"
#include once "PsDatePicker.inc"

PsDatePicker.inc includes PsTipHost.inc (and through it PsTooltip.inc) for you, so those two need no line of their own — but the files must be present.

Initialise GDI+

The control renders through GDI+. Bracket your message loop with AfxGdipInit and AfxGdipShutdown, or it draws nothing at all:

dim as ULONG_PTR gdipToken = AfxGdipInit()
' ... create windows, run the message loop ...
AfxGdipShutdown( gdipToken )

AfxGdipShutdown must come after every window is destroyed.

Do not name anything ok

GDI+ defines Ok = 0 as a Status enum value in namespace AfxNova, and your host almost certainly says using AfxNova. Any identifier of your own called ok becomes a duplicate definition the moment you adopt this control. Use bOK.

Message pump — PsDatePicker_FilterMessage is NOT optional

dim uMsg as MSG
do while GetMessage(@uMsg, null, 0, 0)
    if PsDatePicker_FilterMessage( @uMsg ) then continue do
    TranslateMessage @uMsg
    DispatchMessage @uMsg
loop

One call discharges three obligations at once:

1. it forwards to PsTextBox_FilterMessage, without which the field's right-click menu has no keyboard navigation and never closes on an outside click;
2. it dismisses the open calendar on Esc and on a click outside it — the popup never takes activation, so it cannot see either event itself;
3. it arms a one-shot guard so that an icon click which just dismissed the calendar does not instantly reopen it.

Skip the call and the calendar becomes a popup you can only close by picking a date.

Tab navigation into and out of the field needs no IsDialogMessage: PsTextBox handles VK_TAB itself, and the container carries WS_EX_CONTROLPARENT so that walk can see through it.

---

Quick start

dim as HWND hDate = PsDatePicker_Create( hMainWindow, IDC_MYDATE )
PsDatePicker_SetFont( hDate, hFont )                       ' caller-owned HFONT
PsDatePicker_SetFormatCallback( hDate, @MyFormat )         ' date -> field text
PsDatePicker_SetParseCallback( hDate, @MyParse )           ' typed text -> date
PsDatePicker_SetDateChangedCallback( hDate, @MyChanged )

dim as SYSTEMTIME stNow
GetLocalTime( @stNow )
PsDatePicker_SetDate( hDate, PsDatePicker_MakeDate( stNow.wYear, stNow.wMonth, stNow.wDay ) )

' Size it to whatever it asks for, then show it.
dim as long w, h
PsDatePicker_GetIdealSize( hDate, w, h )
SetWindowPos( hDate, NULL, 20, 20, w, h, SWP_NOZORDER )
ShowWindow( hDate, SW_SHOW )

And the callbacks it wires:

' date -> display text
sub MyFormat( byval hCtrl as HWND, byval pDate as SYSTEMTIME ptr, byref sOut as DWSTRING )
    if pDate = 0 then sOut = "" : exit sub
    sOut = str(pDate->wYear) & "-" & format(pDate->wMonth,"00") & "-" & format(pDate->wDay,"00")
end sub

' typed text -> date. Return FALSE for anything you cannot accept.
function MyParse( byval hCtrl as HWND, byval sText as DWSTRING, byval pDate as SYSTEMTIME ptr ) as boolean
    if pDate = 0 then return false
    dim as string s = trim( sText )
    dim as long y = valint( mid(s, 1, 4) )
    dim as long m = valint( mid(s, 6, 2) )
    dim as long d = valint( mid(s, 9, 2) )
    if (m < 1) orelse (m > 12) then return false
    if (d < 1) orelse (d > PsDatePicker_DaysInMonth( y, m )) then return false
    *pDate = PsDatePicker_MakeDate( y, m, d )
    return true
end function

sub MyChanged( byval hCtrl as HWND, byval pDate as SYSTEMTIME ptr, byval bHasDate as boolean )
    if bHasDate = false then exit sub          ' the field was cleared
    ' pDate is the new value
end sub

---

Concepts

The handle is a real HWND

PsDatePicker_Create returns an ordinary child window. Position and size it with SetWindowPos, show it with ShowWindow, destroy it with its parent. It is created 0×0 and invisible; nothing appears until you size and show it.

Format and Parse must round-trip

This is the one wiring mistake that produces no error message. On commit the control calls your Parse callback with whatever is in the field; if Parse returns FALSE the field silently reverts to the last text the control wrote — which is exactly what it looks like when the user typed nothing at all. So if your Format produces "Jul 24, 2026" and your Parse only understands digits, every commit made after the calendar or a setter wrote the field will fail and revert.

Assert Parse( Format( d ) ) = d for a few dates when you wire the pair.

Focus lives two levels down

The field is a PsTextBox, whose own input window is a RichEdit. GetFocus() = hCtrl is never true. Ask PsDatePicker_HasFocus instead.

Programmatic setters are silent

SetDate, ClearDate, SetRange and ReformatText never fire DateChangedCallback. It fires only for user action: a typed commit (Enter, or focus leaving the field) or a calendar pick. That is what lets you call a setter from inside your own handler without re-entering it.

DropDownCallback is the deliberate exception: it reports a window-state transition rather than a value change, so it fires for PsDatePicker_DropDown and PsDatePicker_CloseUp too.

Rects are derived, never set

rcFrame, rcField, rcDiv and rcIcon are computed from the client rect on the next paint after anything invalidates the layout. You cannot assign them; you read them back with GetFrameRect / GetFieldRect / GetIconRect, each of which returns FALSE while the control has never been given a non-empty size.

The layout is:

icon    = the right nIconWidth pixels, full height
divider = nDividerThick pixels immediately left of the icon
field   = from left + nCornerRadius to the divider,
          inset top and bottom by nBorderThick

The field is inset by the corner radius so the frame's rounded left corners survive underneath the child's square rectangle. The PsTextBox child is moved to rcField on every layout.

The calendar is a popup the control owns

It is created lazily — PsDatePicker_GetCalendarHandle returns 0 until the first open — and destroyed with the control. It is a WS_POPUP that never takes activation, so your window stays foreground and keystrokes keep flowing to it; that is why dismissal runs through the pump filter, and why the popup polls the foreground window (every 100 ms) to close itself on alt-tab.

Only one picker's calendar is open at a time process-wide.

Every open re-seeds the calendar from the control: week start, month count, footer, range, the selected date, and today. The view always reopens on the days grid, and the displayed month is the selected date's month, or today's when there is no date.

Sizes are DPI-scaled once, at Create

The icon width, field padding, vertical padding and corner radius are scaled for the monitor's DPI when the control is created; the calendar's own metrics are scaled when the popup is created. Every setter afterwards takes raw pixels — scale them yourself. The border and divider thicknesses are rules, not sizes, and are never scaled: a hairline stays a hairline.

---

Behaviour and limits

• The pump filter is mandatory. See Requirements.
• The calendar is mouse-driven for selection. F4, Alt+Down and Down open it (and close it again); Esc, an outside click and alt-tab dismiss it. There are no arrow keys inside the popup — you cannot move the selection from the keyboard.
• nMonthCount is 1 or 2. Anything else is clamped. Only the left panel carries the chevrons and the interactive title; the right one is a static caption.
• The drill-down uses the left panel only. In two-month mode the right half is blank chrome while the months or years grid is showing.
• The day grid is a fixed 6×7. The popup never changes height between months.
• Month names and weekday abbreviations in the calendar chrome are English and cannot be replaced. Only the field's text goes through your Format callback. (PsCalendar takes host-supplied names if you need localized chrome.)
• The range clamps, it does not refuse. SetDate and a typed commit both clamp into [min, max]; an inverted min/max pair is swapped rather than left unsatisfiable.
• Empty is a legal value unless you turn it off with SetAllowEmpty(false), in which case clearing the field reverts to the last valid text on commit.
• There is no keyboard route to the Today footer — it is a click target.
• CS_DBLCLKS is off. A rapid second click on the icon is a legitimate close-then-reopen and arrives as two WM_LBUTTONDOWN.
• The tooltip is calendar-only. There is no tip on the field or the icon, and none at all until you set a TooltipCallback.

---

API reference

Creation, children, focus

Value

All silent; none of these fire DateChangedCallback.

Calendar behaviour

Layout and appearance

Every size below is in raw pixels — scale for DPI yourself.

Geometry

Colours

Callback registration

Tooltips

The calendar's day-cell tip is tracked: the control resolves the text, positions the tip on the cell and shows it immediately, rather than letting a dwell decide. It is also lazy — nothing is built until a day cell actually asks for a tip, and nothing is built at all unless a TooltipCallback is set.

The mode is remembered on the picker, not the popup. The popup's tip is destroyed with the popup, so a mode stored there would revert to the default the second time a user opened the calendar; setting the mode applies to the current popup if there is one and to every later one.

Host message pump

Date helpers

Pure functions, safe to call before any control exists. The serial is a day count that makes every month and year rollover fall out of ordinary arithmetic.

Test seam and render probes

These drive the real calendar painter into an offscreen buffer, so a host that replaces the day painter can assert its render is sane. They take the calendar handle, not the control's.

A tone floor copied from another control is meaningless: the number depends on what else is inside the rect.

---

Colors

PSDATEPICKER_COLORS is a flat struct of COLORREF fields, all carrying defaults for a dark theme. Read-modify-write it with GetColors / SetColors.

Frame and field

Icon cell

Calendar chrome

Day cells

Today footer

Only used when SetShowTodayFooter is on. The band has no fill of its own — it sits on CalBackColor — so these three are the caption colour alone.

Keep DayColorAdjacent and DayColorDisabled clearly apart. An adjacent day is clickable and navigates to its month; a disabled day does nothing. If the two are close in luminance, a range like "the next 60 days" shows most of the month greyed with no way to tell which greys can be clicked. The defaults sit far apart deliberately.

Day-cell precedence

Background first: selected → hot (and only when not disabled) → nothing. Then the today ring, drawn only when the cell is not selected. Then the number:

disabled > selected > hot > adjacent > weekend > ordinary

Note that disabled beats selected here, and that hot beats adjacent — an out-of-month day under the cursor takes the hot colour.

---

Callbacks

Every typedef carries the DTP_ prefix.

DTP_ParseCallbackFunc

function MyParse( byval hCtrl as HWND, byval sText as DWSTRING, byval pDate as SYSTEMTIME ptr ) as boolean

Called on commit — Enter, or focus leaving the field — with the field's current text. Fill *pDate and return TRUE, or return FALSE for text you cannot accept, in which case the field reverts to the last text the control wrote. Empty text never reaches you: the control handles it according to SetAllowEmpty. A date you return is clamped into the range afterwards.

sText is byval — copy that signature exactly. Declaring it byref … as const DWSTRING and then copying it (dim as DWSTRING c = sText, the obvious first line of any parser) corrupts the process heap: AfxNova's DWSTRING copy constructor is not const-correct. The crash lands far from the cause, often much later and in unrelated code.

DTP_FormatCallbackSub

sub MyFormat( byval hCtrl as HWND, byval pDate as SYSTEMTIME ptr, byref sOut as DWSTRING )

Render a date into field text. Called whenever the control writes the field — a setter, a calendar pick, a successful parse, ReformatText, or SetFormatCallback itself — and also for the Today footer's caption, so the band matches the field above it. With no callback the control falls back to ISO yyyy-MM-dd.

DTP_DateChangedCallbackSub

sub MyChanged( byval hCtrl as HWND, byval pDate as SYSTEMTIME ptr, byval bHasDate as boolean )

User action only — a typed commit or a calendar pick (including the Today footer, which routes through the same commit path, so it fires exactly once). Every programmatic setter is silent. It fires only when the value actually changed. bHasDate is FALSE when the user cleared the field, and pDate then holds the stale previous value — test the flag, not the pointer.

DTP_DropDownCallbackSub

sub MyDropDown( byval hCtrl as HWND, byval isOpen as boolean )

The calendar opened or closed, programmatic opens included. The opening edge runs before the calendar is created or seeded, which makes it the just-in-time hook for setting a range or a month count that depends on current state. If the popup fails to be created, the closing edge fires immediately so the pairing holds.

DTP_PaintCallbackSub

sub MyPaint( byval p as PSDATEPICKER_PAINTINFO ptr )

Replaces the built-in painter for the editing box — frame, divider and icon. It never draws the date text; the RichEdit child does that, on top of whatever you paint. The buffer's background has already been filled with BackColor before you are called.

A callback that fills a rectangle covering the whole control erases everything already drawn. Draw your additions, not a background.

PSDATEPICKER_PAINTINFO

DTP_DayPaintCallbackSub

sub MyDayPaint( byval p as PSDATEPICKER_DAYPAINTINFO ptr )

Draws one day cell, replacing the built-in day painter for that cell. The cell's background has already been filled with CalBackColor. This is the granular hook — availability shading, appointment dots, per-day colouring.

PSDATEPICKER_DAYPAINTINFO

DTP_MessageCallbackFunc

function MyMessage( byval m as PSDATEPICKER_MESSAGEINFO ptr ) as boolean

Observes messages arriving at the container and at the embedded field. Return TRUE to suppress the control's own handling.

The return value is ignored for four messages, because each has already changed state by the time you are offered it, so suppressing it could only leave the control disagreeing with what the system has done: WM_KILLFOCUS (a claimed kill-focus would skip the typed-text commit), WM_LBUTTONUP (a claimed button-up would strand state the control has to unwind), WM_MOUSELEAVE (the hot flag and its repaint happen regardless) and WM_ENABLE (the enabled flag, the field colours and the repaint happen regardless).

PSDATEPICKER_MESSAGEINFO

DTP_TooltipCallbackFunc

function MyTooltip( byval t as PSDATEPICKER_TOOLTIPINFO ptr ) as boolean

Supply the tip for the day under the cursor. Fill outText and return TRUE; return FALSE — or leave outText empty — for no tip on that day. Called once per day cell as the cursor moves between cells, not once per mouse move.

Setting this callback is what turns tooltips on. With none set, no tip window is ever created.

PSDATEPICKER_TOOLTIPINFO

---

Constants

Week start

Calendar view

Hit-test parts

Returned inside DTP_HITRESULT by the calendar's internal hit test, and the vocabulary the nPart arguments of the render probes echo.

PsDatePicker_HitTest on the control is a different, much smaller vocabulary: 1 for the icon cell, 0 for everything else.

Tooltip modes

Cross-window messages

Sent by the popup to the control. Listed because they pass through a host message callback, not because a host should send them.

Layout defaults

Sizes are DPI-scaled at Create unless noted.

Mouse wheel

Over the open calendar, a wheel notch away from the user shows the previous month; toward the user shows the next. Sub-notch deltas from a precision touchpad accumulate rather than being dropped, and a notch stops at a disabled chevron.

---

Related controls

• PsTextBox is the editing field. Its docs cover the text behaviour you inherit — caret, selection, undo, paste, the right-click menu — and the reason PsPopupMenu is on the file list. Its FilterMessage obligation is discharged for you by PsDatePicker_FilterMessage.
• PsTooltip is the optional tip backend selected by PsDatePicker_SetTooltipMode. Style it through the handle PsDatePicker_GetPsTooltipHandle hands back.
• PsCalendar is the embedded, non-popup calendar: the same grid and drill-down as a normal child control, with host-supplied month names, keyboard selection, and no pump obligation.

GPL-3.0.

Licence

Mozilla Public License 2.0.

MPL-2.0 is file-level copyleft, chosen deliberately for a drop-in control:

• You may use this in closed-source software, commercial or otherwise. §3.2 permits static linking with no additional conditions.
• If you modify these files, publish those files' changes. The obligation is per-file — your own sources are unaffected however tightly they are combined with these.
• The Exhibit B "Incompatible With Secondary Licenses" notice is not applied, which keeps this GPL-compatible.