A Field Guide to GTK Widgets

This is the opening post of a series that works through GTK4 and Libadwaita together, one practical interface decision at a time. The posts are grouped around the things you actually build — a window, a list, a settings page — rather than the library a widget happens to ship in. Each post stands alone; together they’re meant to be the field guide the reference documentation isn’t. The problem with the reference The GTK4 documentation is genuinely good. Every widget has a page. Every property, signal, and method is listed. The class hierarchies are accurate and the prose is precise. If you already know which widget you need, the reference will tell you everything about it. ...

This is the first proper entry in A Field Guide to GTK Widgets — a series about which widget to reach for, when, and what bites you when you do. We start where every app starts: the window. Each post stands on its own, and the complete, runnable code for this one lives in the companion repo. Two windows, and the one you should reach for You sit down to write a GNOME app. The very first widget you need is the window, and the toolkit immediately hands you a choice it doesn’t explain: GtkApplicationWindow, from GTK itself, or AdwApplicationWindow, from Libadwaita. The reference describes both accurately and tells you nothing about which one you want. ...

This is the third entry in A Field Guide to GTK Widgets — a series about which widget to reach for, when, and what bites you when you do. We’re jumping straight to lists, ahead of layout and navigation, because it’s the material the reference documents worst. Each post stands on its own, and the complete, runnable code for this one lives in the companion repo. The list you’d build without thinking Say you’re showing a handful of tasks. The obvious way to do it doesn’t require reading any documentation at all: ...

This is the fourth entry in A Field Guide to GTK Widgets — a series about which widget to reach for, when, and what bites you when you do. The previous post got a list on screen with a factory it deliberately didn’t explain. This one explains it. The complete, runnable code lives in the companion repo. Where we left off The list-mindset post got a GtkListView on screen with just enough factory code to prove the model-driven approach worked, and it said so directly: setup builds a row’s widgets once, bind fills them in, and GTK recycles rows as you scroll — the same widgets get re-bound to different items instead of new rows being built for each one. That recycling is the entire reason GtkListView scrolls well through ten thousand rows without breaking a sweat, and it’s also the thing that breaks people’s mental model the first time they hit it, because nothing in the API shouts about it. You write bind once, it looks like a constructor, and it isn’t one. ...

This is the fifth entry in A Field Guide to GTK Widgets — a series about which widget to reach for, when, and what bites you when you do. The previous post got rows behaving correctly under recycling. This one is about which of them is selected. The complete, runnable code lives in the companion repo. Where we left off Two posts ago I wrapped the list store in a NoSelection and moved on, with a note that GtkListView won’t accept a bare GListModel and that NoSelection is how you say “no selection, and I mean it.” True enough as far as it went, but it was a placeholder. Time to take the wrapper seriously. ...

This is the sixth entry in A Field Guide to GTK Widgets, a series about which widget to reach for, when, and what bites you when you do. The previous post put selection in the model. This one adds search and sort underneath it. The complete, runnable code lives in the companion repo. Where we left off Last time the stack was two layers deep: a GListStore with a MultiSelection on top. I closed with a warning to look positions up through the model that handed them to you, because the store would stop agreeing with the view once a filter or sort model joined in, and this post adds both of them. ...

This is the seventh entry in A Field Guide to GTK Widgets, a series about which widget to reach for, when, and what bites you when you do. It picks up where the filter and sort post left off and replaces the workaround that one ended on. The complete, runnable code lives in the companion repo. Where we left off The last post built a task list four models deep: a GListStore at the bottom, then a FilterListModel, a SortListModel and a MultiSelection. It searched, hid done tasks and sorted three ways, and two parts of it were workarounds. ...