On this page

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.

Calendar, a month grid to pick a day or a range, drawn by isolenCalendar, a month grid to pick a day or a range, drawn by isolen

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.

CallDoes
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.
day_math.cpp
#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.

FieldDefaultMeaning
namesEnglishThe date_names table. Null also means English.
week_start0The first column, 0 for Sunday and 1 for Monday. Taken modulo 7.
todayk_no_dayThe day marked with a dot. k_no_day reads today(u).
min_day, max_dayk_no_day, INT32_MAXThe pickable span. Days outside it are disabled. The grid never walks past about 100 million days either side.
disablednullA day_test that returns true for a day that cannot be picked. It gets user.
marknullA day_paint called for each day of the month with its cell, to draw your own marks. It gets user.
usernullPassed to disabled and mark.
months12 or more shows two months side by side. Two is the most.
outsidetrueShows the days of the months before and after in a single month grid. Two months never show them.
autofocusfalseThe focus stop day takes focus when its scope opens, as in the date picker's popover.
viewnullAn 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.

KeyDay gridMonth and year grids
Left, RightOne dayOne cell
Up, DownOne weekOne row
Page Up, Page DownOne month, with Shift one yearA year of months or 20 years, with Shift twelve times that
Home, EndThe start and end of the week rowThe start and end of the row
Enter, SpacePicks the focused dayOpens 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.

booking.cpp
#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 fieldDefaultMeaning
calcalendar_defaults()The calendar in the popover. Its limits and disabled also gate typed dates.
orderdate_ymddate_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.

report.cpp
#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
    }
}
In 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.

Last updated 6 October 2026