DEV Community: Justin - FromTheArchitect

Sortable Columns in GTK4: ColumnView, ColumnViewSorter and GridView

Justin - FromTheArchitect — Tue, 27 Oct 2026 06:07:14 +0000

This is the eighth 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 taught the store to report its own changes. This one puts a table and a grid on top of it. The complete, runnable code lives in the companion repo.

Where we left off

Every view in this series so far has been a ListView: one row per item, one widget per row. The model stack under it grew from a store and a selection to four layers, and the last post made the store report when an item changed so the sort model above it could keep up.

This post swaps the view. The example is a small photo library, twelve photos from three cameras, shown two ways. One is a ColumnView, a table with a header you can click to sort, columns you can drag wider or narrower, and columns you can drag into a different order. The other is a GridView of tiles. They sit in an AdwViewStack with a switcher in the header bar, and underneath they share one model stack.

A table is a list with columns

The thing that made ColumnView click for me is that it isn't a different kind of view. It's a ListView where each row is split into cells, and each column brings its own factory to build its cell. There's still one model, and each item in it is still one row.

So the factory code from the factory post carries over almost unchanged. The one difference is the object that setup is handed. A ListView passes a ListItem. A ColumnView passes a ColumnViewCell, which has the same item property, so expressions rooted at it read exactly as they did before. ColumnViewCell arrived in GTK 4.12, so that's the floor for this post, and in gtk4-rs it needs at least the v4_12 feature. The companion code turns on gnome_50, which covers it.

fn label_factory(
    xalign: f32,
    label: impl Fn(gtk::Expression) -> gtk::Expression + 'static,
) -> gtk::SignalListItemFactory {
    let factory = gtk::SignalListItemFactory::new();

    factory.connect_setup(move |_, cell| {
        let cell = cell.downcast_ref::<gtk::ColumnViewCell>().unwrap();

        let widget = gtk::Label::builder()
            .xalign(xalign)
            .ellipsize(pango::EllipsizeMode::End)
            .build();
        cell.set_child(Some(&widget));

        label(gtk::ColumnViewCell::this_expression("item").upcast()).bind(
            &widget,
            "label",
            Some(cell),
        );
    });

    factory
}

All five columns in the example are labels, so one helper builds every factory and each column passes in the expression for its own text. Name is the simplest:

pub fn name() -> gtk::ColumnViewColumn {
    let factory = label_factory(0.0, |item| item.chain_property::<Photo>("name").upcast());

    gtk::ColumnViewColumn::builder()
        .title("Name")
        .factory(&factory)
        .sorter(&gtk::StringSorter::new(Some(property("name"))))
        .expand(true)
        .resizable(true)
        .build()
}

A ColumnViewColumn bundles the header title, the cell factory, the sorter that clicking the header will use, and how the column sizes itself. Photo is a GObject with five properties for the same reason Task became one two posts ago: the sorters and expressions find their data by property name.

Sizing columns

expand hands a column a share of any spare width. I gave it only to Name, so when the window grows, Name gets wider and the rest stay at their natural width. If two columns expanded they'd split the spare width between them.

resizable lets the user drag the column's right edge, and it's why every label in the factory ellipsizes. A label that can't ellipsize asks for its whole text as its minimum width, so the longest file name in the column would set how narrow Name could go. With ellipsizing on, the minimum drops to a few characters and the rest of the name becomes an ellipsis.

fixed-width pins a column. I set .fixed_width(96) on Size and left it out of the resizable ones, so that column never changes width however the others move. The numbers line up on the right because Size's labels get an xalign of 1.0 from the factory helper; the width has nothing to do with it.

Dragging a header sideways to reorder columns needs nothing at all. Columns are reorderable by default. The reorderable property belongs to the ColumnView itself, so turning it off locks every column in place.

Clickable headers need wiring

Each column has a sorter, and clicking its header shows a sort arrow. On its own, that's all that happens, and the rows stay where they are.

What the click changes is the ColumnView's own sorter, a ColumnViewSorter that it builds out of the columns' sorters. A sorter only reorders anything when a SortListModel is using it, and nothing has connected one to the other yet. Making that connection forces an order on the construction code. The view has to exist before you can ask for its sorter, and the sort model has to exist before the view can be given its model. So the view is built first, empty:

let column_view = gtk::ColumnView::new(None::<gtk::SelectionModel>);
column_view.append_column(&columns::name());
// ...camera, taken, size, rating

let sorter = column_view
    .sorter()
    .and_downcast::<gtk::ColumnViewSorter>()
    .unwrap();
let sort_model = gtk::SortListModel::new(Some(photos.model().clone()), Some(sorter.clone()));
let selection = gtk::MultiSelection::new(Some(sort_model));
column_view.set_model(Some(&selection));

sorter() returns a plain gtk::Sorter. The downcast is only needed if you want to ask it which column is sorted, which the example does for its status bar.

The starting sort is newest first, set in code with column_view.sort_by_column(Some(&taken), gtk::SortType::Descending). I assumed that was the same thing as a user clicking the Taken header twice. On a fresh view it is. The difference only shows once the user has built up a stack of clicks, and it turned up in the log.

Sort on the value behind the label

Taken shows a date and Size shows "9.1 MB", but neither column's sorter reads what's on screen. Each one is a NumericSorter on the raw property: Unix seconds for Taken, bytes for Size. The label is produced separately, by a closure on the expression:

item.chain_property::<Photo>("size")
    .chain_closure::<String>(glib::closure!(|_: Option<glib::Object>, size: u64| {
        glib::format_size(size).to_string()
    }))

The sample sizes straddle 10 MB on purpose. Sort the formatted strings and "12.4 MB" comes before "9.1 MB", because "1" sorts before "9". Dates fare worse, since "1 Mar 2025" would sort next to "1 Sep 2025". StringSorter's filename collation (gtk::Collation::Filename, GTK 4.10) compares embedded numbers as numbers and would fix that pair, but it would still put "1.2 MB" ahead of "900 kB". Keeping the stored value raw and formatting only for display means the column sorts correctly with no extra code.

What the sorter does with each click

The example logs the sorter's full list of sort columns every time it changes. Starting from newest first, I clicked Camera, Taken twice, Size and Rating, in that order:

sorter changed: Sorted by Camera ascending (sort columns: ["Camera Ascending", "Taken Descending"])
sorter changed: Sorted by Taken ascending (sort columns: ["Taken Ascending", "Camera Ascending"])
sorter changed: Sorted by Taken descending (sort columns: ["Taken Descending", "Camera Ascending"])
sorter changed: Sorted by Size ascending (sort columns: ["Size Ascending", "Taken Descending", "Camera Ascending"])
sorter changed: Sorted by Rating ascending (sort columns: ["Rating Ascending", "Size Ascending", "Taken Descending", "Camera Ascending"])

A ColumnViewSorter keeps a stack. The column you click goes to the front and every column clicked before it stays behind as a tie-breaker, most recent click first. After the Camera click, photos from the same camera came out newest first, because Taken was second in line.

Clicking the front column flips its direction. Clicking one further back brings it to the front ascending, whatever direction it had before. My log can't tell those two apart (Taken was descending when I clicked it, and would have come back ascending either way), so that rule comes from GTK's source.

In a scratch test I called sort_by_column for Taken, then Size, then Camera, and each time n_sort_columns() came back as 1. Each call wipes the stack and starts again with the one column you pass, so with nothing behind Camera, ties fell back to the order the photos sit in the store.

None of that shows in the header, which only ever draws an arrow on the front column. For a photo library the stacking is what you'd want: sort by camera and each camera's photos are still in date order from the last click.

If your app restores a saved sort on startup with sort_by_column, it can only ever restore one column. That includes the recipe in the ColumnViewSorter docs (the restore example near the end), which calls sort_by_column once per saved column, working from the back of the stack forward. Each call wipes the one before, so only the last column it passes survives. The function that pushes a column onto the stack, the one a header click uses, is private to GTK.

Keeping the table sorted when a photo changes

Header sorting is a SortListModel underneath, so it inherits the problem the last two posts dealt with: SortListModel has no watch-items, and that's still true in GTK 4.24. Sorted by Rating, a photo you rate up stays where it was unless something tells the sort model to look again.

The first version of the Rate up button ended with sorter.changed(gtk::SorterChange::Different) on the ColumnViewSorter. I wrote it from habit, then remembered the correction on the filter and sort post: that call leaves expression sorters out of order. Rating's sorter is a NumericSorter, so I expected the button not to work. It worked. That was enough of a surprise to test properly, rating up the five lowest photos and checking the order after each change:

What the SortListModel holds	After changed(Different)
NumericSorter on rating	out of order
MultiSorter holding that NumericSorter	out of order
ColumnViewSorter holding that NumericSorter	in order

Same NumericSorter in all three, GTK 4.22.5, at 12 photos and at 1,200. Wrapped in a ColumnViewSorter, it re-sorts. Used directly or inside a MultiSorter, it doesn't. GTK's source has the answer: SortListModel reuses its cached sort keys when the new ones look compatible, and a NumericSorter's keys still hold the old rating. ColumnViewSorter has no keys of its own, so its comparisons always see the live value. GTK doesn't document any of that, so I wouldn't build on it. It does mean a table can look fine with the button-handler approach and then go wrong the day the same sorter is reused in a plain list.

The example doesn't rely on it. The store from the last post comes across as PhotoStore, and Rate up just sets the rating:

rate_up.connect_clicked(move |_| {
    for photo in selected_photos(&model) {
        photo.set_rating((photo.rating() + 1).min(5));
    }
});

selected_photos copies the selected items into a Vec before the loop starts. Each set_rating re-sorts the model and moves positions around, so walking the selection's bitset live would skip or repeat photos.

The store hears notify::rating and emits items_changed for that photo, and the sort model re-places it under whichever column is in front. What changes in a table is the watch list. The task list's sorters read three properties. Here every column sorts on a different property, so the store watches all five, and a column whose property was left off would drift out of order without any warning.

The same photos as a grid

The GridView takes the same selection model as the table:

let grid_view = gtk::GridView::new(Some(selection.clone()), Some(tile::factory()));
grid_view.set_min_columns(2);
grid_view.set_max_columns(6);

Its factory is a plain ListItem factory, one tile per photo, with an icon, the name and the star rating bound by expressions. GridView works out how many tiles fit across, between the minimum and maximum you give it, and wraps the rest onto new rows. There are no columns to configure in the table sense and no headers, so the grid can't change the sort itself. It shows whatever order the model has.

My photo app, Moments, leans on that fitting for zoom. Its photo grid allows anywhere from 2 to 20 columns, and zooming swaps in a factory whose cells ask for a bigger or smaller square, from 96 up to 320 pixels. Nothing sets a column count anywhere; the grid works it out again from the new tile size.

Because both views read the same MultiSelection, they share the sort and the selection. I selected three photos in the table, switched to the grid, and the same three were highlighted, in the same positions. Click Rating in the table and the grid reorders too. Add photo appends to the store, and under the starting sort the new photo shows up first in both views.

Sharing one selection model is fine even with both views on screen at once. Here only one is visible, but the hidden one stays subscribed to the model, so every change reaches both. I haven't measured what that costs at scale; with twelve photos it's nothing.

Sharp edges

Header clicks do nothing until you wire the sorter. Hand column_view.sorter() to a SortListModel under the selection, which means building the view before its model.

Sort on stored values, format for display. A NumericSorter on bytes or timestamps, and a closure on the expression for the label.

Ellipsize labels in resizable columns. Otherwise the longest label sets the narrowest the column can go.

sort_by_column replaces the sort; a header click adds to it. The tie-breaker stack only builds up through clicks, and only a click on the front column flips its direction.

Report item changes from the store. changed() on a ColumnViewSorter re-sorted in my tests and the same NumericSorter used directly didn't, which turned out to be sort-key caching in SortListModel. I'd rather not have a table's correctness hang on which sorter happens to sit on top, so the store emits items_changed for every property a column sorts on.

Next up

The table is flat: every photo is one row at the same level. The next post adds hierarchy with GtkTreeListModel and GtkTreeExpander, which is where people still land on Stack Overflow answers about the deprecated GtkTreeView. A ColumnView is also where a tree is most useful, with an expander in the first column and sortable columns beside it.

The runnable version of this example is in the companion repo: cd 07-columns-grids && cargo run. One widget at a time. See you in the next one.

Assisted by Claude Code (claude-opus-5-5). The experiments, bugs and conclusions are mine. How I work with AI tools is in The AI pair programmer.

Keeping a GTK4 SortListModel in Order When Items Change

Justin - FromTheArchitect — Fri, 23 Oct 2026 10:00:00 +0000

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.

Hiding done tasks had to be a BoolFilter with watch-items switched on, because watch-items only sees properties through filters built from expressions. A CustomFilter was invisible to it. Sorting had nothing at all. SortListModel has no watch-items of its own, so the Mark done button finished by calling sorter.changed(gtk::SorterChange::Different) to make it look again.

That call only helps when the change goes through that button. A sync from another device or an undo would set a task's done property somewhere else, and the list would sit out of order until something happened to re-sort it.

It also bothered me as an engineer. SorterChange::Different tells the sort model that any comparison it has made might now be wrong, so it sorts the whole list again to place the one task that changed. On ten tasks nobody would notice. A photo library or an email folder is the kind of list these models exist for, tens of thousands of items, and there it's a full re-sort every time someone stars a photo or reads a message.

This post moves the job down to the store. When a task changes, the store says so, and every model above it re-checks that one task. watch-items goes back to its default of off, the sorter call is deleted, and "hide done" can be a closure again.

Reporting a change in place

Every list model has an items-changed signal carrying three numbers: a position, how many items were removed there, and how many were added. Each model in the stack listens for it on the model below and re-emits it in its own positions, which is how an appended task reaches the view already filtered and sorted.

Nothing stops a model from emitting items_changed(pos, 1, 1) for an item that hasn't gone anywhere. It reads as one item removed at pos and one added in its place. When the added item is the same object as the removed one, the message is that this item changed and should be looked at again. The filter model runs it back through the filter, and the sort model finds where it belongs now. Neither needs to know which property changed.

A GListStore won't send that for you. It knows when you insert or remove, but it has no idea when something inside an item it holds changes, so that part has to be wired up by hand.

What gets wired up is the observer pattern twice over. The store observes each task through GObject's property notifications, and the models above observe the store through items-changed. In between, the store translates "this task's done property changed" into "the item at position 4 changed", the only kind of event a list model understands.

A store that reports

The companion code wraps the store in a small Rust struct called TaskStore. Tasks go in through it, so it can connect handlers on the way:

pub fn append(&self, task: &Task) {
    let ids = [
        task.connect_title_notify(self.reporter("title")),
        task.connect_done_notify(self.reporter("done")),
        task.connect_priority_notify(self.reporter("priority")),
    ];
    self.handlers.borrow_mut().insert(task.clone(), ids);
    self.store.append(task);
}

connect_done_notify and its siblings come from the #[property] derive, one per property, and each fires only for its own property. The handler finds the task's position and reports it:

