Calendars and dates
isolenui/kit/pickers.h holds a calendar, a range calendar and date fields that open one in a popover. Every date is a single int32_t day number, so storing, comparing and stepping dates is plain integer work.


In the galleryCalendarcalendarDate Pickerdate_picker
The pickers come in through isolenui/kit/kit.h, which includes isolenui/kit/pickers.h. Each picker is its own file in isolenui/src/kit, so an app that never calls one does not carry it. See the component kit.
Day numbers
A day is the count of days since 1970 01 01 on the proleptic Gregorian calendar, negative before it. k_no_day (INT32_MIN) means no date, and every picker shows an empty field or no selection for it. The helpers are all constexpr.
| Call | Does |
|---|---|
days_from_civil(y, m, d) | A year, a month from 1 and a day from 1 to a day number. |
civil_from_days(z) | A day number back to a civil of year, month and day. |
weekday_of(z) | 0 for Sunday up to 6 for Saturday. |
leap_year(y), month_days(y, m) | Gregorian leap years and the length of a month. |
month_index(y, m) | A month as one number, y * 12 + m - 1. |
month_first(index) | The day number of the first day of that month. |
today(u) | The local date. It reads the os clock at most once a minute and logs a warning and returns 0 if it cannot. |
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
// every date in the kit is an int32_t day number, days since 1970 01 01
constexpr int32_t launch = ui::days_from_civil(2026, 9, 23);
static_assert(ui::civil_from_days(launch).month == 9u);
static_assert(ui::weekday_of(launch) == 3u); // a wednesday, zero is sunday
static_assert(ui::month_days(2028, 2) == 29u);
// month indexes count months, year * 12 + month - 1
constexpr int32_t sept = ui::month_index(2026, 9);
static_assert(ui::month_first(sept) == ui::days_from_civil(2026, 9, 1));
static int32_t days_left(ui::ctx* u)
{
// the local date, read from the os at most once a minute
return launch - ui::today(u);
}Names
date_names holds the twelve month names, twelve short month names, seven weekday labels starting on Sunday, and the am and pm marks the time picker shows. date_names_english() returns the built in English table with two letter weekdays. Point a spec at your own table to translate the calendar. It must outlive the frame.
calendar
calendar(u, label, &day, spec) draws a month grid and writes the picked day. It returns true on the frame the day changes, from a click or from Enter or Space on the focused day. A null spec uses calendar_defaults().
The header has a back and a forward arrow and a caption per month. Clicking a caption cycles the grid from days to a month grid (3 across) to a year grid (20 years, 4 across) and back to days. The arrows step one month, one year or 20 years to match. Picking a month or a year drops one level back toward the days.
| Field | Default | Meaning |
|---|---|---|
names | English | The date_names table. Null also means English. |
week_start | 0 | The first column, 0 for Sunday and 1 for Monday. Taken modulo 7. |
today | k_no_day | The day marked with a dot. k_no_day reads today(u). |
min_day, max_day | k_no_day, INT32_MAX | The pickable span. Days outside it are disabled. The grid never walks past about 100 million days either side. |
disabled | null | A day_test that returns true for a day that cannot be picked. It gets user. |
mark | null | A day_paint called for each day of the month with its cell, to draw your own marks. It gets user. |
user | null | Passed to disabled and mark. |
months | 1 | 2 or more shows two months side by side. Two is the most. |
outside | true | Shows the days of the months before and after in a single month grid. Two months never show them. |
autofocus | false | The focus stop day takes focus when its scope opens, as in the date picker's popover. |
view | null | An int32_t* month index the caller owns. The calendar shows it and writes back where the user moved. Null keeps the view in the calendar's own state. |
The shown month follows the value. When the day changes from outside to a month that is not on screen, the view jumps to it. With no value it opens on today's month, clamped into the pickable span.
Keys
One day of the grid is in the tab order at a time: the focused day, else the value, else today, else the first pickable day. The grid claims these keys while it holds focus.
| Key | Day grid | Month and year grids |
|---|---|---|
| Left, Right | One day | One cell |
| Up, Down | One week | One row |
| Page Up, Page Down | One month, with Shift one year | A year of months or 20 years, with Shift twelve times that |
| Home, End | The start and end of the week row | The start and end of the row |
| Enter, Space | Picks the focused day | Opens the focused month or year |
A move that lands on a disabled day walks on in the same direction to the next pickable one, up to a year. A move off the shown months turns the view.
calendar_range
calendar_range(u, label, &from, &to, spec, &done) picks a span in two steps. The first pick sets both ends to that day and holds it as the anchor. While the anchor is held the span follows the hovered or focused day. The second pick writes the ordered pair and clears the anchor. It returns true whenever from or to changes, so on both picks. done is set true only on the frame of the second pick, and false on every other frame. It may be null.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
struct booking {
int32_t day = ui::k_no_day;
int32_t from = ui::k_no_day;
int32_t to = ui::k_no_day;
};
static bool weekend(int32_t day, void*)
{
const uint32_t wd = ui::weekday_of(day);
return wd == 0u || wd == 6u;
}
static void booking_view(ui::ctx* u, booking* b)
{
// one month, weeks start on sunday, every day pickable
if (ui::calendar(u, "delivery", &b->day)) {
// a day was clicked or picked with enter or space
}
// two months side by side, monday first, no weekends, nothing in the past
ui::calendar_spec spec = ui::calendar_defaults();
spec.week_start = 1u;
spec.months = 2u;
spec.min_day = ui::today(u);
spec.disabled = weekend;
bool done = false;
ui::calendar_range(u, "stay", &b->from, &b->to, &spec, &done);
if (done) {
// the second pick landed, from and to are ordered
}
}date_picker and date_range_picker
date_picker is a text_box plus a calendar button. The field shows the day through date_format and parses what is typed with date_parse when the text box commits. An empty field sets k_no_day. Text that does not parse, or a day the spec disables, keeps the old day and logs it. The button opens the calendar in a popover anchored below the field that flips and shifts to stay on screen. It also opens from Enter, Space or Alt Down while the button has focus. The popover takes focus onto the calendar and closes on a pick, Escape or a press outside it.
date_range_picker shows two fields and a two month calendar_range. It swaps the ends when the typed to falls before from, and closes on the second pick. Both return true on the frame the value changes.
date_spec field | Default | Meaning |
|---|---|---|
cal | calendar_defaults() | The calendar in the popover. Its limits and disabled also gate typed dates. |
order | date_ymd | date_ymd, date_dmy or date_mdy. |
sep | '-' | The separator date_format writes. Zero writes -. |
hint | "yyyy-mm-dd" | The text box label. Change it with order. |
date_format writes a four digit year and two digit month and day in the spec's order, returns the length, and writes an empty string for k_no_day or a buffer that is too small. date_parse takes any three runs of digits split by anything, so 2026.9.3 works for date_ymd. A year of one or two digits means 2000 plus it. A leading minus is a negative year, only in date_ymd. It returns false for a bad month or day.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
struct report_form {
int32_t due = ui::k_no_day;
int32_t from = ui::k_no_day;
int32_t to = ui::k_no_day;
};
static void report_view(ui::ctx* u, report_form* r)
{
// a text field that takes yyyy-mm-dd and a button that opens a calendar
ui::date_picker(u, "due", &r->due);
// two fields and a two month range calendar, written as dd/mm/yyyy
ui::date_spec spec = ui::date_defaults();
spec.order = ui::date_dmy;
spec.sep = '/';
spec.hint = "dd/mm/yyyy";
ui::date_range_picker(u, "period", &r->from, &r->to, &spec);
// the same format both ways, outside any widget
char text[32];
ui::date_format(text, sizeof(text), r->due, spec);
int32_t back = ui::k_no_day;
if (ui::date_parse(text, spec, &back)) {
// back == r->due
}
}kit.conf, date_picker needs calendar text_box. Turning off calendar or text_box takes the date picker off too, so a call to it fails to link rather than doing nothing.