Lists
Three widgets that hold children you append rather than a model: the list box, one row per child, the flow box, the same rows reflowed into as many per line as the width fits, and the calendar, a month grid you navigate with four arrows.
On GTK the rows of the first two are widgets you wrap yourself —
gtk_list_box_insert() puts a GtkListBoxRow around whatever you hand it —
and here a <gtk-list-box-row> is that wrapper in markup. All three take
selection-mode, and all four values of Gtk.SelectionMode answer on this
port: single, multiple, browse and none.
List Box
Section titled “List Box”One row per child. selection-mode is single by default and takes all
four values; show-separators draws the hairline between rows. A click
selects, Ctrl toggles and Shift extends from the row the
previous Shift-click kept as its anchor, exactly as
gtk_list_box_update_selection_full does. Activation is a single click
unless you set activate-on-single-click="false".
Enter activates the focused row and Ctrl+Space
toggles it. tab-behavior="item" turns the whole box into one tab stop
whose arrow keys move the cursor; the default, all, gives every activatable
row its own.
Flow Box
Section titled “Flow Box”The same rows, reflowed. It fills lines along orientation — horizontal,
which is the default here and the opposite of every GTK list — and starts a new
line when the next child will not fit. min-children-per-line and
max-children-per-line bound the count; GTK’s own default maximum is
seven, and row-spacing and column-spacing are the gaps.
homogeneous gives every child the same size.
The arrows move by visual position, not by index: from the last cell of a
full line, Left is the first cell of the next one and
↑ is one line up in the same column — the same distinction GTK draws
between GTK_MOVEMENT_VISUAL_POSITIONS and GTK_MOVEMENT_DISPLAY_LINES.
Calendar
Section titled “Calendar”A month grid with a heading and four arrows. date is the selected day as
YYYY-MM-DD, the form GDateTime serialises to, and it starts at today —
which is what gtk_calendar_init seeds the widget with. show-heading and
show-day-names are both on by default and show-week-numbers is off
until you ask, because the week numbers are a real grid column and turning
them on narrows the days.
The grid is always six rows of seven: GTK allocates day_number_labels[6][7]
whatever the month needs, so a five-row month still paints six and the height
does not jump. The arrows clamp the way g_date_time_add_months does — from the
31st you land on the 28th (or 29th), never on 3 March. A day belonging to
the next or previous month is clickable and pages with you; markDay() puts a
tint on a day of this month, and a mark survives a month that has no such day.
↑ ↓ ← → move the cursor,
Space selects the day it is on, and with Ctrl the same four
keys are the month and year arrows. The year, month and day properties
still work and are the 0-11 numbering the GIR uses for month — all three are
deprecated since GTK 4.20 in favour of date.
Related
Section titled “Related”- Models: the four views that draw a list model through a factory, where the rows come from the items rather than from your markup.
- Boxed Lists:
Adw.ActionRowand friends areGtkListBoxRowsubclasses, so a preferences group is a list box wearing Adwaita. - Controls: the drop-down, which is a list box with an inline popover instead of visible rows.
- Adwaita Storybook: the same three widgets in a live component browser you can poke at.