fn reporter(&self, property: &'static str) -> impl Fn(&Task) + 'static {
    let store = self.store.downgrade();
    move |task| {
        let Some(store) = store.upgrade() else {
            return;
        };
        if let Some(position) = store.find(task) {
            println!("{property} changed on {:?}: items_changed({position}, 1, 1)", task.title());
            store.items_changed(position, 1, 1);
        }
    }
}

The repo's version also has a switch for turning reporting off, which comes up later.

The handler holds the store weakly. A GObject owns the handlers connected to it, so each task owns its handler. If the handler held the store strongly, the store would hold the task, the task its handler, and the handler the store again. It's the same cycle the last post found in the selection handlers, one layer further down.

The other choice is which properties to watch. The answer is every property a filter or sorter reads: title for the search and the Title sort, done for "hide done" and Open first, priority for the Priority sort. The first version of the companion code watched only done and priority, because those were the two the buttons changed. Nothing in the app renames a task, so it passed every test, but a rename under the Title sort would have left the task in the wrong place with nothing in the log to say so.

GNOME Contacts makes the same call in contacts-store.vala. It listens for property changes on each contact as it's added and ignores all of them except the display name and the favourite flag, the two its sorting and filtering depend on.

Each report costs a store.find(task), which walks the store comparing pointers. For a task list that's nothing. For a very long list you'd keep a map from item to position instead.

Taking a task out

Adding handlers is the easy half. When a task leaves the store its handlers have to go too:

pub fn remove(&self, task: &Task) {
    if let Some(position) = self.store.find(task) {
        self.store.remove(position);
    }
    if let Some(ids) = self.handlers.borrow_mut().remove(task) {
        for id in ids {
            task.disconnect(id);
        }
    }
}

This is where the observer pattern usually goes wrong. Forgetting to unsubscribe has a name, the lapsed listener. Here a deleted task that's still referenced somewhere else, an undo stack say, would keep firing its handler every time it changed, and each time the handler would search the whole store for a task that isn't there. Because the handler holds the store weakly, that's wasted work rather than a leak. With a strong reference, every deleted task would keep the entire store alive.

To check it, the companion app's Task logs a line when it's freed. Deleting a task printed it straight away, and closing the window printed one for every task left, so nothing was holding on.

What the log showed

The companion app logs each items-changed at the bottom of the stack and at the top, every row bind and unbind, and what's still selected after each change. I ran it through the cases the last post had trouble with.

"Hide done" is a CustomFilter again, and watch-items is off. With "hide done" switched on, marking a task done removed the row. So did the Simulate sync button, which completes the first open task in store order without going near the selection or any handler that knows about the sorter.

The rest is in this table:

Change	What the view saw	Rows rebound	Selection
Raise to P1 under Title sort, task stays put	items-changed(2, -1, +1)	none	kept
Raise to P1 under Priority sort, task moves up	items-changed(2, -7, +7)	none	kept
Select all ten, Mark done under Title sort	ten single-item changes	none	all ten kept
Mark done with "hide done" on	items-changed(0, -1, +0)	one unbind	gone with the row

The second row needs explaining. The sort model didn't report the move as one removal and one insertion. It reported a single range covering everything from the task's old position to its new one, seven rows replaced. Even so, nothing was rebound. The ListView kept the rows it already had for those seven objects.

There's one caveat on that. All ten tasks fitted on screen, so every item that moved already had a row. A task moving in from off-screen would need binding like any other.

Compare the selection with the last post, where a search that hid a selected row lost the selection for good. Here the selected task was removed and added back in the same signal, and MultiSelection kept it selected through every case except the one where the filter took it away.

Ten changes in a row meant ten signals and no visible cost.

At scale

The log covers ten tasks, and the worry at the top of this post is about tens of thousands. So I measured it: toggle one task's done property under the Open first sort, and time the models alone with no window, in a release build on GTK 4.22.5. Each figure is the median of 25 changes.

Tasks	sorter.changed(Different)	items_changed(pos, 1, 1)	of which find()
10	0.012 ms	0.005 ms	under 0.001 ms
1,000	0.57 ms	0.016 ms	0.004 ms
10,000	5.5 ms	0.066 ms	0.035 ms
50,000	28 ms	0.40 ms	0.28 ms
100,000	53.5 ms	0.60 ms	0.43 ms

At 100,000 tasks the button approach spends 53 ms on one change, more than three frames at 60 Hz. Reporting the item takes 0.6 ms, and most of that is find() walking the store, which is where the item-to-position map mentioned earlier would start to pay for itself.

Those sorting times belong to this comparator as much as to GTK. Open first lowercases both titles on every comparison, and each of those allocates. A cheaper comparator would make the re-sort faster, but it would still be re-sorting all 100,000 tasks to place one.

The benchmark also checked that the list was still in order after each run, and under the Priority sort that check failed. sorter.changed(gtk::SorterChange::Different) re-sorted the CustomSorter behind Open first. It didn't re-sort the expression sorters. A NumericSorter, a StringSorter and the MultiSorter combining them all left the list out of order after their properties changed, at every size down to ten tasks. I haven't been into GTK's source to find out why. Reporting each changed item with items_changed kept every sorter type in order.

That contradicts the last post, which recommended the sorter call for expression sorters too. I've added a correction there.

The change nobody reported

The companion app has a "Report changes" toggle that switches the store's handlers off. I turned it off, sorted by Open first and marked a task done. It stayed where it was, which was the point of the toggle.

Then I turned reporting back on and marked a second task done. The second one dropped to the bottom with the other done tasks. The first one stayed in the middle of the open tasks, still out of place, and I had to stop and work out whether that was a bug.

It isn't. A report covers one item at one moment, and the models above only re-check the items they're told about. Nobody told them about the first task, and turning the toggle back on doesn't go back and replay what was missed. That task stays wrong until it changes again or the sort order is switched.

The toggle is a demo, but the real version of it is a property missing from the watch list. If you suspect a list has drifted, emit items_changed(0, n, n) on the store, with n as its length, and the models re-check everything. On 100,000 tasks under Open first that took 0.94 s, which is fine for a one-off repair. Calling changed() on the sorter won't do it for an expression sorter, as the benchmark showed.

When a reusable model is worth it

TaskStore is written for one item type and one list. That's the shape Contacts uses too: handlers on a plain GListStore.

Fractal, the GNOME Matrix client, goes a step further. Its ExpressionListModel is a list model in its own right. It wraps any other list model, watches a list of expressions on every item, and reports a single-item change when one of them fires. It sits under the SortListModels for the room sidebar, the member list and the mention and room completion lists. It also keeps the item-to-position map mentioned above, so lookups don't walk the list.

That generality costs code: implementing the list model interface, passing through changes from the model underneath, and keeping the watches in step as items come and go. For one list of one type, the store wrapper here does the job. A second list needing the same thing would be the time to write the general version.

Which fix to use

Approach	Catches changes from anywhere	Works with	Per change, 100,000 tasks
sorter.changed(Different) in the button handler	No, only changes made there	CustomSorter only	53.5 ms
watch-items on the FilterListModel	Yes	Expression filters, no sorting	not measured
items_changed(pos, 1, 1) from the store	Yes, for the properties it watches	Any filter or sorter	0.6 ms
items_changed(0, n, n) as a reset	Yes	Any filter or sorter	0.94 s

Two things the table doesn't show. The store only reports the properties it watches, so the watch list has to cover everything a filter or sorter reads, and a property left off fails silently. And the handlers are observers like any other: disconnect them when an item leaves, and hold the store weakly so a forgotten one can't keep it alive.

Next up

The list now stays in order no matter where a change comes from, and the button handlers no longer know about the sorter. Next is GtkColumnView and GtkGridView, where clickable column headers come down to handing column_view.sorter() to a SortListModel. The store from this post keeps that in order too.

The runnable version of this example is in the companion repo: cd 06-items-changed && cargo run. One widget at a time. See you in the next one.

Assisted by Claude Code (claude-opus-5-5). The experiments, bugs and conclusions are mine. How I work with AI tools is in The AI pair programmer.

Filtering and Sorting Without Re-querying: FilterListModel and SortListModel

Justin - FromTheArchitect — Thu, 15 Oct 2026 10:53:57 +0000

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.

The goal is a task list with a search box, a "hide done" toggle and a sort dropdown, where none of those controls ever touch the store. Typing in the search box doesn't rebuild anything. The store keeps every task in the order they were added, and the layers above it decide what the view sees.

The stack

let filter_model = gtk::FilterListModel::new(Some(store.clone()), Some(every.clone()));
let sort_model =
    gtk::SortListModel::new(Some(filter_model.clone()), Some(sorters::by_index(0)));
let selection = gtk::MultiSelection::new(Some(sort_model.clone()));

let list_view = gtk::ListView::new(Some(selection), Some(task_row::factory()));

FilterListModel and SortListModel work like the selection models from last time. Each takes another list model as its input and is itself a list model, which is what lets them stack: the filter model wraps the store, the sort model wraps the filter model, and the selection wraps the sort model. The view is handed only the top layer and never learns the others exist.

Order matters a little. Filtering first means the sorter only ever sees the rows that survived, which is less work on a long list. Selection goes last because the positions it hands out have to be positions in the list the user is looking at, and that's the filtered, sorted one.

You don't connect anything between the layers. Each wrapper subscribes to its child's items-changed when you hand it the child, and re-emits the change in its own positions. Append to the store and the new task arrives at the view already filtered and in sorted position.

Task has to become a GObject

Up to now Task has been a plain struct inside a BoxedAnyObject, and the row factory downcast and borrowed it. That works when your own closure is the only thing reading the data. Most of GTK's filters and sorters don't take a closure. They take an expression, which looks values up by property name, and a BoxedAnyObject has no properties to look up.

So Task becomes a GObject subclass with three real properties:

#[derive(Default, Properties)]
#[properties(wrapper_type = super::Task)]
pub struct Task {
    #[property(get, set)]
    title: RefCell<String>,
    #[property(get, set)]
    done: Cell<bool>,
    #[property(get, set)]
    priority: Cell<u32>,
}

Plus the usual object_subclass and wrapper boilerplate, which is in the companion repo and which I'll skip here. If the inner/outer type split or the #[property(get, set)] attribute is new to you, GObject in Rust: The Type System Explained walks through the same pattern one piece at a time. For now what matters is that task.done() and task.set_done(true) exist, and that setting a property emits notify::done.

Searching and hiding with filters

The search box is a StringFilter. You give it an expression naming the property to match against, and it does the rest:

fn property(name: &str) -> gtk::PropertyExpression {
    gtk::PropertyExpression::new(Task::static_type(), gtk::Expression::NONE, name)
}

pub fn search() -> gtk::StringFilter {
    let filter = gtk::StringFilter::new(Some(property("title")));
    filter.set_match_mode(gtk::StringFilterMatchMode::Substring);
    filter.set_ignore_case(true);
    filter
}

Substring matching and ignoring case are already the defaults, so those two setters change nothing. I keep them because the search behaviour is then readable without looking the defaults up.

Wiring it to the entry is one line, filter.set_search(Some(&entry.text())) in the search-changed handler. Setting the search string re-runs the filter on its own.

Hiding done tasks is a BoolFilter on done, inverted so it keeps the tasks that aren't. To combine the two I put both in an EveryFilter, which passes an item only if every child filter does (AnyFilter is the "or" version). The toggle adds the bool filter to the EveryFilter when it's switched on and removes it when it's switched off. Removing by every.n_items() - 1 relies on the bool filter being the last child, which holds here because nothing else is ever appended after it:

hide.connect_toggled(move |button| {
    if button.is_active() {
        every.append(not_done.clone());
    } else {
        every.remove(every.n_items() - 1);
    }
});

Adding or removing a child counts as the filter changing, so the FilterListModel re-filters without being told.

That's the version that works. It isn't the version I wrote first.

Why a done task didn't hide

My first "hide done" was a CustomFilter, the closure form. It read a shared flag and the task's done property:

let filter = gtk::CustomFilter::new(move |item| {
    let task = item.downcast_ref::<Task>().unwrap();
    !(state.get() && task.done())
});

A closure gives GTK no way to know when its answer changes, so the toggle handler flipped the flag and then called filter.changed(gtk::FilterChange::MoreStrict). MoreStrict promises the model that nothing hidden now will come back, so it only re-checks the rows on screen. LessStrict promises the opposite. That part worked, and switching the toggle on hid the done tasks as expected.

Then I selected a visible task, pressed Mark done, and it stayed on screen with its tick showing, in a list that was supposed to be hiding done tasks.

My first suspect was store.clone(). The filter model was built from a clone of the store, and for a minute I wondered if Mark done was changing a task in a different copy. It isn't. Cloning a gtk-rs object bumps a reference count and hands you a second pointer to the same GObject, so there's one store and one set of tasks. The tick appearing in the row proved the property had changed.

The actual problem was that when a task's done property changed, nothing told the filter model to run that task through the filter again. FilterListModel has a watch-items property for this, added in GTK 4.20 and off by default. In gtk4-rs, set_watch_items only exists when the crate's v4_20 feature is on (the companion code gets it through gnome_50), so without it you get a missing-method compile error rather than a hint about versions. The explanation I found when I searched for it said that turning it on makes the model listen for changes to every property on every item. If that were the whole story, it would have fixed the CustomFilter, but with watch-items on the row still stayed on screen.

GTK's own documentation for set_watch_items is more careful:

This allows implementations of GtkFilter that support expression watching to react to property changes. This property has no effect if the current filter doesn't support watching items.

The filter model doesn't subscribe to anything on its own. It asks the filter which properties to watch, and only a filter built from expressions can answer. A closure can't say what it reads. I checked all three combinations against the same task:

Filter	watch-items	Task marked done
BoolFilter on done	off	row stays
BoolFilter on done	on	row removed
CustomFilter reading done	on	row stays

So the fix was two changes together: rebuild "hide done" as the BoolFilter above, and turn watch-items on. The companion app leaves a toggle for watch-items so you can switch it off and watch the bug come back.

Re-sorting after the data changes

The dropdown offers three orders, and swapping between them is sort_model.set_sorter(...).

fn title() -> gtk::StringSorter {
    gtk::StringSorter::new(Some(property("title")))
}

fn priority() -> gtk::Sorter {
    let sorter = gtk::MultiSorter::new();
    sorter.append(gtk::NumericSorter::new(Some(property("priority"))));
    sorter.append(title());
    sorter.upcast()
}

StringSorter ignores case by default. MultiSorter only consults its second sorter on a tie, so tasks of equal priority come out alphabetical. The third order, "Open first", is a CustomSorter, because sinking done tasks and then sorting by title is easier to write than to express. It returns a std Ordering and calls .into() to get GTK's.

After the filter episode I expected SortListModel to have a watch-items of its own. As of GTK 4.22 it doesn't. Its properties are incremental, item-type, model, n-items, pending, section-sorter and sorter, and nothing in that list watches items. Under "Open first", a task you mark done stays where it was. The same goes for the expression-based sorters: I changed a task's priority under the Priority sort and it didn't move either.

Correction, 18 October 2026
The sorter call below only re-sorts a CustomSorter, such as Open first. Benchmarking a follow-up post on GTK 4.22.5 found that sorter.changed(gtk::SorterChange::Different) leaves expression sorters (a NumericSorter, a StringSorter, or a MultiSorter of them) out of order after their items' properties change, so under the Priority sort it does nothing. Reporting the changed item with items_changed(pos, 1, 1) works for every sorter type, and the follow-up post shows how.

The fix is to tell the sorter yourself, after you change the data:

mark_done.connect_clicked(move |_| {
    for task in selected_tasks(&model) {
        task.set_done(true);
    }
    if let Some(sorter) = sorted.sorter() {
        sorter.changed(gtk::SorterChange::Different);
    }
});

Collecting the tasks before changing any of them matters too. With watch-items on, each set_done can filter a row out and shift every position after it, so iterating the selection's bitset while mutating would skip rows.

A sturdier fix
Calling the sorter from the button works, but only for changes that go through that button. A sync or an undo that changes a task somewhere else would leave the list out of order. The sturdier fix is for the model to report the change itself: when a task's property changes, emit items_changed(pos, 1, 1) for its position, and the filter and sort models above re-check just that one item. GNOME Contacts does this on a plain GListStore in contacts-store.vala, listening only to the two properties that affect its order. Fractal wraps it in a reusable ExpressionListModel that sits under its SortListModels. That approach gets its own post next.

Binding rows with expressions

A side effect of Task being a GObject is that the row factory no longer needs bind and unbind handlers. In setup, each widget is bound to an expression rooted at the list item's item property:

let item = gtk::ListItem::this_expression("item");
item.chain_property::<Task>("title")
    .bind(&title, "label", Some(list_item));
item.chain_property::<Task>("done")
    .bind(&done, "visible", Some(list_item));

GTK re-evaluates those when the row slot is recycled onto a different item and when the bound property changes. That second part is why the tick appears the moment you press Mark done, without the factory being involved. The bind/unbind rhythm from the factory post is still how things work underneath; the expressions just do the bookkeeping. The binding belongs to the target widget, so there's nothing to clean up on unbind either.

What happens to the selection

Last post promised this. I selected two tasks under the Title sort, then changed things underneath them and logged what the MultiSelection reported.

A re-sort keeps the selection. The two tasks were at positions 1 and 5. After switching to the Priority sort they were at 5 and 8, still selected. MultiSelection tracks the items themselves.

What it doesn't do is tell you. That re-sort emitted items-changed on the selection model and no selection-changed at all. The selection is the same set of tasks, so from the model's point of view nothing about selection changed. Anything holding on to positions is now holding the wrong ones.

A filter is different. With the same two selected, I searched for "draft", which hid one of them. Clearing the search brought the row back unselected, and again only items-changed was emitted.

SingleSelection follows its item through a re-sort too, but what happens when a filter removes it depends on autoselect. With autoselect on, which is the default, it quietly selects a neighbour: my selected task was hidden by the search and "Draft the filter and sort post" became the selection, and stayed selected after the search was cleared. With autoselect off, selected_item becomes None and stays None when the row comes back. The neighbour is arguably the worse outcome, because nothing on screen looks wrong.

The practical consequence is in the status bar of the companion app, which shows "7 of 10 shown, 2 selected". If it only listened to selection-changed, a search that hid a selected row would leave it claiming two selected. It listens to both signals:

selection.connect_selection_changed(move |selection, _, _| {
    update(selection);
});
selection.connect_items_changed(move |selection, _, _, _| {
    update(selection);
});

Avoiding a reference cycle in your handlers

Those two handlers had a bug in my first draft, and not one you'd see by running the app. The status update was a closure that captured a clone of selection so it could read the counts. That closure was then connected to a signal on selection.

A GObject owns the handlers connected to it. So the selection model owned a closure that owned the selection model, which is a reference cycle. Because MultiSelection holds the sort model, which holds the filter model, which holds the store, the whole stack would outlive the window.

I tested both versions by building the stack, dropping every handle and checking a weak reference afterwards. With the captured clone, the selection and the store were both still alive. With the fix, both had been freed by the time I checked.

The fix is to stop capturing. Every signal hands the handler the object that emitted it, so the closure takes the selection as a parameter and uses that:

let update_status = {
    let (status, store) = (status.clone(), store.clone());
    Rc::new(move |selection: &gtk::MultiSelection| {
        status.set_label(&format!(
            "{} of {} shown, {} selected",
            selection.n_items(),
            store.n_items(),
            selection.selection().size()
        ));
    })
};

The label and the store are still captured strongly, which is fine: neither of them holds the selection, so there's no loop. glib::clone! with a weak capture is the other common fix, and the right one when the handler is connected to a different object from the one it reads.

Sharp edges

Build filters from expressions if items change. watch-items re-checks an item only through filters that can name what they read, such as StringFilter, BoolFilter, or an EveryFilter holding them. A CustomFilter is invisible to it, so a closure filter that depends on item state needs its own changed() call.

Sorting never notices item changes. As of GTK 4.22, editing a property that a sorter compares leaves the row where it was, even with an expression sorter. Whatever changes the data owes the sorter a changed() call, or the model owes the list an items-changed.

Corrected 18 October 2026: the changed() call only works for a CustomSorter. For expression sorters, report the item with items-changed instead, as the follow-up post does.

Listen to items-changed as well as selection-changed. A re-sort moves selected rows without a selection-changed, and a filter can drop or swap the selection without one either. On a SingleSelection with autoselect on, the swap lands on a neighbour. If a selection has to survive a search, keep it in your own state.

Don't capture the emitter in its own handler. Use the reference the signal passes in, or a weak clone. A strong clone keeps the selection model and everything under it alive.

Collect before you mutate. With watch-items on, changing an item can remove its row and shift the positions you were about to visit.

Next up

The list now searches, hides and reorders, and the store hasn't changed once. The next post replaces the button-handler re-sort with a model that reports its own item changes, using what GNOME Contacts and Fractal do in production. After that, GtkColumnView and GtkGridView, where clickable column headers come down to handing column_view.sorter() to a SortListModel.

The runnable version of this example is in the companion repo: cd 05-filter-sort && cargo run. One widget at a time. See you in the next one.

Assisted by Claude Code (claude-opus-5-5). The experiments, bugs and conclusions are mine. How I work with AI tools is in The AI pair programmer.

Selection, Modelled: Why GTK4 Puts Selection in the Model, Not the View

Justin - FromTheArchitect — Mon, 28 Sep 2026 23:00:00 +0000

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.

Before any of the type names matter, it's worth knowing where selection lives, because GTK4 moved it and that move is the whole design. In the GtkTreeView world you asked the view. gtk_tree_view_get_selection() handed you a GtkTreeSelection object that belonged to the widget, and selection was a property of the thing on screen. GTK4 inverts it. Selection is a property of the model, and the view is a renderer of model state, which is how everything else in this part of the toolkit works too. GtkListView has no get_selection() at all.

That relocation buys more than it looks like from the API diff. The selection state of your list becomes available to code that has never heard of your widget tree. You can set it before the view exists. You can test it without a display server.

Three models, one interface

GtkSelectionModel is an interface rather than a class, and the three implementations you'll actually use are all decorators. Each one wraps a GListModel and is itself a GListModel:

let selection = gtk::NoSelection::new(Some(store.clone()));      // nothing selectable
let selection = gtk::SingleSelection::new(Some(store.clone()));  // at most one
let selection = gtk::MultiSelection::new(Some(store.clone()));   // any number

The decoration is the part to hold onto. The view doesn't see your GListStore; it sees the selection model, which forwards item lookups straight through and adds selection state on top. Next post's filter and sort models are the same trick applied to a different concern, which is why they compose with this one so cleanly. They slot in underneath, between the store and the selection model.

Choosing between the three is mostly obvious. NoSelection for a list that's purely display, like a log or a feed or a set of rows whose only interaction is a button inside the row. SingleSelection for master-detail, where picking a row drives a pane somewhere else. MultiSelection when the user needs to act on a batch. What's less obvious is that SingleSelection and MultiSelection expose that state through two completely different mechanisms, and the second one is where people get stuck.

SingleSelection and the autoselect surprise

SingleSelection gives you two properties: selected, a u32 position, and selected-item, the object itself. Watching either one is how you wire selection outward:

selection.connect_selected_item_notify(|selection| {
    let Some(item) = selection.selected_item() else {
        return;
    };
    let boxed = item.downcast::<BoxedAnyObject>().unwrap();
    let task: Ref<Task> = boxed.borrow();

    println!("selected: {}", task.title);
});

The handler never touches the GtkListView. It doesn't ask the view what's highlighted or walk rows looking for a CSS class, and it runs whether or not a view has been built yet. For master-detail that's the arrangement you want: the detail pane subscribes to the selection model and never learns which widget is displaying it.

Now the surprise. SingleSelection has an autoselect property that defaults to TRUE. With it on, the model refuses to hold an empty selection. It takes item 0 as soon as the model is non-empty, and it takes something else if the selected item is removed. Your list opens with the first row highlighted, your detail pane opens already populated, and nothing in your code asked for either.

A second property is involved: can-unselect, defaulting to FALSE. The name reads like a user-interaction flag, something about whether ctrl-click can deselect. Its scope is wider than that. It gates every route to an empty selection, your own code included. With can-unselect off, set_selected(gtk::INVALID_LIST_POSITION) and unselect_all() both return without doing anything. autoselect then sits on top as a second, independent veto: even with can-unselect on, an empty selection is refused while autoselect is on.

That leaves four combinations, one of which lets a SingleSelection end up empty:

autoselect	can-unselect	can it be cleared?
false	false	no
false	true	yes
true	false	no
true	true	no

So you turn autoselect off. Here is where I lost an afternoon:

// Looks right. Selects item 0 anyway.
let selection = gtk::SingleSelection::builder()
    .model(&store)
    .autoselect(false)
    .can_unselect(true)
    .build();

That builder produces a model with selected == 0. The order of the builder calls is load-bearing. Properties are applied in the order you write them, and installing the model is the event that triggers the autoselect, so with .model() first, item 0 gets selected while autoselect is still sitting at its default TRUE. The .autoselect(false) that lands a moment later doesn't retroactively undo it. Swap the two lines:

// Actually starts empty.
let selection = gtk::SingleSelection::builder()
    .autoselect(false)
    .can_unselect(true)
    .model(&store)
    .build();

The other construction paths are worth checking rather than guessing at, because the failure is so quiet. SingleSelection::new(Some(store)) followed by set_autoselect(false) fails the same way, for the same reason: the model went in first. Constructing empty, setting the property, then calling set_model() works. If you've already got a model that has made its choice, set_selected(gtk::INVALID_LIST_POSITION) will clear it, though only with can-unselect on and autoselect off, per the table above. Call it without those and it returns quietly, which puts you one level down in the same hole.

None of these are CONSTRUCT properties, which is why the ordering leaks through at all. They're ordinary read-write ones. The builder applies them in the sequence you wrote, and installing the model runs the autoselect immediately rather than waiting for construction to finish.

A note on that constant. GTK_INVALID_LIST_POSITION is u32::MAX. You rarely need it in Rust, since selected_item() returns an Option and the let ... else above covers the empty case. If you do compare positions numerically, watch the emptiness test in particular. Empty is u32::MAX, so selected() == 0 is false exactly when the selection is empty and true when row 0 is legitimately picked, which is the inverse of the check you meant to write. The C habit of testing against -1 at least fails loudly: selected() returns a u32 and won't compile against it.

MultiSelection doesn't have a selected property

The instinct is to reach for the plural of what SingleSelection gave you, and there's nothing there. MultiSelection has no selected-items property. The signal you connect to lives on the GtkSelectionModel interface itself:

selection.connect_selection_changed(|selection, position, n_items| {
    // position and n_items describe the range that CHANGED,
    // not the range that is now selected.
});

Those two arguments are the trap. position and n_items delimit the range whose selection state was touched. They're an invalidation hint for the view, in the same spirit as items-changed, and they don't tell you what is selected.

It's easiest to see by logging both at once. Selecting row 3, then row 7, then hitting select-all on a ten-item model:

after select_item(3, false): args = (3, 1),  selection size = 1
after select_item(7, false): args = (7, 1),  selection size = 2
after select_all():          args = (0, 10), selection size = 10

The second line is the whole problem. The arguments say "one item, at position 7" while the actual selection is two rows. Code that treats those arguments as the answer gets the first line right and the second line wrong, with nothing in the API to tell it which case it's in.

To find out what's actually selected, re-query the model:

let bitset = selection.selection();

GtkBitset is a compact set of u32 positions. That's the right shape when a user has just selected forty thousand rows and you'd rather not materialise a vector of them. Getting items out of it means iterating positions and looking each one up:

let bitset = selection.selection();
let mut titles = Vec::new();

if let Some((mut iter, first)) = gtk::BitsetIter::init_first(&bitset) {
    let mut position = Some(first);
    while let Some(p) = position {
        let item = selection.item(p).unwrap();
        let boxed = item.downcast::<BoxedAnyObject>().unwrap();
        let task: Ref<Task> = boxed.borrow();
        titles.push(task.title.clone());
        position = iter.next();
    }
}

Two things there earn their awkwardness. BitsetIter::init_first returns the iterator and the first value together, because an empty bitset has no first value. The Option doubles as the emptiness check, so no separate is_empty() call is needed in front of it.

The second is the lookup: selection.item(p) rather than store.item(p), because positions are in the selection model's coordinate space. Today those two happen to be identical, since MultiSelection is a straight pass-through. They stop being identical the moment a filter or sort model joins the stack, and looking positions up in the wrong model is the kind of bug that only shows itself once a user types in a search box.

Setting selection from code

Everything so far has been reading. The GtkSelectionModel interface is also how you write:

selection.select_item(3, true);   // true = unselect everything else first
selection.select_range(0, 5, false);
selection.select_all();
selection.unselect_all();
selection.set_selection(&selected, &mask);

That bool on select_item is unselect_rest, and it does real work. select_item(3, false) on a MultiSelection adds row 3 to whatever was already selected; select_item(3, true) makes it the only one. On a SingleSelection the distinction is academic, which is how you end up internalising the wrong meaning while working with single selection and then carrying it over.

set_selection(&selected, &mask) takes two bitsets and updates every position in mask to match selected. It's the batch primitive. Reach for it when applying a whole selection state at once, restoring a saved selection say, rather than looping select_item and emitting a signal per row.

Now the catch, which is why "available on the interface" is a weaker promise than it sounds. SingleSelection implements only select_item, unselect_item and unselect_all. Everything else falls through to the interface defaults, which return false and do nothing. select_all, select_range and set_selection are all callable on a SingleSelection, they all compile, and they all silently decline. Each returns a bool saying so, and that return value is the only thing distinguishing "done" from "declined":

let changed = selection.select_range(0, 5, false);
// MultiSelection: true.  SingleSelection: false, and nothing happened.

Sharp edges

Set autoselect before installing the model. Installing the model is what triggers the initial selection, so a builder with .model() first leaves you item 0 selected and a property claiming otherwise.

can-unselect gates your code too, not only the user. With it off, set_selected(INVALID_LIST_POSITION) and unselect_all() are silent no-ops. Clearing a SingleSelection needs can-unselect on and autoselect off; three of the four combinations refuse.

Re-query selection() in every selection-changed handler. The position/n_items arguments are an invalidation hint for the view. Clicking rows one at a time produces ranges that happen to look like the answer, so this survives casual testing and then fails on the second click.

Look positions up through the model that gave them to you. Your store will agree today and hand back the wrong row once a filter or sort model joins the stack.

Half the interface does nothing on a SingleSelection. select_all, select_range and set_selection compile fine and return false without acting. Only select_item, unselect_item and unselect_all are implemented. On NoSelection none of them do anything. That bool return is your only signal, and it's easy to discard.

autoselect guarantees a selection only when items exist. An empty model has nothing to select, so selected_item() still returns None and the Option handling stays load-bearing.

GTK_INVALID_LIST_POSITION is u32::MAX. selected() == -1 won't compile against a u32, which is the loud failure. selected() == 0 compiles and inverts the emptiness check you meant. Prefer selected_item().

Next up

Selection is now something the rest of the app can read and write without touching a widget. The next post puts a second decorator in the stack: FilterListModel and SortListModel, which let you search and reorder a list without re-querying the source. That post also covers what happens to your carefully maintained selection when the rows underneath it move.

The runnable version of this example is in the companion repo — cd 04-selection && cargo run. One widget at a time. See you in the next one.

Reviewed with Claude, which caught the can-unselect scope error and the SingleSelection interface no-ops. Prose and conclusions are mine.

Your First Factory: GtkListView and the Bind/Unbind Rhythm

Justin - FromTheArchitect — Mon, 21 Sep 2026 23:00:00 +0000

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 post is the factory in full: all four lifecycle signals, what happens if you skip the ones that don't feel necessary, and the second way to build a factory that most tutorials skip straight past.

The four signals, not two

SignalListItemFactory exposes four connection points, and the previous post only used two of them. In practice bind is where most of the real logic lives — it attaches a specific item's data to the widget tree, and runs every time GTK assigns a row slot to an item, including reuse. setup is the one that runs first: it builds that widget tree, once per recycled row slot rather than once per item. unbind undoes whatever bind did, right before the row slot gets reassigned to a different item. teardown means the widget tree is being destroyed for good — it's the one I reach for least of the four.

// task_row.rs
factory.connect_setup(|_, list_item| {
    let label = gtk::Label::builder().xalign(0.0).build();
    list_item
        .downcast_ref::<gtk::ListItem>()
        .unwrap()
        .set_child(Some(&label));
});

factory.connect_bind(|_, list_item| {
    let list_item = list_item.downcast_ref::<gtk::ListItem>().unwrap();
    let boxed = list_item.item().and_downcast::<BoxedAnyObject>().unwrap();
    let task: Ref<Task> = boxed.borrow();
    let label = list_item.child().and_downcast::<gtk::Label>().unwrap();

    label.set_label(&task.title);

    if task.done {
        label.add_css_class("dim-label");
    }
});

That last line is the trap, and it's the one that got me the first time I hit it. add_css_class is not idempotent the way set_label is — it doesn't replace a previous state, it accumulates. Scroll this list far enough that a row gets recycled from a done task onto a not-done one, and the class is still there. Nothing crashes. Nothing warns you. You just get a task that renders dim for no reason anyone can see by reading bind on its own, because the bug isn't in bind — it's in the signal you didn't write.

Why `unbind` is the fix, not `bind` doing more

The instinct is to patch bind so it handles both cases:

label.set_css_classes(if task.done { &["dim-label"] } else { &[] });

That works here, and for a single CSS class it's arguably fine. It stops working the moment bind does anything that isn't purely declarative — a signal handler connected to a button inside the row, a spawned async task tied to this item, a GtkExpression watching a property. Reconnecting a signal handler in bind without disconnecting the previous one doesn't overwrite it; it stacks a second handler on top of the first, and now the row fires its click callback twice, then three times, then four, silently, for as long as the app runs. It's the most common factory bug I've seen reported, and every instance I've traced back had the same root cause: something was set up in bind with no matching teardown in unbind.

The fix is to treat bind and unbind as a pair, symmetrical on purpose:

factory.connect_bind(|_, list_item| {
    let list_item = list_item.downcast_ref::<gtk::ListItem>().unwrap();
    let boxed = list_item.item().and_downcast::<BoxedAnyObject>().unwrap();
    let task: Ref<Task> = boxed.borrow();
    let label = list_item.child().and_downcast::<gtk::Label>().unwrap();

    label.set_label(&task.title);
    if task.done {
        label.add_css_class("dim-label");
    }
});

factory.connect_unbind(|_, list_item| {
    let list_item = list_item.downcast_ref::<gtk::ListItem>().unwrap();
    let label = list_item.child().and_downcast::<gtk::Label>().unwrap();
    label.remove_css_class("dim-label");
});

unbind runs right before this row slot gets handed to a different item, so anything bind might have done conditionally gets a guaranteed place to be undone unconditionally. It costs a few extra lines for something as small as one CSS class. It's the difference between a working app and an unreproducible bug report for a connected signal handler, and by the time that bug report shows up, the factory code that caused it is long forgotten.

setup and teardown follow the same pairing, just less often needed: setup builds the widget tree, teardown runs when GTK is discarding that row slot entirely (the list shrank, the view is closing), not merely reassigning it. Most factories never touch teardown because widgets clean up their own children automatically — it exists for things you allocated outside the widget tree and GTK has no way to know about.

The other kind of factory

Everything so far has been SignalListItemFactory: build the row in Rust, imperatively, in a closure. GTK also has BuilderListItemFactory, which takes a .ui file — the same GtkBuilder XML you'd use for a whole window — and uses it as the template for each row:

<!-- task_row.ui -->
<interface>
  <template class="GtkListItem">
    <property name="child">
      <object class="GtkBox">
        <property name="spacing">6</property>
        <child>
          <object class="GtkImage">
            <property name="icon-name">task-due-symbolic</property>
          </object>
        </child>
        <child>
          <object class="GtkLabel" id="label">
            <property name="xalign">0.0</property>
          </object>
        </child>
      </object>
    </property>
  </template>
</interface>

let bytes = glib::Bytes::from_static(include_bytes!("task_row.ui"));
let factory = gtk::BuilderListItemFactory::from_bytes(gtk::BuilderScope::NONE, &bytes);

The declarative version wins on exactly one axis: rows with real layout — an icon and a label, two labels stacked, a switch on the trailing edge — read as a row when you look at the XML, the way the widget tree reads in Blueprint or .ui for a window. But BuilderListItemFactory isn't a variant of the setup/bind/unbind/teardown rhythm — it doesn't have those signals at all. setup, bind, unbind, and teardown belong specifically to SignalListItemFactory; the base GtkListItemFactory class defines none of them, and BuilderListItemFactory doesn't add any of its own. There is no connect_bind to call on it. Its only way of getting item data onto a row is a GtkExpression binding declared in the template itself — <binding><lookup name="title">item</lookup></binding> — which watches a property on the item and keeps a widget property in sync with it automatically, no Rust callback involved.

That means BuilderListItemFactory requires a real GObject with real properties, full stop. It's not merely more ceremony for our Task, wrapped as it is in a BoxedAnyObject — it's off the table entirely, because BoxedAnyObject doesn't expose title or done as properties an expression can look up, and there's no imperative hook left to fill that gap by hand. If you want a .ui-described row over a plain-struct payload like ours, the pattern isn't BuilderListItemFactory — it's still SignalListItemFactory, with a setup handler that builds the child from a .ui file (via gtk::Builder) or a composite template widget, and bind/unbind wired normally as signals underneath it. You get the markup; you keep the callbacks. Reach for BuilderListItemFactory on its own only once you've already paid for a proper GObject subclass with the properties an expression needs; keep plain SignalListItemFactory when the row is a handful of widgets and the logic is the whole story, which is most rows.

Sharp edges

bind running more than once isn't a bug in your code — it's a bug in this code, specifically when it manages any state beyond what it can also fully overwrite. If every line in bind reassigns a value unconditionally (set_label, set_visible, set_css_classes with the complete list every time), there's nothing for unbind to clean up, because nothing accumulates. The moment bind does anything additive — add_css_class, connect_clicked, spawning a task — it needs an unbind that undoes exactly that, or the row slot slowly becomes a superposition of every item that's ever occupied it.

unbind fires before reassignment, not before destruction. If you're holding a resource that genuinely needs to outlive one item but not the whole factory — a debounce timer, say — unbind is still the right place to cancel it, not teardown. teardown is rarer than either of the other three; most factories never implement it, and I've reached for it out of caution when unbind was what I actually meant, which is itself a small sharp edge.

BuilderListItemFactory has no connect_bind to skip — setup/bind/unbind/teardown are signals on SignalListItemFactory specifically, not on the base GtkListItemFactory class the two factory types share. BuilderListItemFactory's only binding mechanism is a GtkExpression declared in the template, which needs a real GObject property to watch. With a BoxedAnyObject payload like ours, there's no property for an expression to look up and no signal to connect instead, so the .ui template route is closed, not just less convenient. That's easy to miss on a skim of the docs, because the two factory classes look, from their names, like they should be more different than they are, and because most examples you'll find online use a real GObject model where the expression shortcut is available.

Next up

Rows now behave correctly under recycling, one at a time. The next post is what happens with more than one row selected at once: GtkSelectionModel, the difference between SingleSelection and MultiSelection, and wiring a selection change back out to the rest of the app without reaching into the view to ask it what's highlighted.

The runnable version of this example is in the companion repo — cd 03-first-factory && cargo run. One widget at a time. See you in the next one.

Stop Thinking in Rows: GListModel and the Modern List Mindset

Justin - FromTheArchitect — Mon, 14 Sep 2026 23:00:00 +0000

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:

let list_box = gtk::ListBox::new();

for task in &tasks {
    let label = gtk::Label::builder()
        .label(&task.title)
        .xalign(0.0)
        .build();
    list_box.append(&label);
}

Loop over your data, build a row, append it. It's the same instinct you'd bring from almost any UI toolkit that isn't fully declarative, and for a fixed handful of items it's completely fine — we'll come back to exactly when it's fine later in this post. The trouble starts the moment the data stops holding still.

Where that breaks

A task gets marked done somewhere else in the app. The list needs to re-sort so completed tasks drop to the bottom. A "show completed" toggle needs to filter rows in and out. With the loop-and-append approach, every one of those is a hand-rolled patch to a widget tree you built once and now have to keep in sync by hand: find the right row, remove it, rebuild it, reinsert it at the right index, and don't get the index wrong or you'll silently update the wrong task. None of this is exotic; it's the normal shape of a list that does anything at all, and it's exactly the kind of code that works fine in testing and comes apart three weeks later.

This is the specific pain GTK4 redesigned around, and it's worth naming what it replaced. Older GTK did this with GtkTreeView, GtkListStore, and cell renderers — a whole apparatus for exactly this problem, and it's largely deprecated now. The series intro opens with the story of finding a six-year-old Stack Overflow answer built on exactly that apparatus, getting it working, and only later discovering the toolkit had moved on without telling you. This post is the other half of that story: what actually replaced it, and why it's better once it clicks.

GListModel: data as the source of truth

The modern answer inverts the relationship. Instead of a widget tree you mutate by hand, you keep your data in a list model — something implementing the GListModel interface — and the view watches it. GListModel isn't a widget; it's an interface any GObject can implement to say "I'm an ordered, indexable collection, and I'll tell you when I change." The concrete type you'll reach for constantly is GListStore: a plain, mutable, in-memory list model you own and push items into.

Once data and view are genuinely separate concerns, the files should say so too. This example is small enough to fit in one, but I've split it the way I would in a real app instead — the way the companion repo actually has it: task.rs for the data, task_row.rs for turning one task into one row, window.rs for wiring the two into a window. The boundary is easier to see with it actually drawn.

// task.rs
pub struct Task {
    pub title: String,
    pub done: bool,
}

pub fn starting_tasks() -> Vec<Task> {
    vec![
        Task {
            title: "Write the list-mindset post".to_string(),
            done: false,
        },
        Task {
            title: "Record the cover art".to_string(),
            done: false,
        },
        Task {
            title: "Reply to the GTK forum thread".to_string(),
            done: true,
        },
    ]
}

And in window.rs, the store gets built from it:

// window.rs
let store = gio::ListStore::new::<BoxedAnyObject>();
for task in starting_tasks() {
    store.append(&BoxedAnyObject::new(task));
}

Two things stand out here. First, GListStore only holds GObjects, not arbitrary Rust structs — a plain Task can't go in directly. The usual fix is a real GObject subclass with proper properties, which is the right call for anything long-lived, but that's its own topic and I've already covered the subclassing mechanics in the GNOME/Rust series rather than repeat it here. For a case like this one, where the items are plain data and nothing needs to bind to their properties, glib::BoxedAnyObject is the honest shortcut: it wraps any Rust value as a GObject with no subclassing at all, at the cost of borrow()/borrow_mut() runtime checks instead of compile-time property access. Reach for it when you just need data in a list model; reach for a real subclass when something needs to observe a property changing.

Second, and this is the point of the whole post: you never touch a widget here. task.rs doesn't import gtk at all — nothing above creates a label or a row. The store is just data. Getting it on screen needs two more pieces: a selection model and a factory. Then the mutation story pays off.

The other half, briefly

GtkListView won't take a bare list model; it needs a selection model wrapped around it, even if you don't care about selection at all. NoSelection is the model for exactly that case — a pass-through that reports nothing selectable. And it needs a factory: a recipe for turning one item into one row. That recipe is the entire job of task_row.rs:

// task_row.rs
use std::cell::Ref;

use gtk::glib::BoxedAnyObject;
use gtk::prelude::*;

use crate::task::Task;

pub fn factory() -> gtk::SignalListItemFactory {
    let factory = gtk::SignalListItemFactory::new();

    factory.connect_setup(|_, list_item| {
        let label = gtk::Label::builder().xalign(0.0).build();
        list_item
            .downcast_ref::<gtk::ListItem>()
            .unwrap()
            .set_child(Some(&label));
    });

    factory.connect_bind(|_, list_item| {
        let list_item = list_item.downcast_ref::<gtk::ListItem>().unwrap();
        let boxed = list_item.item().and_downcast::<BoxedAnyObject>().unwrap();
        let task: Ref<Task> = boxed.borrow();
        let label = list_item.child().and_downcast::<gtk::Label>().unwrap();

        label.set_label(&if task.done {
            format!("✓ {}", task.title)
        } else {
            task.title.clone()
        });
    });

    factory
}

I'm deliberately not unpacking this fully. setup builds a row's widgets once; bind fills them in with a specific item's data, and this is the part that catches nearly everyone: GTK recycles rows as you scroll, so bind runs again and again for the same widgets with different items, not just once at creation. That recycling rhythm, the paired unbind step, and the difference between this signal-based factory and the builder-template kind are the entire subject of the next post. For now, treat task_row.rs as plumbing: enough to get something on screen so we can look at what happens when the data underneath it changes.

Back in window.rs, wiring the model to the view is two lines — the selection wrapper, and handing both to the view:

// window.rs
let selection = gtk::NoSelection::new(Some(store.clone()));
let list_view = gtk::ListView::new(Some(selection), Some(task_row::factory()));

The payoff: update the model, not the view

Here's the whole reason any of this is worth the extra ceremony. With the list built and already on screen, appending to the store is all it takes to add a row — still in window.rs, still nowhere near task_row.rs:

// window.rs
glib::timeout_add_seconds_local(2, move || {
    store.append(&BoxedAnyObject::new(Task {
        title: "Ship the draft".to_string(),
        done: false,
    }));
    glib::ControlFlow::Break
});

Run this and a fourth task appears two seconds after the window opens, with nothing above touching list_view, walking the widget tree, or computing an insertion index. GListStore::append fires the model's items-changed signal, the GtkListView is already listening for it, and it asks the factory for a row for the new item. The view is a function of the model; you stopped writing the function by hand.

That leaves main.rs almost embarrassingly small — its only job is declaring the three modules and handing GTK an entry point:

// main.rs
use adw::prelude::*;
use gtk::glib;

mod task;
mod task_row;
mod window;

const APP_ID: &str = "dev.fromthearchitect.gtkwidgets.ListMindset";

fn main() -> glib::ExitCode {
    let app = adw::Application::builder().application_id(APP_ID).build();
    app.connect_activate(window::build);
    app.run()
}

That's deliberate: the file that boots the app shouldn't be the file that knows how the app works. It's a small example, so the split is a bit generous for its size — but the boundary is the same one a bigger app needs, and drawing it here is cheaper than retrofitting it later.

This is the shift the field-guide post promised: describe the relationship between data and widget once, and let the toolkit run it. Everything else in this cluster of posts (selection, sorting, filtering, GtkColumnView) is a variation on this same shape.

So which list do you actually build?

None of this means GtkListBox is deprecated, and I want to say that plainly, because it's easy to walk away from a post like this assuming every list needs to be re-architected. It doesn't.

GtkListBox (plain widgets, one per row, appended by hand — the thing at the top of this post) is still exactly correct for a short, mostly-static list: a settings page, a handful of radio-style options, a preferences group. Libadwaita builds directly on top of it: AdwActionRow and friends are GtkListBox rows, because that combination is genuinely the right tool for that job, and you'll see it constantly once this series reaches forms and settings.

The real decision is about scale and volatility, not correctness. Reach for GListModel and GtkListView when the list is long enough to need recycling to scroll well, or when the data moves — items added, removed, or reordered from outside the widget tree, the way tasks completing or articles syncing in the background would. Keep GtkListBox when the list is short and mostly fixed once it's built. Figuring out which bucket you're in before you start saves you a rewrite later — and the reference won't help you here, because neither widget is "wrong."

Sharp edges

A few things caught me the first time I worked through this pattern. The first one at least fails loudly; the other two don't — they compile and run fine while getting it wrong.

GtkListView won't take a bare GListModel. It specifically wants something implementing GtkSelectionModel, so if you skip the NoSelection wrapper assuming you'll deal with selection later, it doesn't compile at all — that's not optional scaffolding, it's the documented way to say "no selection, and I mean it."

The second is sneakier, and I checked it rather than take it on faith: mutating an item in place doesn't touch its row. Swap the append in the demo above for grabbing store.item(0) and flipping its done field with borrow_mut(), and the row just sits there, unchanged — I ran exactly that and watched nothing happen. Nothing tells the view anything happened, because items-changed is a structural signal (items added, removed, or moved), not a property-change signal. To make an existing row reflect new data, you either replace the item outright (remove and reinsert, or GListStore::splice) or move up to a real GObject subclass with a proper property and let the factory bind a notification instead of copying data once. It's exactly why the demo appends a new task rather than flipping a flag on an existing one — flipping it wouldn't have shown you anything.

The third is the one worth repeating because it's the single most common bug report against this API: the factory's bind runs more than once. It's not a constructor — it reruns every time GTK recycles a row for a new item, so anything you set up conditionally needs tearing down again in unbind, or it leaks onto the next item that reuses the row. This example is too simple to hit that; a set_label call is idempotent. Almost anything more involved (a signal handler, a CSS class, a spawned task) won't be, and that's the entire subject of the next post.

Next up

You've now got the mental model and just enough factory code to prove it works. The next post stops hand-waving over that factory: GtkListView properly, the difference between a SignalListItemFactory and a BuilderListItemFactory, and the bind/unbind recycling rhythm in full — including the leak this post's example was too simple to trigger.

The runnable version of this example is in the companion repo — cd 02-list-mindset && cargo run. One widget at a time. See you in the next one.

GtkApplicationWindow vs AdwApplicationWindow: Which Window a GNOME App Should Use

Justin - FromTheArchitect — Mon, 07 Sep 2026 23:00:00 +0000

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.

Here's the short answer, so the rest of this post is the why: in 2026, for anything you intend to ship as a GNOME app, reach for AdwApplicationWindow. The reason isn't cosmetics — it's structural, and it changes how you build everything above it. The difference comes down to one thing: where the titlebar lives.

GtkApplicationWindow: the honest baseline

GtkApplicationWindow is the plain GTK window, and there's nothing wrong with it. It has a content area and a dedicated titlebar slot, and you fill the slot with a header bar:

let header = gtk::HeaderBar::new();

let window = gtk::ApplicationWindow::builder()
    .application(app)
    .title("Application Shell")
    .default_width(420)
    .build();

window.set_titlebar(Some(&header));
window.set_child(Some(&content));
window.present();

Two slots, two setters: set_titlebar for the bar across the top, set_child for everything underneath. If you don't call set_titlebar at all, GTK gives you a default one so the window is still draggable and closable. This works, it ships, and for a tool that doesn't care about looking GNOME-native it's entirely fine.

The limitation is baked into that titlebar slot. It's a special region the window manages separately from its content — which means your header bar can never be anything other than a strip pinned to the very top, the full width of the window, for the whole life of the app. The moment you want a layout where the header is part of a collapsible sidebar, or where two panes each carry their own bar, the slot is in your way. That's not a rare want in modern GNOME; it's the standard adaptive pattern. So the slot that makes GtkApplicationWindow simple is the same slot that makes it a dead end.

AdwApplicationWindow: no titlebar slot at all

AdwApplicationWindow removes the slot. That sounds like a downgrade and is actually the whole point. There is no separate titlebar region — the window has a single content child that fills it edge to edge, and the header bar becomes an ordinary widget you place inside that content, like any other.

let window = adw::ApplicationWindow::builder()
    .application(app)
    .title("Application Shell")
    .content(&content)   // one child, no titlebar slot
    .build();

Notice the method is content, not child plus titlebar. That single change is what unlocks adaptive layouts. Because the header bar is now just a widget in the tree, you can put it wherever the layout needs it: at the top of the window, yes, but equally at the top of one pane in a split view, or inside a page that slides away on a phone. The window stops dictating where chrome can live. Libadwaita's rounded corners, its dialogs that draw as sheets attached to the window, and the adaptive split views the whole platform is built around all assume this shape — content all the way out, chrome composed inside it.

This is the part I'd most want a newcomer to internalise, because it inverts the mental model you arrive with. The window is not a frame with a title bar and a body. It's an empty box you fill with one widget, and you assemble the chrome inside it. Once that clicks, the rest of Libadwaita stops looking like a pile of special cases and starts looking like a kit.

If the window is just an empty box, you need two more pieces to fill it: the header bar, and something to manage the relationship between it and your content.

AdwHeaderBar: the bar itself

The header bar goes inside the content, and you almost always want the Libadwaita one:

let header = adw::HeaderBar::new();

AdwHeaderBar and GtkHeaderBar look nearly identical and share most of their API, so it's fair to ask why bother. AdwHeaderBar is built to live inside the content rather than in a titlebar slot, it knows how to integrate with the adaptive containers (a split view can tell each pane's header bar to show or hide its window controls so you never get two close buttons), and it carries the platform's responsive behaviour for free. GtkHeaderBar predates all of that and assumes it's being set as a titlebar.

