Pickers

Components · interactive

A calendar: a month of days, walked with the pointer or the keyboard.

Import

#include "gbui/widgets/datePicker.hpp"
#include "gbui/widgets/dateTimePicker.hpp"
#include "gbui/widgets/timePicker.hpp"

Example

DateField

dateField · Components · interactive

Nothing is downloaded until you press it.

DateFieldResult dateField(Ui& ui, const Interaction& input, std::string_view id, const Date& selected, DatePickerState& state, const DateFieldOptions& options = {});

A calendar behind a field, opened in a popover. The counterpart to colorField, and the same split: the inline calendar owns its space, this one borrows it. They share the state and the grid.

DatePicker

datePicker · Components · interactive

Nothing is downloaded until you press it.

DatePickerResult datePicker(Ui& ui, const Interaction& input, std::string_view id, const Date& selected, DatePickerState& state, const DatePickerOptions& options = {});

Draws a month and reports the day chosen, if any. Stateless like everything else: selected comes in, the state carries only what is being looked at. The arrow keys move by a day and Page Up and Page Down by a month, both skipping nothing — a day outside the bounds is drawn and dimmed rather than hidden, because a calendar with holes in it is harder to read than one with unavailable days in it.

DateTimeField

dateTimeField · Components · interactive

Nothing is downloaded until you press it.

DateTimeFieldResult dateTimeField(Ui& ui, const Interaction& input, std::string_view id, const DateTime& selected, DateTimeFieldState& state, const DateTimeFieldOptions& options = {});

A calendar and a clock behind one input. The pair belongs behind a single field far more often than beside each other on a page — a due date, a scheduled run, a deadline are one value, and asking for it in two controls invites half of it being filled in.

DateTimePicker

dateTimePicker · Components · interactive

Nothing is downloaded until you press it.

DateTimePickerResult dateTimePicker(Ui& ui, const Interaction& input, std::string_view id, const DateTime& selected, DateTimePickerState& state, const DateTimePickerOptions& options = {});

The two pickers, sharing one value.

TimePicker

timePicker · Components · interactive

Nothing is downloaded until you press it.

TimePickerResult timePicker(Ui& ui, const Interaction& input, std::string_view id, const Time& selected, TimePickerState& state, const TimePickerOptions& options = {});

Columns of hours, minutes and — when asked for — seconds, each scrolled to its own value. Columns rather than steppers because a time is picked far more often than it is nudged: "quarter past two" is two glances, and two number fields make it two edits. Each column keeps its selection in view, so opening the picker on 23:45 does not show midnight.

API

DateFieldOptions

Option	Type	Default	What it does
placeholder	std::string_view	"Select a date…"	Shown when nothing is chosen. A field with no value has to say so. Falling back to today would be a lie — "no date" and "today" are different answers, and a form that silently fills one in gets the other submitted.
pattern	std::string_view	"dd/MM/yyyy"	How the chosen date is written on the trigger. The same grammar formatDate takes, so the field reads the way the rest of the application writes dates.
clearable	bool	true	An x on the trigger that puts it back to nothing.
disabled	bool	false
width	float	200.0f
height	float	32.0f
dismissOnOutsideClick	bool	true
dismissOnEscape	bool	true

DatePickerOptions

Option	Type	Default	What it does
minimum	Date		Nothing before this, or after that, can be chosen. An invalid date means no bound.
maximum	Date
today	Date	Date::today()	Drawn with a dot under it. Invalid draws none.
locale	CalendarLocale		The first day of the week, twelve month names and seven day initials. Answered rather than solved — see the note above CalendarLocale.
showToday	bool	true	Marks today with a dot. A dot rather than a ring, so it cannot be mistaken for the selection or for where the keyboard is.
cellSize	float	30.0f	How big a day cell would like to be. A preference, not a promise: seven of these plus six gaps is a wide grid, and a calendar in a narrow column or a popover against the edge of a small window gets less than that. The cells shrink to fit rather than running out of the box, down to minimumCellSize and no further.
minimumCellSize	float	22.0f	The floor the cells shrink to. Below about this a two-digit day stops being readable, and a grid that has to scroll sideways is worse than one that is merely tight.
gap	float	2.0f

DateTimeFieldOptions

Option	Type	Default	What it does
placeholder	std::string_view	"Select a date and time…"
pattern	std::string_view	"dd/MM/yyyy HH:mm"	How the value is written on the trigger. One pattern for both halves, in the grammar formatDate and formatTime share — the date tokens are read by one and the clock tokens by the other, so dd/MM/yyyy HH:mm needs no separate spelling of where the date ends and the time begins.
clearable	bool	true	A small cross on the trigger once there is a value. Off where the field is required and empty is not an answer.
disabled	bool	false
width	float	240.0f
height	float	0.0f	Zero takes the design's control height.
dismissOnOutsideClick	bool	true
dismissOnEscape	bool	true

DateTimePickerOptions

Option	Type	Default	What it does
date	DatePickerOptions		The two halves, each configured exactly as it would be on its own — bounds, locale, pattern. Passed through rather than restated, which is what keeps this one calendar and one clock instead of a third of each.
time	TimePickerOptions		As above.
sideBySide	bool	true	The clock beside the calendar, or under it. Beside is the default because a calendar is wider than it is tall and the pair balances.
gap	float	16.0f

TimePickerOptions

Option	Type	Default	What it does
use24Hour	bool	true	Twelve-hour display with an AM/PM column. The value is always 0–23.
showSeconds	bool	false	A third column. Off, because most times are picked to the minute and a column nobody uses is a column in the way.
minuteStep	int	1	Coarser columns: 5 or 15 for a picker nobody needs to the minute.
secondStep	int	1	How the seconds column is filled: every second at 1, every fifteenth at 15. The step for seconds — not the second step.
minimum	Time	0, 0, 0	Times outside these cannot be chosen. Leave both at midnight for none — a range of nothing is not a range anybody wants.
maximum	Time	0, 0, 0
locale	ClockLocale		The words: AM, PM, and the separator. The pattern decides the shape and this decides the words, which is how one formatter covers Brazilian, American and ISO without a locale database.
height	float	176.0f
columnWidth	float	58.0f
rowHeight	float	28.0f