The Application Shell: GtkApplicationWindow vs AdwApplicationWindow
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…
This is the first post in a series about choosing the right GTK widget for your application. We focus on the window, the first widget you need when creating a GNOME app. The toolkit offers two options: GtkApplicationWindow from GTK itself, or AdwApplicationWindow from Libadwaita. The reference provides accurate descriptions but doesn't clarify which one to choose.
The recommended choice is AdwApplicationWindow for shipping as a GNOME app in 2026. The reason lies in the structural differences between the two windows. GtkApplicationWindow is the basic GTK window, with a dedicated titlebar slot. AdwApplicationWindow, on the other hand, removes the titlebar slot entirely and treats the window's content as a single child that fills the entire area.
This change opens up the possibility for adaptive layouts, where the header bar can be placed wherever needed, such as the top of a collapsible sidebar or inside a split view. By moving the titlebar from a dedicated slot to an ordinary widget, AdwApplicationWindow frees the window from dictating where chrome (titlebar, window controls) can live. This aligns with the platform's adaptive design approach, enabling layout patterns like collapsible sidebars and page slides.
To create an AdwApplicationWindow, you build an AdwApplicationWindow using libadwaita's builder API, setting the window title and content. The header bar becomes an ordinary widget within the content, allowing for flexible layout arrangements. The AdwHeaderBar, a customizable version of GtkHeaderBar, becomes the header bar widget. It offers similar functionality to GtkHeaderBar, with the added benefit of being built to live inside the content and integrate with Libadwaita's adaptive containers and responsive behavior.
In summary, the GtkApplicationWindow's titlebar slot limits layout flexibility, while AdwApplicationWindow's single-child approach enables adaptive layouts. AdwHeaderBar, the recommended header bar widget, provides a title and closable functionality out of the box and integrates seamlessly with Libadwaita's responsive features.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