By default a header bar shows the window's title in the centre and the window controls — close, and minimise/maximise where the desktop uses them — at the ends. That's why the example sets .title(...) on the window: the header bar reads it. When you want a title and subtitle, or a custom widget in the centre, you set a title widget (AdwWindowTitle is the usual one) explicitly — a detail for a later post. For now, an empty AdwHeaderBar already gives you a draggable, closable, titled bar.

The rule of thumb: in a GNOME app, reach for AdwHeaderBar. The only time you'd drop to GtkHeaderBar is if you're deliberately not building on Libadwaita — and if that's true, you wouldn't be using AdwApplicationWindow either.

AdwToolbarView: the chrome manager

You could pack the header bar and your content into a GtkBox and call it done. It would even look right — at first. But you'd be hand-rolling something Libadwaita does properly, and AdwToolbarView is the widget for it:

let toolbar_view = adw::ToolbarView::new();
toolbar_view.add_top_bar(&header);
toolbar_view.set_content(Some(&content));

AdwToolbarView manages the bars around your content — any number across the top, any number across the bottom — and the content between them. The reason to use it over a plain box is everything it does that a box doesn't. It styles the bars to match the platform, and more importantly, it reacts to the content scrolling underneath: with its default flat style, a header bar sits borderless while the content is at the top and gains a subtle undershoot shadow the instant the content scrolls beneath it, so the user always knows there's more above. Bottom bars get the same treatment in reverse. (Want a persistent line instead of a shadow — useful when the bar and the content have different backgrounds? That's the top-bar-style property set to RaisedBorder; the default is Flat.) That scroll-aware shadow is the kind of thing you only notice when it's missing — and it costs nothing if you're already using AdwToolbarView.

A bottom bar — an action bar, a media control strip — is the same call:

toolbar_view.add_bottom_bar(&controls);

The mistake to avoid is putting the header bar into set_content instead of add_top_bar. It compiles, and it even renders something bar-shaped at the top of your content — but now it scrolls away with the content and gets none of the bar styling, because you've told the toolbar view it's page material, not chrome. The bar methods are how the widget knows the difference.

Putting the shell together

Three widgets, nested in one clear order — window holds a toolbar view, toolbar view holds a header bar and a page:

fn build_ui(app: &adw::Application) {
    let header = adw::HeaderBar::new();

    let content = gtk::Label::builder()
        .label("The shell is the chrome around this label.")
        .build();

    let toolbar_view = adw::ToolbarView::new();
    toolbar_view.add_top_bar(&header);
    toolbar_view.set_content(Some(&content));

    let window = adw::ApplicationWindow::builder()
        .application(app)
        .title("Application Shell")
        .default_width(420)
        .default_height(320)
        .content(&toolbar_view)
        .build();

    window.present();
}

Build your Application as an adw::Application, not a gtk::Application — it's easy to miss, and the full example makes it explicit at the top. Constructing the Adwaita application type is what initialises Libadwaita — its stylesheet, its settings, the dark-mode plumbing. Use a plain gtk::Application with Adwaita widgets and you'll get a window that's subtly unstyled at best and a panic at worst. It's a one-word change that's easy to forget and annoying to diagnose, so make it a habit.

That's the shell. From here out, we're just filling it.

Sharp edges

A few things that bite, all of them on the seam between the GTK window you might expect and the Adwaita one you're actually using.

AdwApplicationWindow inherits set_child and set_titlebar from GtkWindow, so they compile — but it overrides their behaviour, and the docs are explicit that you must use set_content instead. Call set_child on an AdwApplicationWindow and you'll get a runtime warning and a window that doesn't lay out the way you meant. If you've ported code from GtkApplicationWindow, this is the first thing to fix: one content child, no titlebar.

Because AdwApplicationWindow has no default titlebar, forgetting to add a header bar entirely gives you a window with no title, no close button, and nothing obvious to grab. On GtkApplicationWindow the default titlebar hides this mistake; here, nothing does. If your window comes up looking stranded, check that something in the content tree is actually an AdwHeaderBar.

Worth repeating because it's the one that wastes an afternoon: a header bar handed to set_content — or buried in a GtkBox that you then set as content — loses its bar styling and scrolls away with the page. If your header looks flat and slides off the top when you scroll, that's this: it belongs in add_top_bar, not the content.

And an empty AdwHeaderBar shows the window's title, not its own. If the centre of your bar is empty, you probably never called .title(...) on the window. Set it there, or give the header bar an explicit title widget — but don't expect a title to appear from nowhere.

Next up

You've got a window with proper chrome and an empty content area staring back at you. Everything from here is filling that area — and the next stretch of posts jumps straight to the material that's most underserved: showing lists of things. Before any specific list widget, the next post is about the mental shift GTK4 demands first — from hand-building rows to describing your data as a model and letting the toolkit drive the view.

The runnable version of this shell is in the companion repo — cd 01-application-shell && cargo run. One widget at a time. See you in the next one.

A Field Guide to GTK Widgets

Justin - FromTheArchitect — Mon, 31 Aug 2026 23:00:00 +0000

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.

That last sentence is the whole problem.

When you sit down to build a real interface, you almost never start from "I need a GtkColumnView." You start from "I need to show a list of articles, some of them unread, sortable by date, and it has to feel right on a phone." Nothing in the reference answers that. The reference is organised by what each widget is. The work is organised by what you're trying to do — and the translation between those two is exactly the knowledge that doesn't get written down.

So you do what everyone does. You search. You find a six-year-old Stack Overflow answer using GtkTreeView and GtkListStore, copy it, get it working, and only much later discover that the modern toolkit replaced that entire pattern with something completely different — list models and factories — that nobody told you about because the old way still compiles. You ship the deprecated path because it was the first thing that worked.

I've done this more times than I'd like to admit. This series is my attempt to write down the missing layer that the reference leaves to experience: which widget to reach for, when, and what's going to bite you when you do.

What a "field guide" means here

A field guide isn't an encyclopedia. A bird encyclopedia describes every feather; a field guide tells you how to tell a sparrow from a finch while it's moving. That distinction drives every choice in this series.

Every post leads with a decision rather than a widget. The title of a typical entry is closer to "how do I show a list?" than "the GtkListView class" — the widget is the answer to a question I'll pose first, in terms of a problem you actually have. And I'll show the trade-offs rather than just the happy path, because GTK frequently hands you three widgets that all could do the job: GtkListBox, GtkListView, or GtkColumnView for a list; GtkBox or GtkGrid for layout; the new AdwDialog or the patterns it replaced. Knowing which to pick, and what each one costs you, is the actual skill.

Mostly, though, the gotcha is the point. Scrolling that silently doesn't work because the policy is wrong; a factory that gets called far more often than you expected; rows that look identical but behave differently. These are the things that cost you an afternoon, and they're exactly what the reference omits, because strictly speaking everything is working as documented. The flip side is that I won't pad. GTK has a hundred-odd widgets and some of them, like GtkSeparator and GtkSpinner, don't warrant a thousand words. Where a widget is trivial I'll group it with its neighbours and tell you the one property you'll actually reach for, rather than stretch a separator into a post.

The modern GTK mindset

Before any specific widget, there's a shift in thinking that GTK4 quietly demands, and it trips up nearly everyone arriving from older GTK, other toolkits, or stale tutorials.

For years, the way you built a UI was imperative and row-oriented. You created widgets, packed them into containers, and when the data changed you went back into the widget tree and updated it by hand. I still have a lot of code that works exactly this way. It holds up fine until the data starts moving, at which point it fights you at every turn. And the specific machinery for displaying data that way — GtkTreeView, GtkListStore, cell renderers — is largely deprecated now. (Packing widgets into a GtkBox or GtkGrid is not going anywhere; it's still how you build any non-list UI. It's the row-oriented data-display path that's on the way out.)

The modern way is model-driven. You keep your data in a list model, and you hand GTK a factory: a small recipe for turning one item into one row. GTK calls that factory as needed and recycles the widgets as the user scrolls. The recycling is the part that catches people out — your factory's bind step runs again every time a row is reused for a different item, not just once when the widget is first created, so anything you set up has to be torn down again on unbind. You stop reaching into the tree when data changes; you update the model and let the UI follow.

If you've built a RecyclerView on Android or a UICollectionView on iOS, that recycle-and-bind rhythm will feel immediately familiar. If you're coming from SwiftUI or Compose, adjust your expectations: GTK isn't diffing a declarative view tree for you, so you still wire widgets up by hand inside the factory callbacks. And if you're coming from GTK2 or 3, this is a real reorientation — one worth making deliberately rather than discovering by accident halfway through a project.

You'll see this theme return constantly: describe the relationship between data and widget once, then let the toolkit run it. It shows up in list views, in property bindings, in GtkExpression, in the Libadwaita rows. Internalise it early and the rest of the toolkit stops surprising you.

How the series is organised

By concept, not by library.

The temptation is to do all of GTK first and then all of Libadwaita. I'm deliberately not doing that. Sorting widgets by the library they live in is an accident of how the code is packaged; it has almost nothing to do with the problem in front of you. Real interface work doesn't divide along library lines. You don't have "GTK problems" and "Libadwaita problems"; you have jobs: lay out a window, show a list, build a settings page, give the user feedback. So that's how the posts are grouped. Each one takes a job and reaches for whichever toolkit has the right tool, and very often both are in play at once.

That last part matters more than it sounds. For a great many jobs, GTK gives you the raw mechanism and Libadwaita gives you the GNOME-shaped version on top of it: a GtkListBox row versus an AdwActionRow, a hand-assembled dialog versus an AdwAlertDialog, GtkHeaderBar versus AdwHeaderBar. Knowing the Libadwaita version exists, and knowing when to ignore it and reach for the GTK primitive instead, is the kind of judgement that only comes from use. The reference documents the two libraries as if they were strangers. They aren't. You use them together, in the same widget tree, all day long. Libadwaita is also younger and far less blogged-about than GTK, so the example gap is widest exactly where the two meet, which is where this series spends most of its time.

Within each concept, posts are tiered honestly. Some carry a full treatment. Some get a tight, focused post. Some widgets are clustered with their siblings. I'll always tell you which, so you know whether you're getting a deep dive or a quick orientation. And where the GNOME Human Interface Guidelines have an opinion about the job at hand, I'll point it out — following them is most of what makes an app feel native.

The code

Abstract examples are forgettable, so every post that shows code ships a small, runnable example alongside it — its own self-contained project in the companion repo, one folder per post. No shared app sits underneath the series: each example is scoped to the one decision that post is about, so you can clone a single folder, cargo run it, and see exactly the widget in question without pulling in a wider codebase to understand it.

If you want to see the same widgets doing real work in a full application, my Building GNOME Apps with Rust series builds one — Gazette, a small RSS reader — from scratch. The two series are independent, but they pair well.

Why Rust

Every code sample in this series is Rust, using the gtk4-rs and libadwaita-rs bindings.

I made the case for Rust at length in the GNOME/Rust series, so I won't relitigate it here. The short version: the bindings are mature and idiomatic, a lot of the most interesting new GNOME apps are being written in Rust and that's the direction I'd bet on, and Rust's type system catches a whole category of UI-state bugs before you run the program. It's the default I'd recommend for new GNOME work in 2026.

If you write your GTK in C, Python, or Vala, you're still in the right place. The decisions this series is about — which widget, when, and why — are language-neutral. The factory pattern is the factory pattern whether you express it in Rust closures or Python callbacks. You'll just be mentally translating the snippets, and GTK's consistent API naming across bindings makes that nearly mechanical.

What I won't do is re-explain GObject subclassing or the project setup from scratch in every post — that ground is covered in the GNOME/Rust series, and I'll link back to it rather than repeat it. If you want the full environment setup (Flatpak SDK, Builder, the toolchain), start there. For this series, a working gtk4-rs project and a copy of Workbench for quick experiments is all you really need.

Next up: the application shell

We start where every app starts: the window itself. GtkApplicationWindow versus AdwApplicationWindow, the AdwHeaderBar that sits on top of it, and AdwToolbarView for the bars above and below your content. You open on a plain GTK window and, within a few lines, reach for the Adwaita chrome that makes it look like it belongs on the desktop — the two libraries working together from line one.

From there we jump straight into the list machinery, which is where modern GTK really lives — ahead of layout and navigation, because it's the genuinely underserved material and the gap this post itself just called out. If you've ever stared at a GtkListView wondering what a "factory" is and why your rows aren't appearing, that's the cluster of posts I'm most looking forward to writing.

One widget at a time. See you in the next one.

Excavating Legacy ETL: The AI Never Asserts a Fact It Could Look Up

Justin - FromTheArchitect — Tue, 25 Aug 2026 23:00:00 +0000

Every platform modernisation programme has the same first act, and it is never the interesting one. Before anyone gets to write a line of dbt, somebody has to work out what the current thing actually does.

In the SAP BusinessObjects Data Services case — BODS, if you've had the pleasure — that means inheriting a few hundred dataflows whose authors left the organisation years ago. The logic lives in exported XML. The business rationale lived in the heads of people who are now at other companies. Nobody can tell you which flows are duplicates, which ones nothing reads any more, or what any given one is for. There is a spreadsheet somewhere claiming to be an inventory. It is wrong in ways nobody can enumerate.

This is archaeology. It is also, on paper, the exact shape of problem that large language models should eat for breakfast: mountains of semi-structured text, pattern recognition, summarisation into prose a human can read.

So I tried the obvious thing, and the obvious thing failed in a way that turned out to be the most useful finding of the whole exercise.

Why pointing an LLM at the XML doesn't work

Paste a BODS dataflow export into a chat window and ask what it does, and you get an answer. It is fluent, well-structured, and mostly correct.

Mostly is the problem.

The output is a blend of two very different things: columns and mappings that are genuinely in the XML, and plausible-sounding business context that is not. AMOUNT_USD is a currency-normalised revenue measure — fine, that's a reasonable inference. But it will also tell you, with identical confidence and no change of register, that the flow runs nightly, or that STATUS follows the standard active/inactive convention, or that a column feeds the finance dashboard. None of those facts are in the file. They are priors about what ETL usually looks like, rendered in the same voice as the facts.

For most LLM tasks that's an acceptable cost. For this one it's fatal, because on a migration the facts are the deliverable. A spec that gets the join predicate subtly wrong doesn't fail loudly — it produces a fact table where every row has silently been stamped with the wrong foreign key. You find out during reconciliation, six weeks and a lot of goodwill later.

The failure mode isn't that the model can't read the XML. It reads it fine. The failure mode is that the output gives you no way to tell which sentences came from the file and which came from the model's expectations, and a human reviewer holding a 40-page spec cannot re-derive every claim by hand. That's the whole reason you asked for help in the first place.

So I stopped trying to make the model more accurate, and changed what it was allowed to do.

The one rule the whole design hangs on

The system I ended up with — etl-archaeologist — is built around a single constraint:

The AI never asserts a fact it could look up. The deterministic layer never interprets.

Two layers, one hard boundary. A plain Python layer parses the BODS exports into a fact store: sources, targets, columns, datatypes, mapping expressions, column lineage, join predicates, cross-flow dependencies. No model involved. Same input, same facts, every time.

An agent layer then reads that store and writes the parts a script genuinely cannot: what the pipeline is for, what the grain and keys probably are, whether to lift-and-shift it or redesign it, whether to migrate it at all.

That split sounds like process pedantry. It isn't — it's what makes the output reviewable. Every factual section of a finished spec traces to a row in a database. Every interpretive sentence carries (inferred — confirm with SME). A reviewer reading the spec knows, at every line, whether they're checking a fact or challenging a judgement. Those are completely different cognitive tasks and mixing them is what makes AI-generated documentation exhausting to review.

Layer one: facts

The extractor is unglamorous on purpose. lxml in, DuckDB out, about 150 lines:

CREATE TABLE dataflow      (df_name TEXT, job TEXT, project TEXT, source_file TEXT);
CREATE TABLE reads         (df_name TEXT, object_key TEXT, datastore TEXT, table_name TEXT);
CREATE TABLE writes        (df_name TEXT, object_key TEXT, datastore TEXT, table_name TEXT);
CREATE TABLE column_def    (df_name TEXT, col_name TEXT, datatype TEXT, mapping_text TEXT);
CREATE TABLE column_lineage(df_name TEXT, target_col TEXT, src_table TEXT, src_col TEXT);
CREATE TABLE source_column (df_name TEXT, datastore TEXT, table_name TEXT, col_name TEXT);
CREATE TABLE predicate     (df_name TEXT, predicate_text TEXT);
CREATE TABLE predicate_ref (df_name TEXT, src_table TEXT, src_col TEXT);

Predicates get stored twice, which looks redundant until you need it. predicate keeps the join or filter expression as verbatim text, because that's what has to be reproduced exactly on the target platform. predicate_ref holds the same expression exploded into the individual source columns it touches — the extractor regexes table.column references out of the predicate and keeps the ones that resolve to a real source table. Without that second table, any column used only as a join key looks unreferenced, and the dead-code query below would confidently recommend dropping the very columns holding the estate together.

The one piece that needed actual thought is column lineage. A BODS dataflow isn't a single mapping step; it's a chain of transforms, and most columns pass through several of them untouched before landing in the target. If you only record each hop, the final target column's origin is a graph walk away. So the extractor threads origins forward hop by hop — a mapped column records the source columns its expression references, a generated column (a surrogate key, an SCD date) records that it was generated, and a pass-through column inherits whatever the upstream column already knew:

else:  # pass-through: inherit the upstream column's origin
    prev = acc.get(frm, {"src": set(), "expr": "«pass-through»", ...})
    info = {"src": set(prev["src"]), "expr": prev["expr"], ...}

By the last transform, every target column knows the source columns it came from and the expression that produced it. That's the fact an SME can confirm or deny in five seconds, and it's the one an LLM is most tempted to smooth over.

The thing I underrated going in: this layer is not just an input to the AI. It's the test oracle. Because it's exact and reproducible, you can later use it to check the agent's homework — which turns out to be the entire trick.

Layer two: the questions one file can't answer

A second deterministic pass looks across all pipelines at once, because there is a whole class of question that no amount of careful reading of a single export can answer. "Is this a duplicate?" is unanswerable from inside the file.

Four queries do most of the work. Dependencies are a join between who writes an object and who reads it. Duplicate candidates are pairs of flows writing the same target, scored by column-set Jaccard overlap. Dead-flow candidates are flows nothing else reads. And dead code — my favourite, because it's pure profit — is source columns pulled into a flow and then never referenced by any mapping or any predicate, which is where predicate_ref earns its place:

SELECT sc.df_name, sc.table_name, sc.col_name
FROM source_column sc
WHERE NOT EXISTS (SELECT 1 FROM column_lineage cl
                  WHERE cl.df_name=sc.df_name AND cl.src_table=sc.table_name AND cl.src_col=sc.col_name)
  AND NOT EXISTS (SELECT 1 FROM predicate_ref pr
                  WHERE pr.df_name=sc.df_name AND pr.src_table=sc.table_name AND pr.src_col=sc.col_name)

Across seven pipelines that found seven columns being extracted for no reason at all. On a real estate that number is a rounding error on the migration effort you don't have to spend.

Worth being precise about what "dead" means here, because it's narrower than it sounds. The column never reaches the target, so nothing downstream of this flow can be reading it — that part is safe. What it doesn't mean is that the column is dead in the source system. Another flow may well use it, and something outside BODS almost certainly does. The finding is "stop pulling this column into this pipeline", not "drop this column".

Jaccard — intersection over union — is about as crude as similarity metrics get, and I chose it for that. It needs no tuning and no threshold anyone will argue about in a workshop, and the hard part of the question has already been answered by the join: these two flows write the same table. The score only has to rank what's left for a human to look at. I don't know it's the right metric. I know it hasn't yet surfaced a pair that wasn't worth two minutes of attention.

Notice what all four have in common: they're detection, not judgement. Exact, exhaustive, auditable, and completely free of opinion. Which is exactly what you want feeding the next layer.

Layer three: making "look it up" cheaper than guessing

The boundary between the layers only holds if the agent has an easy way to actually look things up. So the fact store — the DuckDB file — gets a fact server in front of it: a read-only MCP interface exposing list_pipelines, get_pipeline_facts, rationalisation_report, and a general query for anything the first three don't cover. Store is the data; server is the only door the agent gets to walk through, and the door is deliberately one-way:

def _query(sql: str):
    s = sql.strip().lower()
    if not (s.startswith("select") or s.startswith("with")):
        raise ValueError("read-only fact store: only SELECT / WITH queries are allowed")
    return _q(sql)

This is the part I'd most encourage people to steal. Telling a model "don't hallucinate" is a wish. Giving it a cheap, obvious, structured way to get the real answer is a design. When the ground truth is one tool call away, the model reaches for it — and when it does invent something anyway, the same tool is sitting right there to catch it.

Layer four: the part that actually needs judgement

With facts handled, what's left for the agent is genuinely interesting, and it's more than prose polish.

Take the dead-flow signal. The detector flagged four candidates, all with identical structural evidence: nothing else in the corpus reads your output. Deterministically they are indistinguishable. And yet the right answer differs for every one of them, because "no downstream consumer in the BODS metadata" means completely different things depending on what the flow is:

A monthly sales aggregate with no downstream reader isn't dead. It's terminal — the consumer is a BI tool the fact store cannot see. Keep, and go confirm the dashboard exists.
A conformed product dimension with no downstream reader is the same story, only more so — a conformed dimension exists precisely so that things outside the warehouse can slice on it. Keep, verify.
A customer SCD2 history table — same shape again. It's a history mart. Terminal by design.
A two-column pass-through in an isolated Legacy project, reading a source table literally named OLD_ACCOUNTS, writing to a staging area, referenced by nothing: that one is a genuine orphan. Retire.

One signal, four different verdicts, and the discriminator in every case is context that lives nowhere in the metadata — naming conventions, which datastore the target sits in, what kind of table it is, whether "terminal" is normal for that kind of table. That's the work. The detector found the candidates; the agent adjudicated them; and it overruled the detector three times out of four, which is precisely what you want a judgement layer to do.

The second thing the agent is good at is smelling migration risk in an expression. From the order fact load:

ifthenelse(ORDERS.CURRENCY = 'USD', ORDERS.AMOUNT, ORDERS.AMOUNT * 0.66)

A hard-coded FX rate. One rate, for every currency, for all time. The agent flagged it — and then, correctly, refused to fix it: preserve 0.66 exactly through cutover so reconciliation is byte-for-byte, and raise the rate-table question as a deferred redesign afterwards. That's the right call and it's a slightly subtle one. The instinct on seeing bad code is to improve it. The instinct that survives a migration is to reproduce it faithfully and change it in a separate, visible step.

The find I liked most, though, came out of the duplicate pair. Two flows both writing DIM_CUSTOMER, 60% column overlap, obviously redundant. But look at how each one derives STATUS:

DF_DIM_CUSTOMER          ifthenelse(CUSTOMER.ACTIVE_FLG = 'Y', 'ACTIVE', 'INACTIVE')
DF_DIM_CUSTOMER_REFRESH  ifthenelse(CUSTOMER.ACTIVE_FLG = 'A', 'ACTIVE', 'INACTIVE')

Same column, same source, different sentinel. 'Y' in one, 'A' in the other. Merge those two flows by picking whichever expression you happened to be looking at, and you silently flip the active/inactive status of some portion of the customer base. It's a two-character difference across two files, and it went straight into the report as a hard blocker on the merge. That's the class of thing manual archaeology misses at 3pm on a Thursday, and it's a good illustration of what the two-layer split buys you: the comparison was deterministic, the significance was judgement, and neither layer could have produced the finding alone.

Fixed templates, because consistency is a feature

Every agent-authored artefact fills a fixed template — one for pipeline specs, one for the portfolio report, one for verification verdicts. Same headings, same order, every run, with - none where a section is empty rather than the section quietly vanishing.

This is a small thing that pays continuously. Consistent structure means specs diff cleanly — against each other and against their own previous versions — reviewers build muscle memory, and changing the house style is a one-file edit instead of a re-prompt. Mostly it kills a whole category of drift you'd otherwise catch by feel, late, in review.

The gate: assume the spec is wrong

Here's the honest bit. Everything above still leaves you with output from a non-deterministic process. Constraints reduce the error rate; they don't take it to zero. Trusting the specs because the architecture is nice would be exactly the mistake I started out trying to avoid.

So the last step is an adversarial verification pass. One subagent per spec, with an explicit brief: try to break it. Assume every factual claim is wrong until ground truth proves it right. Do not read the spec and then go looking for support — establish ground truth independently first, from the fact store and the raw XML, then extract every factual claim from the spec and classify it: SUPPORTED, UNSUPPORTED, CONTRADICTED, or MISLABELLED.

The output is a claim-by-claim table with a PASS/FAIL verdict:

Claim	Status	Evidence
Dead code: `OLD_ACCOUNTS.CLOSED_DT` read but never mapped	SUPPORTED	facts `unused_source_columns = [{OLD_ACCOUNTS, CLOSED_DT}]`; XML declares `CLOSED_DT` in `<DISource>` schema but it is absent from the `Query` transform output schema
Join/filter predicates: none	SUPPORTED	facts `predicates = []` — genuinely empty. The added "None" line is accurate, not invented

That second row is the one that made me trust the design. The verifier didn't just check that the stated facts were right; it checked that a claim of absence was honest. "There are no filters here" is exactly the kind of statement that's easy to write and easy to be wrong about.

The obvious objection is that I've now got a non-deterministic process checking a non-deterministic process, and that's fair. The verifier is an agent too; it can miss things. What it can't easily do is miss things in the same direction as the author, because it isn't reading the author's reasoning — it goes back to the fact store and the raw XML and builds its own picture first. Two independent passes over the same ground truth have to fail in correlated ways to let an error through, which is a meaningfully harder thing to do by accident. That's a reduction in risk, not a proof of correctness, and it's exactly why the gate needs calibrating rather than trusting.

Which is what the planted errors are for. Two things came out of running the gate for real. First, on a deliberate planted-error test it caught every injected error while still passing the clean spec — so it isn't just manufacturing objections to look diligent. Second, and more usefully, it caught a defect I wasn't looking for: a spec that had been correct when written and had gone stale, because a new pipeline was added to the corpus afterwards and its dependency list no longer reflected reality.

That reframed the whole thing for me. I built the gate expecting to catch hallucination. What it actually earns its keep on is staleness — documentation drifting behind the source. Which, if you think about it, is the failure mode that has plagued every hand-written data dictionary ever produced. The difference is that here regenerating and re-verifying costs minutes, so the documentation can be treated as derived rather than authored, and re-derived whenever the source moves.

What I'd tell someone starting this

Split facts from judgement before you write a single prompt — not as a review step afterwards, as an architecture. If a script can determine it, a script should determine it, and the model should be reading the script's output rather than the raw source. Every other decision here fell out of that one, including the ones I didn't see coming.

The corollary is that ground truth has to be cheap to reach. A read-only fact server does more for accuracy than any amount of prompt engineering about accuracy, because it changes the economics rather than the instructions: guessing has to be the more expensive option, or eventually it won't be the one taken.

Then label inference at the sentence level. A disclaimer at the top of a document is decoration — a reviewer stops seeing it by page two. (inferred — confirm with SME) sitting in front of the specific claim is a routing instruction: this line is for the data owner, that line is for the migration engineer.

And when you verify, verify against the source rather than the summary. A checker that reads the spec and goes looking for support will find it every time; one that reconstructs ground truth independently and then hunts for contradictions is doing a completely different job, and only the second one tells you anything you didn't already believe.

Then the caveats, because I said I'd be honest about them.

The corpus I've been describing is synthetic — deliberately planted with a known answer key so I could measure whether the method recovers the truths rather than just producing confident-looking documents. It's a test of the approach, not a sample of any real estate, and no production data goes anywhere near it. Real BODS XML also nests its attributes differently to my samples, so pointing this at a live export means recalibrating the XPath in the extractor once. That's the only part that changes — but it does have to change, and I'd expect it to be a fiddlier afternoon than it sounds.

The larger limit is that detection only sees what BODS records. It cannot see Tableau, Athena, or the analyst with a scheduled query nobody remembers writing. That's precisely why every retire and merge recommendation is gated on a human plus external-consumer evidence rather than fired automatically — the tool is allowed to nominate, never to decide.

None of this made the model smarter. It made the model's job smaller. The interesting judgement — is this dead, is this a duplicate, is that hard-coded rate a bug or a contract — is exactly as hard as it was before, and it's still the reason anyone is doing the work. What changed is that it's no longer tangled up with a hundred low-level facts a database can answer exactly, and a reviewer can finally tell the two apart at a glance.

Archaeology, done properly, is mostly about knowing which layer you're digging in.

The etl-archaeologist tooling was written with Claude Code — the co-author trailers are in its commit history. The two-layer split and the constraint it hangs on are mine; most of the implementation is not. I didn't keep the prompt transcripts, which for a post arguing you should be able to audit what the AI did is an omission I notice.

Two YubiKeys, One Prompt Too Many

Justin - FromTheArchitect — Thu, 20 Aug 2026 23:00:00 +0000

I carry two YubiKeys. One lives on my keyring, one lives in a drawer, and both are enrolled everywhere that matters. A hardware token with no backup is a single point of failure you have chosen on purpose.

For months I had a small irritation I never bothered to chase. Some days git push asked for my PIN, I typed it, and it worked. Other days it asked for my PIN, failed, and then asked again, and the second one worked. Same command, same repo, same laptop. The variable turned out to be which of the two keys happened to be in the USB port.

It is a five-second annoyance — and I hit it maybe fifteen times a day.

What was actually happening

Both keys are sk-ssh-ed25519 credentials, and both get loaded into the gnome-keyring agent automatically:

$ ssh-add -l
256 SHA256:5imEVNLX...  yk1-12345678 (ED25519-SK)
256 SHA256:ATug2xnP...  yk2-12345679 (ED25519-SK)

I had no ~/.ssh/config at all. Without one, ssh offers the agent's keys in the order the agent hands them over, and the server takes the first one it recognises. GitHub has both of these enrolled, so it accepts the first offer every time. Which means ssh commits to yk1 before anything has checked whether the token in the port can actually satisfy it.

With yk1 in the port, that guess is right and you see one prompt. With yk2 in the port, ssh asks the attached token to sign for a credential it has never heard of. You get a PIN dialog, you type your PIN, it fails, ssh falls through to the second key, and that one works.

The detail that makes this worse than it needs to be is how these keys were generated. Both are resident keys with user verification required. The flags byte in the private key blob is 0x25, which decodes, using the constant names from OpenSSH's sk-api.h, as:

0x25 = SSH_SK_USER_PRESENCE_REQD | SSH_SK_USER_VERIFICATION_REQD | SSH_SK_RESIDENT_KEY

USER_VERIFICATION_REQD is what turns this from invisible into annoying, and the ordering that causes it sits above the token rather than inside it. Before ssh can request an assertion at all, the client has to obtain a PIN/UV auth token from the authenticator, and that is the step that puts the dialog on screen. Only after you have typed the PIN does the assertion request go down the wire, and only then does the key answer that it has never held this credential. Without the flag, the wrong-key attempt would fail silently and I would never have noticed.

The information was already there

Here is the part I feel slightly silly about. Look at the comments on those keys again:

yk1-12345678
yk2-12345679

Past me, generating these, had already written the serial number of the owning YubiKey into each key's comment. The mapping from "which token is plugged in" to "which key can possibly work" had been sitting in ssh-add -l output the entire time, and I had spent months not reading it.

OpenSSH gives you exactly the right hook for this. Match exec runs a shell command and applies the block if it exits zero:

Match host github.com,gitlab.com exec "%d/.ssh/yk-plugged 12345678"
    IdentityFile ~/.ssh/id_ed25519_sk_yk1
    IdentitiesOnly yes

Match host github.com,gitlab.com exec "%d/.ssh/yk-plugged 12345679"
    IdentityFile ~/.ssh/id_ed25519_sk_yk2
    IdentitiesOnly yes

Note the host criterion, because leaving it off is the mistake that turns a papercut fix into a bad afternoon. Match exec on its own applies to every destination, and the first block that matches pins IdentitiesOnly and a single IdentityFile for whatever you happen to be connecting to. Every other host, with every other key, stops authenticating.

IdentitiesOnly yes is the load-bearing line, and it is the one people leave out. I had assumed the name meant "ignore the agent". The -v output says otherwise: the agent still returns both keys. What the option actually restricts is which of them are eligible to be offered: only the ones whose public half matches an IdentityFile entry in scope. Two keys in, one considered.

That matching is also why the IdentityFile paths have to exist on disk even though the keys live in the agent. Since these are resident credentials, it is entirely possible to arrive on a fresh machine, pull them off the token with ssh-add -K, and have nothing in ~/.ssh at all. In that state the blocks match nothing and do nothing, which is confusing for about ten minutes.

If neither serial matches, no block applies, and you fall back to the old behaviour of trying everything. That is the correct failure mode: a config that gets worse than no config when it does not understand the situation is a config you will eventually curse. If both keys happen to be attached, both blocks match and both IdentityFile entries land in scope (IdentityFile accumulates across directives, unlike most keywords), so you are back to a coin flip and possibly one doomed prompt. Correct behaviour, but it does mean the fix looks broken if you plug in the drawer key without unplugging the keyring one.

The bit that was actually hard

Match exec runs on every single ssh invocation. Every git fetch, every scp, every ssh -G a tool makes to introspect your config. Whatever goes in there has to be cheap.

My first instinct was to read the serial out of sysfs, the way you would for most USB devices. That does not work:

$ cat /sys/bus/usb/devices/3-4/serial

$ cat /sys/bus/usb/devices/3-4/product
YubiKey OTP+FIDO+CCID

Empty. A YubiKey does not publish its serial in the USB device descriptor. You have to ask the device over one of its application interfaces, which in practice means ykman:

$ ykman list --serials
12345678

That call takes about 350 milliseconds on my laptop, most of it spent bringing the CCID interface up. Two Match exec blocks means two invocations, so seven tenths of a second on every git operation in order to save five seconds fifteen times a day. The arithmetic does not work.

So the helper caches. The question is what to key the cache on, and "a timeout" is the wrong answer. A 60-second TTL buys you either a minute of wrong answers after a swap or a minute of pointless ykman calls, and you get to choose which.

There is a better key available. The Linux USB stack assigns a device number on enumeration, and it increments. Swap tokens, even into the same physical port, and the number changes:

# yk1 attached
/sys/bus/usb/devices/3-4/  busnum=3 devnum=10

# swapped to yk2, same port
/sys/bus/usb/devices/3-4/  busnum=3 devnum=11

# swapped back to yk1
/sys/bus/usb/devices/3-4/  busnum=3 devnum=12

That gives a cache key derived from the thing whose change I care about. Reading it costs a cat of a sysfs file. No timeout, no staleness window, no daemon watching udev.

#!/bin/sh
# Exit 0 if a YubiKey with the given serial number is attached.
set -eu
want=$1

# Fingerprint the attached Yubico (vendor 1050) USB devices.
fp=
for d in /sys/bus/usb/devices/*/; do
    [ -r "$d/idVendor" ] || continue
    [ "$(cat "$d/idVendor")" = 1050 ] || continue
    fp="$fp$(cat "$d/busnum")-$(cat "$d/devnum"),"
done
[ -n "$fp" ] || exit 1  # nothing attached; no point spawning ykman

# Deliberately no /tmp fallback; see below.
cache=${XDG_RUNTIME_DIR:?}/yk-serials
if [ -r "$cache" ] && [ "$(head -n1 "$cache")" = "$fp" ]; then
    serials=$(tail -n +2 "$cache")
else
    serials=$(ykman list --serials 2>/dev/null) || serials=
    # Don't cache a failed lookup (busy pcscd, ykman missing); it would stick
    # until the next replug.
    if [ -n "$serials" ]; then
        tmp=$cache.$$
        (umask 077; printf '%s\n%s\n' "$fp" "$serials" >"$tmp") && mv -f "$tmp" "$cache"
    fi
fi

printf '%s\n' "$serials" | grep -qx -- "$want"

Two details in there are scar tissue rather than design. The early exit when no Yubico device is present keeps ykman from being spawned at all on a laptop with nothing plugged in, which is the common case when I am working offline. And declining to cache an empty result matters because a transient failure — a busy pcscd, a ykman that is not installed yet — would otherwise be cached against a fingerprint that stays valid until the next replug.

The hard requirement on XDG_RUNTIME_DIR is there for a related reason. It is torn down at logout, so the cache can never outlive a boot. Fall back to /tmp on a system where /tmp survives a reboot and the fingerprint stops meaning anything: device numbers are allocated from the low end again after every boot, so a stale entry has a very good chance of matching one.

Warm, the helper returns in about 9ms. Resolving the whole config with both Match blocks in it (ssh -G github.com) comes to 87ms, the remainder being ssh's own startup rather than anything I added. Cold, on the first connection after a swap, you pay the 350ms once.

Checking it actually works

ssh -v is useful here because it prints the whole decision path, key by key, rather than just the result. With the backup key in the port:

debug1: get_agent_identities: agent returned 2 keys
debug1: Will attempt key: ~/.ssh/id_ed25519_sk_yk2 ED25519-SK
debug1: Offering public key: ~/.ssh/id_ed25519_sk_yk2 ED25519-SK
debug1: Server accepts key: ~/.ssh/id_ed25519_sk_yk2 ED25519-SK
Authenticated to github.com using "publickey".

Two keys in, one attempt out. agent returned 2 keys alongside a single Offering public key is the whole fix between them: the agent's inventory is unchanged, and the filtering happened before anything went out on the wire, let alone reached the token.

I tested the other direction too, and I want to be honest about what that proved, because it is less than it looks. With yk1 attached, the run is identical and authentication succeeds on the first attempt. But that direction already worked before any of this, purely because id_ed25519_sk_yk1 sorts before id_ed25519_sk_yk2 and got offered first by luck. The value of testing it was confirming I had not broken the path that was fine. The yk2 case is the one that fixed a real failure.

That asymmetry is also why the bug survived so long. Half my usage was already correct, so it never looked like a broken configuration — it looked like the drawer key being flaky.

What this does not fix

It does not remove the PIN prompt. It removes the doomed one. I still verify and still touch, which is the entire reason for carrying a hardware token at all; a change that removed those would be trading the whole point for a fraction of a second.

There is one theoretical hole. USB device numbers wrap at 128, so a sufficiently unlucky sequence of replugs could land on a device number matching the cached one while holding a different token. The cost would be a single stale prompt, self-correcting on the next swap. I thought about defending against it for about a minute and then decided that engineering around a 1-in-128 chance of reproducing the exact bug I started with was not a good use of an afternoon.

The general shape

Match exec is the most underused thing in ssh_config. Most people know Match host and stop there, and then work around everything else with wrapper scripts or shell aliases or a mess of -i flags in their git remotes. But the predicate can be any command — which means your ssh config can respond to essentially any fact about the machine it is running on: which VPN is up, which network you are on, whether a particular file exists, which hardware token is in the port.

The constraint that makes it interesting is that it sits in the hot path of every connection, so the fact you want has to be cheap to establish. Half the work here was not "how do I select the right key", which is four lines. It was "how do I answer a 350ms question in under 10ms without ever answering it wrong". That is a caching problem, and the trick is nearly always the same — find the thing that already changes when your answer changes, and key on that instead of on the clock.

Setup notes: Fedora, OpenSSH 10.2p1, YubiKey 5C NFC on firmware 5.4.3, keys held by the gnome-keyring agent at $XDG_RUNTIME_DIR/gcr/ssh. Serial numbers in the examples are made up; use your own from ykman list --serials.

Reviewed with Claude, which caught the unscoped Match blocks and an error in how I'd explained the PIN/UV ordering. Prose and conclusions are mine.

Building GNOME Apps with Rust, Part 6: Fetching Feeds

Justin - FromTheArchitect — Tue, 18 Aug 2026 23:16:31 +0000

This is Part 6 of a series taking a GNOME app from an empty directory to GNOME Circle. Part 5 wired the sidebar to a real Feed GObject and a feed-selected signal — selecting a row updates the content pane and prints a line to the terminal. This is the post where that line stops being a placeholder and becomes a real network fetch.

The click that still does nothing real

Select This Week in GNOME, then select Hacker News. The placeholder swaps in the new name and URL — everything the app knows about that feed, and none of what's actually in it. Every Feed in the sidebar has a uri pointing at a real RSS or Atom document on the actual internet, and nothing in the codebase has ever asked one of them what's there.

The obvious fix — fetch the URL when feed-selected fires — is one line of code and the wrong line of code. GTK doesn't have a spare thread lying around to do that on, and the thread it does have is busy.

By the end of this post, selecting Hacker News in the sidebar prints real headlines to the terminal, fetched over the network, without the window so much as flickering. We'll build a Tokio runtime alongside GTK's own, give Feed somewhere to put what it fetches, and draw a hard line neither executor is allowed to cross.

The freeze

Wire the obvious fix into the feed-selected handler first, so you can watch it fail:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(move |_window: &super::GazetteWindow, feed: Feed| {
        // Don't do this.
        std::thread::sleep(std::time::Duration::from_secs(2));
        eprintln!("fetched (fake): {}", feed.name());
    }),
);

std::thread::sleep stands in for "network request in flight." Run the app and click a feed. For two seconds the window stops responding to anything — no hover states, no resize, no cursor blink, nothing repaints. Click a different feed while the first is still "fetching" and the click doesn't register until the sleep ends; it queues up invisibly and the window only notices you clicked at all once the first one finishes.

If you have GTK Inspector open (GTK_DEBUG=interactive, or Ctrl+Shift+I) while you try this, its own live views stall for the same two seconds — Inspector needs the app's main loop to be responsive to answer its own queries, so a frozen loop is invisible to Inspector too. Worth knowing the next time you're not sure whether your code froze or something else did.

Revert the handler to the logging-only version from Part 5 before continuing. The freeze was the demonstration, not a step you keep.

One main loop, nothing else runs until you give it back

GTK schedules everything through a single glib::MainContext, running cooperatively on a single thread: one job finishes before the next one starts. When you clicked a feed a moment ago, the redraw that should have shown the hover state, the cursor update, the eventual repaint once the click registered — all of it queued behind your feed-selected handler, waiting for std::thread::sleep to let go of the only thread any of it can run on.

That's a deliberate tradeoff. Exactly one thread ever touches a widget, so there's no locking, no data races, no Mutex<Widget>. The price is that the one thread has to keep coming back. Block it — a sleep, a synchronous file read, a blocking network call, anything — and every other queued job waits behind you.

This is also why "just spawn a thread and do it there" isn't a fix, only a different failure. Almost every GTK/GObject type is !Send: the bindings won't even let you move a Feed or a widget handle across a thread boundary — it's a compile error, not a runtime one. GObject's own machinery assumes single-threaded access and doesn't defend against concurrent calls from a second thread. A background thread can compute a result, but it can't hand that result to a widget directly. Something still has to get the result back onto the one thread allowed to touch GTK state.

Two executors, one job each

The pattern that resolves this has a name because the shape recurs in every GTK app that talks to a network: two executors, each with a rule it never breaks.

The GLib main loop owns every widget, every GObject, every signal, and it must never block.

Tokio owns anything that can block — the network request here, file I/O or database queries later. It runs on its own thread pool, and it never touches a widget or a GObject directly. That's its rule.

The two only meet at one seam: a future running on the GLib main context can .await a handle to work Tokio is doing, and when that work finishes, execution resumes back on the main context with the result now sitting there as a plain value. Nothing crosses except that value — no Feed, no gtk::Label, nothing GTK owns ever travels to a Tokio thread, and no raw socket or blocking read ever runs on the GLib thread. The rest of this post is standing up both executors and building that one seam.

Standing up the second executor

Add the dependencies:

tokio = { version = "1.53.1", features = ["rt-multi-thread", "net", "time"] }
feed-rs = "2.4.0"
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls"] }

rt-multi-thread gives the runtime its worker threads; net and time give it the I/O and timer drivers reqwest — and any future tokio::time::sleep — actually needs. That matters more than it looks like it should: reqwest also depends on tokio and pulls in net/time itself, and Cargo unifies features across the whole dependency graph. Leave them off tokio's own line and the project still compiles today, by accident of what else happens to be in Cargo.toml. It breaks the day reqwest changes its feature list, or the day someone copies this dependency line into a project with no reqwest in it.

reqwest with default-features = false and rustls-tls pulls in a pure-Rust TLS stack instead of linking against the system's OpenSSL — one less thing the Flatpak manifest needs to account for. The 0.12 pin is deliberate too: 0.13 renamed that feature to rustls and made it the default backend, which would leave the line above redundant rather than wrong, but 0.12 is what this post was written and tested against, and mixing versions is a worse trap than an old pin.

The runtime itself is built once, in main(), before the GTK application exists:

// The second executor. Built before the GTK application and dropped
// after it exits, so it outlives every fetch that borrows its handle —
// the GLib main loop is the other executor, and it never blocks
// waiting on this one.
let tokio_runtime = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(2)
    .thread_name("gazette-fetch")
    .enable_all()
    .build()
    .expect("failed to build Tokio runtime");

let app = GazetteApplication::new(
    "io.github.fromthearchitect.gazette",
    &gio::ApplicationFlags::empty(),
    tokio_runtime.handle().clone(),
);

let exit_code = app.run();

// `tokio_runtime` would drop here anyway at end of scope; the explicit
// drop just documents the ordering. `Runtime::drop` blocks this thread
// until every worker stops and abandons whatever tasks haven't
// finished — abrupt, not a cooperative cancel — which is still better
// than a fetch outliving the window that would have consumed it.
drop(tokio_runtime);
exit_code

app.run() blocks until the GTK application quits — that's the GLib main loop, occupying this thread for the entire life of the app. The Tokio runtime doesn't need this thread; Builder::new_multi_thread spins up its own worker threads (two of them here, named for easy identification in a debugger) and hands back a Runtime you only need to keep alive, not sit inside. tokio_runtime.handle().clone() is the thing that actually travels: a cheap, cloneable reference that can schedule work onto the runtime from any thread, including the GLib main thread.

One trap worth flagging on its own: forgetting .enable_all() fails silently until the first real request. A Builder without it produces a runtime with no I/O or timer driver — a different gap from the missing Cargo features above, this one is about whether a correctly-compiled runtime instance turns its drivers on. It builds fine, main() runs fine, the window opens fine, and the first time a spawned task tries to do the thing a runtime is for — reqwest::get or tokio::time::sleep — it panics with a message about no I/O driver running. The bug is invisible until the exact code path that needs the missing driver executes, which is exactly the fetch path this post is building.

That Handle needs a home the rest of the app can reach. GazetteApplication already owns everything else global to a running instance, so it owns this too — the same OnceCell shape Part 5 used for feeds: OnceCell<gio::ListStore> on the window: set once, read forever after.

#[derive(Debug, Default)]
pub struct GazetteApplication {
    // The second executor. Built once in `main()`, before the GTK
    // application runs, and outlives every fetch that borrows it.
    pub tokio: OnceCell<tokio::runtime::Handle>,
}

impl GazetteApplication {
    pub fn new(
        application_id: &str,
        flags: &gio::ApplicationFlags,
        tokio: tokio::runtime::Handle,
    ) -> Self {
        let app: Self = glib::Object::builder()
            .property("application-id", application_id)
            .property("flags", flags)
            .property("resource-base-path", "/io/github/fromthearchitect/gazette")
            .build();
        app.imp()
            .tokio
            .set(tokio)
            .expect("tokio handle set once at construction");
        app
    }

    /// The shared Tokio runtime handle — the executor every network fetch
    /// runs on. Available from any `GazetteWindow` via its `application()`.
    pub fn tokio_handle(&self) -> tokio::runtime::Handle {
        self.imp().tokio.get().expect("tokio handle set").clone()
    }
}

build() returns a fully constructed object. If GazetteApplication ever grows a constructed() that reaches for tokio_handle(), it will find the cell empty — constructed() runs during build(), before the line that sets tokio ever executes. Today's code escapes that trap by timing rather than by ordering: nothing that needs the handle runs until GTK calls activate, and activate doesn't fire until app.run(), long after new has returned with tokio set. Any window can reach the runtime through window.application(), downcast to GazetteApplication, and call tokio_handle().

Fetching, off the main thread

The fetch itself lives in a new file, src/fetch.rs, deliberately separate from feed.rs:

use std::fmt;

/// A single parsed entry from a feed. Plain data — not a GObject. It's
/// built on the Tokio runtime and only crosses onto the GLib main context
/// as a value, via `Feed::set_items`.
#[derive(Debug, Clone)]
pub struct FeedItem {
    pub title: String,
    pub link: String,
    pub summary: Option<String>,
}

#[derive(Debug)]
pub enum FetchError {
    Request(reqwest::Error),
    Parse(feed_rs::parser::ParseFeedError),
}

impl fmt::Display for FetchError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FetchError::Request(e) => write!(f, "request failed: {e}"),
            FetchError::Parse(e) => write!(f, "couldn't parse feed: {e}"),
        }
    }
}

/// Fetches and parses a feed at `uri`. Runs entirely on the Tokio runtime —
/// nothing in this function, or anything it calls, touches a widget or a
/// GObject. That's what makes it safe to run off the GLib main thread.
pub async fn fetch_feed(uri: &str) -> Result<Vec<FeedItem>, FetchError> {
    let response = reqwest::get(uri)
        .await
        .map_err(FetchError::Request)?
        .error_for_status()
        .map_err(FetchError::Request)?;

    let bytes = response.bytes().await.map_err(FetchError::Request)?;

    let parsed = feed_rs::parser::parse(&bytes[..]).map_err(FetchError::Parse)?;

    Ok(parsed
        .entries
        .into_iter()
        .map(|entry| FeedItem {
            title: entry
                .title
                .map(|text| text.content)
                .unwrap_or_else(|| "Untitled".to_string()),
            link: entry
                .links
                .first()
                .map(|link| link.href.clone())
                .unwrap_or_default(),
            summary: entry.summary.map(|text| text.content),
        })
        .collect())
}

FeedItem is a plain struct rather than a glib::wrapper! type, and that matters: constructing a GObject means calling into GObject's type system, and this function has no business doing that from a Tokio worker thread. fetch_feed produces data; something back on the main thread decides what GObject, if any, that data becomes.

error_for_status() matters more than it looks. Without it, reqwest::get resolves Ok for a 404, a 500, or a hosting provider's error interstitial — the HTTP request itself succeeded even though the content is a lie. Skip the check and feed_rs::parser::parse gets handed an HTML error page instead of a feed, fails to parse it, and the caller sees FetchError::Parse for what was actually a request-level failure. Checking status before reading the body is what keeps Request meaning "didn't get a real feed body at all" — whether the cause is DNS, a timeout, or a 404 — and Parse meaning "got a body and it wasn't a feed."

feed_rs::parser::parse takes anything implementing std::io::Read (a byte slice qualifies) and returns entries regardless of whether the source was RSS or Atom. Gazette's four sample feeds are a mix of both — This Week in GNOME and From the Architect are Atom, LWN and the Hacker News mirror are RSS — and fetch_feed doesn't need to know or care which. That format detection is feed-rs's job, done once, before any of Gazette's code sees an entry.

One thing worth knowing, not fixing here: reqwest::get is a convenience function that builds a fresh Client — and with it, a fresh connection pool and TLS session — on every call. Fine for a post about the boundary between two executors, wasteful in code that fetches the same handful of feeds over and over. Building a Client once and sharing it alongside the Tokio handle is a refinement for a later post, once persistence is in the picture.

Crossing back

The feed-selected handler is where the two executors actually meet:

obj.connect_closure(
    "feed-selected",
    false,
    glib::closure_local!(move |window: &super::GazetteWindow, feed: Feed| {
        eprintln!("feed selected: {} ({})", feed.name(), feed.uri());

        // The GLib executor owns `feed` and `window`; the Tokio
        // executor (below) only ever sees the URI string it needs
        // to fetch. Neither side touches the other's objects
        // directly — the `.await` on the join handle is the only
        // crossing.
        let tokio_handle = window
            .application()
            .and_downcast::<crate::application::GazetteApplication>()
            .expect("window has a GazetteApplication")
            .tokio_handle();
        let uri = feed.uri();

        glib::MainContext::default().spawn_local(async move {
            let result = tokio_handle
                .spawn(async move { crate::fetch::fetch_feed(&uri).await })
                .await;

            match result {
                Ok(Ok(items)) => feed.set_items(items),
                Ok(Err(fetch_err)) => {
                    eprintln!("fetch failed for {}: {fetch_err}", feed.name());
                }
                Err(join_err) => {
                    eprintln!(
                        "fetch task for {} did not complete: {join_err}",
                        feed.name()
                    );
                }
            }
        });
    }),
);

Read it from the outside in. glib::MainContext::default().spawn_local(async move { ... }) schedules the outer future on the GLib main context — the same executor that owns every widget — running it cooperatively alongside everything else, exactly like a signal handler. Because it's confined to the main context, it's allowed to hold feed and eventually call feed.set_items(...). That's still executor-one territory.

Inside it, tokio_handle.spawn(async move { crate::fetch::fetch_feed(&uri).await }) hands the actual work to executor two. Handle::spawn returns immediately with a JoinHandle; it doesn't block the caller, which is the entire point of calling it from the main thread. .awaiting that JoinHandle is where the outer future pauses: control genuinely returns to the GLib main loop, which goes on painting, handling input, and dispatching other signals while Tokio's worker threads do the fetch. When the Tokio task finishes, the main loop resumes this specific future exactly where it left off, back on the main thread, with result now holding a value.

Why Ok(Ok(items)) and not just Ok(items)? Two different things can go wrong, and they're wrapped separately. The outer Result comes from JoinHandle itself — its Err means the spawned task panicked or was cancelled, a Tokio-level failure that has nothing to do with feeds. The inner Result is fetch_feed's own Result<Vec<FeedItem>, FetchError>, a normal, expected outcome of trying to fetch something over a network that might be down. Matching both layers explicitly is what forces you to decide what each one means, rather than letting ? collapse them into a single generic failure.

And a specific footgun: tokio::spawn(...), the free function, panics here — tokio_handle.spawn(...) doesn't. The free function only works from inside a future that's already running on a Tokio runtime. Called from the GLib main thread, which isn't inside any Tokio runtime, it panics; the exact wording has changed across Tokio versions, but it always amounts to "no runtime found in this context." Handle::spawn, called on the Handle cloned out in main(), is explicitly designed to work from any thread, runtime or not — that's the entire reason GazetteApplication stores a Handle instead of a Runtime. If you ever see that panic, you've reached for the free function where you needed the handle.

Run the app now. Click Hacker News: after a brief pause — a real network round trip, with the window still live under your cursor — real headlines appear on stderr. Click LWN.net Headlines before the first fetch has printed anything, and both proceed independently.

Feed remembers what it fetched

set_items is doing real work in that handler, and Feed needs somewhere to put what it's given:

use crate::fetch::FeedItem;

#[derive(Debug, Default, Properties)]
#[properties(wrapper_type = super::Feed)]
pub struct Feed {
    #[property(get, set)]
    pub name: RefCell<String>,
    #[property(get, set)]
    pub uri: RefCell<String>,
    #[property(get, set)]
    pub unread_count: Cell<u32>,

    // Plain data, not a property: `Vec<FeedItem>` has no `glib::Value`
    // mapping, and nothing outside this module needs to bind to it
    // directly. `items()` and `set_items()` are the accessors.
    pub items: RefCell<Vec<FeedItem>>,
}

impl Feed {
    pub fn items(&self) -> Vec<FeedItem> {
        self.imp().items.borrow().clone()
    }

    /// Replaces this feed's items and emits `items-updated`. The count
    /// crossing over from a real fetch is what makes `unread-count` real
    /// too, rather than the placeholder zero every sample feed starts with.
    pub fn set_items(&self, items: Vec<FeedItem>) {
        self.set_unread_count(items.len() as u32);
        self.imp().items.replace(items);
        self.emit_by_name::<()>("items-updated", &[]);
    }
}

items isn't a #[property]: a Vec<FeedItem> has no glib::Value representation the way a String or a u32 does, and nothing outside Feed needs to bind a widget to the raw list. It's a RefCell for the same reason selected_feed was one back in Part 5 — a value that changes over the object's life, read from one place (items()), written from one place (set_items()).

The items-updated signal was declared back in Part 2, on a Feed that never actually got new items, then Part 5 dropped it entirely to avoid emitting ceremony for nothing. It comes back here on the same impl block that already derives Feed's properties — with one change from Part 2's sketch:

#[glib::derived_properties]
impl ObjectImpl for Feed {
    fn signals() -> &'static [Signal] {
        static SIGNALS: OnceLock<Vec<Signal>> = OnceLock::new();
        SIGNALS.get_or_init(|| vec![Signal::builder("items-updated").build()])
    }
}

Part 2's version carried a u32 payload — the new item count, passed directly on the signal. This one carries nothing. Feed has an unread-count property now, so a listener that wants the count can just read feed.unread_count() instead of catching it off the emission. A signal that announces something changed and lets listeners go look is easier to evolve than one that ships a payload every listener has to keep accepting — that's the shape the rest of this post builds on.

#[glib::derived_properties] has to stay on this impl, even though signals() has nothing to do with properties: it's what generates properties(), property(), and set_property() from the #[property] fields on the struct above. Drop it while adding signals() and every #[property] accessor Feed already has — name(), uri(), set_unread_count() — silently stops working.

What's different now is that set_items is the only thing that ever emits items-updated, and it's only ever called with data that actually came off the network. set_unread_count runs first, before the emit, and the count that shows up in the sidebar is the number of items this fetch found.

That's a narrower claim than "unread," on purpose. Every fetch sets unread-count to the total item count, not the count of items the user hasn't seen. Refetch a feed after reading everything in it and the badge goes straight back up to the full number. unread_count is standing in for a property Gazette doesn't have the machinery to compute correctly yet — real read-tracking needs per-item state, which doesn't exist until this series adds persistence. Until then, read the name as aspirational, not as a bug you need to chase.

A consumer for items-updated

set_items emits; something has to be listening. Each sample feed gets a logging handler when the store is built, in constructed():

let store = gio::ListStore::new::<Feed>();
for (name, uri) in SAMPLE_FEEDS {
    let feed = Feed::new(name, uri);

    // Reacting to items-updated is a separate job from fetching
    // them — the fetch (wired below, on feed-selected) never
    // logs directly, it just calls `feed.set_items(...)`.
    feed.connect_closure(
        "items-updated",
        false,
        glib::closure_local!(move |feed: Feed| {
            let items = feed.items();
            eprintln!("{}: {} items", feed.name(), items.len());
            for item in items.iter().take(3) {
                eprintln!("  - {}", item.title);
            }
        }),
    );

    store.append(&feed);
}

Notice the fetch code in feed-selected never calls eprintln! on success. It just calls feed.set_items(items) and stops. Printing what arrived is this closure's job, connected once per feed, entirely separate from the code that went and got the data. That's the same lesson Part 5 landed with the placeholder binding and the feed-selected logger: fetching is one job, reacting to what was fetched is another, and the signal between them is what keeps neither one needing to know the other exists. A future persistence layer connects its own handler to items-updated later without touching a line of fetch.rs.

Sharp edges

A RefCell borrow held across an .await fails the same way a borrow held across a signal emit did in Part 5, just harder to spot. The failure shape: let items = self.items.borrow_mut(); some_future.await; inside a spawn_local block, where the code resumed after the .await — or a handler running on a different turn of the main loop, if the borrow escapes further — tries to borrow the same cell. Signal handlers run synchronously, so a Part 5-style borrow panic happens right where you'd look for it. An .await point hands control back to the main loop for an arbitrary amount of time: anything else the loop dispatches in between, including another handler that reaches for the same RefCell, can trigger the panic somewhere that looks nothing like the code that caused it. Keep borrows scoped tightly, and never hold one across an .await.

What happens if you click the same feed five times in a row? Five independent fetches run concurrently, each racing to call set_items on the same Feed when it finishes — last one to land wins, and items-updated fires five times for one selection. Harmless for a post about the executor boundary, but worth knowing before you go adding a refresh action, which makes hammering that shortcut the obvious next thing to try. A real fix would track the in-flight JoinHandle on Feed and abort or ignore a new request while one's outstanding — outside this post's scope, but that's where the fix would go.

window.application() returns None before the window has one, and expect turns that into a panic. In practice this never fires here: GazetteWindow::new always takes an application, and nothing runs feed-selected before the window exists. The expect documents an invariant rather than checking one — this window always has an application by the time it can receive input. If you ever construct a GazetteWindow without one, a test most likely, this is where it breaks.

What we have so far

Selecting a feed now does real work. A Tokio runtime, built once alongside the GTK application and never touched by it directly, does the actual fetching and parsing, and the only thing that ever crosses back onto the GLib main thread is a Result full of plain data. Feed::items-updated fires for real for the first time since Part 2 declared it, driven by whatever feed-rs found at the far end of a real URL.

Nothing about this displays anywhere yet — the items live in a RefCell a logging handler reads, and the sidebar still shows nothing but a name and a count. The fetch mechanism this post built doesn't need to change at all to support that; it already hands off a Vec<FeedItem> to whatever wants to render it.

What comes next

That's the gap the next post closes: an article list for the selected feed, a content pane for the selected article, and the adaptive layout that collapses both into a single pane on a narrow window. The two-executor pattern from this post doesn't change to support any of it.

Further out, unread_count and items want somewhere durable to live, so a refetch doesn't erase read state and a restart doesn't lose it either. That's the persistence layer this series has been setting up for since the OnceCell and RefCell conventions in Part 5 — a real place for items-updated to write to, instead of a logging handler standing in for one.

The source code at the end of this post lives on the part-6 branch of fromthearchitect/gnome-rust-gazette.

Moments: The Photo App I Built to Win an Argument

Justin - FromTheArchitect — Fri, 14 Aug 2026 08:17:33 +0000

A phone call with a mate turned into a wager: could AI actually build a real application from scratch? Five months, 898 commits and 40,000 lines of Rust later, here's the verdict — and the app.

It started with a phone call

Like most of my questionable decisions, this one started on the phone with a mate, talking about technology the way we always do. The conversation drifted, as every technical conversation eventually does now, into AI. And we ended up circling the same question everyone circles: is this stuff actually capable of building real software, or is it just very confident autocomplete?

He was the sceptic. I was less sure. I'd been watching AI coding tools long enough to see signs they could do more than trivial hello-world demos — I'd even written about the right way to work with them more than a year earlier. But I don't think either of us honestly believed the answer would be a full-featured desktop application.

So I did the thing you should never do on a phone call after 9pm: I made a declaration. I would definitively prove, one way or the other, whether AI could build a real application from scratch.

Not from a single prompt. That's a stupid idea, and it's a strawman both camps love: the boosters because it makes a great demo, the sceptics because it makes a great failure. I mean built the way software actually gets built: architecture, iteration, review, tests, releases. Using the pair programming approach I'd already laid out on this blog — human as navigator, AI as driver, with the conversation between them doing the real work.

If it failed, I'd write that post. It would have been an easier post to write, honestly. This is the other one.

Picking a fight worth having

If you're going to test whether AI can build real software, the project has to be real: something with real complexity, a demanding platform, and a reason to exist beyond the experiment.

I've been an on-again, off-again Linux user for the best part of thirty years. The kernel was never the problem. The desktop was never really the problem either, especially lately. The thing that has always dragged me back to commercial operating systems is the application ecosystem. It's better today than it has ever been, thanks to an enormous number of dedicated open source developers. But there are still categories where the open source options simply don't compete with their commercial rivals. Photos. Email. The apps your family actually touches.

And that second part matters, because this wasn't abstract for me. I've been trying to move my family away from Apple Photos, and self-hosted Immich is a brilliant back end for that. But my family has spent too many years inside the Apple ecosystem to accept a web interface for something as personal as their photo library. They want a real application. Native, fast, polished. The kind of thing the Linux desktop is chronically short of.

So that was the wager, fully formed: a modern GTK4/libadwaita photo management application for the GNOME desktop, written in Rust. (All the cool kids use Rust. It's been a long time since I was a kid.)

There was one more reason this experiment appealed to me, and it's the one I suspect resonates with most working engineers. My background is software engineering. I've built some large, complex, performance-critical systems for companies big and small. Building software has never been the hard part. Finding the time has. A career plus a family leaves you time-poor in exactly the way that kills side projects, and it's why I'd never seriously committed to a sizable open source project before. If AI could compress the gap between the architecture in my head and working code on disk, the economics of contributing to open source change completely — not just for me, for every experienced engineer who's been sitting on the sidelines for the same reason.

What it was actually like

Five months later I can tell you the answer to the wager, but the honest version of this story is the middle, not the ending. Because the first few weeks were not smooth.

The early problems were all variations on the same theme: an AI will cheerfully solve the problem in front of it with no memory of how it solved the same problem last Tuesday. I'd find duplicate implementations of the same logic in different corners of the codebase. I'd find three different patterns for the same category of problem, each locally reasonable, collectively a mess. I had to learn the right size to chunk features — too big and the AI loses the thread, too small and you spend more time briefing than you save.

But the biggest lesson was about architecture, and it's the one I'd put on a poster. Claude's instinct is to reach the outcome in front of it as fast as possible. It is genuinely good at that. What it does not do — unless you make it — is weigh that outcome against the long-term shape of the system. Left unsupervised, you get software that works today and calcifies by next month. Which, now that I write it down, also describes plenty of human teams I've worked with.

So the collaboration settled into a division of labour that will look very familiar to anyone who read my pair programming post:

Mine: application architecture, design, and feature management. Every structural decision — the backend abstraction, the sync model, the storage layout — came from me. I was the navigator, holding the long-term picture.
Claude's: the code. The overwhelming majority of the actual Rust was written by the AI, driving under direction.
Ours: the review loop. Every change went through a pull request, reviewed and audited before merge — the same discipline I'd demand on any professional team. No PR process, no experiment; it's the review loop that makes the whole thing defensible.

Part way through I added a technique I now consider essential: adversarial review. Don't let the AI that wrote the code be the only AI that reads it. A second model — or even the same model under a deliberately hostile prompt — catches code smells, duplication and quiet regressions far earlier than a friendly one does. The author is always too fond of its own work. That turns out to be true of machines too.

Somewhere in those months, the experiment stopped feeling like an experiment. That's the part I didn't expect. Within days it was apparent that working this way wasn't just possible — it was preferred. I wasn't tolerating the AI to prove a point. I was reaching for it because the loop of architect–direct–review–refine was producing better software, faster, than I would have produced alone in the hours I actually have.

The verdict

Here's what the wager produced:

~40,000 lines of Rust, GTK4 and libadwaita
898 commits over five months, first commit 22 March 2026
Every change human-reviewed before merge, through a PR workflow
Releases through v0.4.1, shipped as Flatpak bundles with checksums, and GPG signatures on signed releases
Built almost entirely in evenings and spare hours: the time budget of a person with a job and a family, not a funded team

Now overlay the cost lens, because this is where the wager stops being a curiosity and starts being an economic argument. The entire AI side of this project ran on a Claude Code subscription — I started on the Pro plan and very quickly determined it wasn't enough, so most of the project was built on the Max 5x tier, at roughly AU$150 a month. During heavy development I'd regularly burn through 80–90% of my weekly token allocation, but I never went over it. So call it $150 a month, all in, for a coding partner that helped produce a 40,000-line application. That's not cheap as subscriptions go, and I won't pretend it's nothing — but weighed against what it unlocked, I found it an easy cost to justify. For me, the constraint was never the money. It was only ever the time. I'll admit I spent more evenings on this than my family would have liked while it was all coming together. Now that we have a functioning app, it's consuming far less of them.

And here is the verdict, as plainly as I can put it: AI can absolutely build a real application — but not alone, and that's precisely the point. The single-prompt fantasy is still a fantasy. What is real, right now, is an experienced engineer setting the architecture and standards, an AI doing the driving, and a review process keeping everyone honest. That combination settled the phone argument — and it removed the constraint that has kept me, and I suspect a great many engineers like me, out of open source for years.

I called my mate to concede that neither of us had been right. He's yet to install a Linux desktop, so I'm calling it a draw.

Meet Moments

Enough about the wager — here's the app.

Moments is a photo management application for the GNOME desktop. It's built for exactly the situation my family is in: your photos live either on your own disk or on a self-hosted Immich server, and you want a fast, native way to actually browse them.

It talks to a local folder or to an Immich server. The Immich backend caches metadata and thumbnails locally in SQLite, so browsing, searching and anything you've already opened works fully offline; a photo you've never viewed before will fetch its full-resolution original on demand, then keep it in a local cache for next time. The grid is keyset-paginated with six zoom levels, and it stays smooth through large libraries.

Beyond that:

RAW and modern formats — CR2, NEF, ARW, DNG and friends, alongside JPEG, PNG, WebP, HEIC and TIFF
Video — import and playback via GStreamer
Albums, People and Favourites — including face data synced from Immich
EXIF metadata — camera, lens, exposure and GPS in the detail panel
Non-destructive rotate, flip and crop, with adjustments and filters behind experimental flags

It's GPL-3.0-or-later, and it's a real daily-driver application — my family's photo library runs on it.

Installing it takes a download and two commands. Every release ships a single-file Flatpak bundle (with checksums, and GPG signatures on signed releases):

flatpak install --user moments-<version>-x86_64.flatpak
flatpak run io.github.justinf555.Moments

Grab the latest bundle from the releases page.

The Flathub question

The obvious question is why those two commands aren't just flatpak install flathub io.github.justinf555.Moments. That deserves a straight answer, because it's part of this story too.

I submitted Moments to Flathub on 27 March 2026, five days after the project's first commit — early, deliberately, so the review could run alongside development. The submission worked through the normal review cycle: manifest fixes, portal permissions, test builds passing on both architectures.

Then, at the end of May, Flathub changed its inclusion policy. The new rule is a blanket one: "Applications containing AI-generated or AI-assisted code, documentation, or any other content are not allowed." Not AI-generated slop with no human behind it — which the previous policy already prohibited, rightly — but AI-assisted anything. Two days after the policy landed, my submission was closed. The full exchange is public, and I'd encourage you to read it and draw your own conclusions rather than take my summary of it. Read closely and you'll notice I described the AI's share of the codebase as "parts of the app" in that thread — more of it than I was comfortable admitting mid-argument, if I'm honest. This post is the fuller account.

I withdrew the submission, and I said my piece on the way out, which I'll stand behind here rather than repeat at length: the old policy drew the correct line — AI-generated code with no human behind it, not allowed; AI-assisted code that a human reviewed, tested and stands behind, allowed. The new policy erases that line. It stops judging software by whether it's good, tested and maintained, and starts judging it by how it was typed.

I understand where the policy comes from. Maintainers are drowning in low-effort AI submissions, and I have real sympathy for that — I wrote a whole post about the open source community's fraught relationship with AI before I was ever personally on the receiving end of it. Flathub's repo, Flathub's rules. But I think the blanket version of the rule is a mistake, and I think this app is a concrete counterexample: working GPL software, architected and reviewed by a human, in a category the Linux desktop has needed for decades. The policy does allow exceptions for "mature, well-maintained projects", so perhaps Moments and Flathub will meet again down the track. The door's open on my side.

In the meantime, the Flatpak bundles work everywhere Flatpak does, and updates are one download away.

What I'd ask of you

Three things, in order:

Install it. Point it at a folder of photos or an Immich server and see what you think. It's a download and two commands.
Star the repo. github.com/justinf555/Moments — discovery is the thing losing Flathub actually cost this project, and a star is the closest substitute GitHub offers.
Tell me what's broken or missing. Issues for bugs and feature requests, Discussions for everything else. This is the part of open source no AI can do: real people, with real photo libraries, telling you what actually matters.

And if you're an experienced engineer who's been sitting on an idea for years because you couldn't find the time — that's the real takeaway of the wager. The time problem is the one that just changed. Go and settle an argument of your own.

DEV Community: Justin - FromTheArchitect

Sortable Columns in GTK4: ColumnView, ColumnViewSorter and GridView

Where we left off

A table is a list with columns

Sizing columns

Clickable headers need wiring

Sort on the value behind the label

What the sorter does with each click

Keeping the table sorted when a photo changes

The same photos as a grid

Sharp edges

Next up

Keeping a GTK4 SortListModel in Order When Items Change

Where we left off

Reporting a change in place

A store that reports

Taking a task out

What the log showed

At scale

The change nobody reported

When a reusable model is worth it

Which fix to use

Next up

Filtering and Sorting Without Re-querying: FilterListModel and SortListModel

Where we left off

The stack

Task has to become a GObject

Searching and hiding with filters

Why a done task didn't hide

Re-sorting after the data changes

Binding rows with expressions

What happens to the selection

Avoiding a reference cycle in your handlers

Sharp edges

Next up

Selection, Modelled: Why GTK4 Puts Selection in the Model, Not the View

Where we left off

Three models, one interface

SingleSelection and the autoselect surprise

MultiSelection doesn't have a selected property

Setting selection from code

Sharp edges

Next up

Your First Factory: GtkListView and the Bind/Unbind Rhythm

Where we left off

The four signals, not two

Why unbind is the fix, not bind doing more

The other kind of factory

Sharp edges

Next up

Stop Thinking in Rows: GListModel and the Modern List Mindset

The list you'd build without thinking

Where that breaks

GListModel: data as the source of truth

The other half, briefly

The payoff: update the model, not the view

So which list do you actually build?

Sharp edges

Next up

GtkApplicationWindow vs AdwApplicationWindow: Which Window a GNOME App Should Use

Two windows, and the one you should reach for

GtkApplicationWindow: the honest baseline

AdwApplicationWindow: no titlebar slot at all

AdwHeaderBar: the bar itself

AdwToolbarView: the chrome manager

Putting the shell together

Sharp edges

Next up

A Field Guide to GTK Widgets

The problem with the reference

What a "field guide" means here

The modern GTK mindset

How the series is organised

The code

Why Rust

Next up: the application shell

Excavating Legacy ETL: The AI Never Asserts a Fact It Could Look Up

Why pointing an LLM at the XML doesn't work

The one rule the whole design hangs on

Layer one: facts

Why `unbind` is the fix, not `bind` doing more