Libadwaita is being developed as a successor to Libhandy 1.4. As such, it offers to GTK 4 many features Libhandy was offering to GTK 3.
Migrating from Libhandy 1.4 to Libadwaita implies migrating from GTK 3 to 4. This guide only focuses on on Libhandy and Libadwaita, and is designed to be used together with the GTK 3 to 4 migration guide.
If you notice that some differences between Libhandy and Libadwaita are missing in this guide, please report them.
The steps outlined in the following sections assume that your software is working with Libhandy 1.4, which is the latest stable release of Libhandy 1.x. It includes all the necessary APIs and tools to help you port your software to Libadwaita. If you are using an older version of Libhandy, you should first get your software to build and work with Libhandy 1.4.
Over the years, a number of functions, and in some cases, entire widgets have been deprecated. These deprecations are clearly spelled out in the API reference, with hints about the recommended replacements. The API reference for Libhandy 1.4 also includes an index of all deprecated symbols.
Following GTK4’s emphasis on composition and delegation over subclassing,
AdwHeaderBar are no longer derivable. As a
replacement, you can subclass
GtkBox and include a leaflet or a
header bar as a child widget.
HdyKeypad has been removed from Libadwaita. Applications that had used it can
copy it in tree instead.
The following named colors have been removed from the stylesheet in Libadwaita:
Applications should not use them.
The preferred way to use icons in applications is to copy them into the
application and to bundle them via
Referencing system icons won’t work in Libadwaita other than for icons GTK
itself ships, so make sure to bundle the icons.
HdyFlap provides the “content”, “flap” and “separator” properties that can be
used for managing children instead of
GtkContainer API. In Libadwaita
AdwFlap:separator are the only way to manage
Adding children in a UI file still works.
This section outlines porting tasks that you need to tackle when you get to the point that you actually build your application against Libadwaita 1. Making it possible to prepare for these in GTK 3 would have been either impossible or impractical.
Same as GTK itself, all widgets that have children have a new API to replace
The following widgets that formerly subclassed
GtkBin have a “child” property now:
For other widgets use the following replacements:
Adding children in a UI file still works.
HdySearchBar has been removed, use
HdyWindowHandle has been removed, use
AdwClamp API Changes
HdyClamp previously had
.large style classes
depending on the current size of its child. These style classes are now
added to the child instead of the clamp itself.
AdwComboRow API Changes
expr = gtk_property_expression_new (ADW_TYPE_ENUM_VALUE_OBJECT, NULL, "nick"); model = G_LIST_MODEL (adw_enum_list_model_new (GTK_TYPE_ORIENTATION)); adw_combo_row_set_expression (row, expr); adw_combo_row_set_model (row, model);
AdwHeaderBar API Changes
GtkHeaderBar:show-title-buttons property has been split into
AdwHeaderBar:show-end-title-buttons to simplify creating multi-pane
layouts. The corresponding getter and the setter have been split as well.
AdwWindowTitle widget may be useful for replacing the title and subtitle.
HdyHeaderGroup has been removed. Its behavior can be replicated by changing
AdwHeaderBar:show-end-title-buttons properties depending on the
layout, for example binding them to the
<object class="AdwLeaflet" id="leaflet"> <child> <object class="GtkBox"> <property name="orientation">vertical</property> <object class="AdwHeaderBar"> <binding name="show-end-title-buttons"> <lookup name="folded">leaflet</lookup> </binding> </object> ... </object> </child> ... <child> <object class="GtkBox"> <property name="orientation">vertical</property> <object class="AdwHeaderBar"> <binding name="show-start-title-buttons"> <lookup name="folded">leaflet</lookup> </binding> </object> ... </object> </child> </object>
AdwSqueezer API Changes
The child properties of
HdySqueezer have been converted into
page objects, similarly to
GtkStack. For example,
adw_squeezer_page_set_enabled() should be used to replace
AdwAvatar API Changes
HdyAvatar:loadable-icon property has been removed along with its getter
and setter. It can be replaced by
hdy_avatar_draw_to_pixbuf_async() function has been removed, use the
regular adw_avatar_draw_to_pixbuf() instead.
Most widgets don’t have a backdrop state anymore, and the following public colors have been removed:
.list-button style class has been renamed to the more accurate name
The public colors
been renamed to
If you were using
theme_selected_bg_color as a text color, use
accent_color instead to make sure the text is readable. You can also use the
.accent style class to apply the correct color.