This guide outlines the differences between Libadwaita development releases. It assumes you’ve already migrated from Libhandy 1.4 to Libadwaita, or you created a new project using a development release of Libadwaita.
If you want to migrate from Libhandy 1.4 to the latest Libadwaita release, follow this guide.
AdwValueObject has been removed. The typical use for storing strings in
GListStore can be replaced by using
GtkStringList, others cases can be replaced by creating your own
objects to store those values .
AdwEnumValueObject has been renamed to
AdwLeaflet API Changes
vhomogeneous-unfolded properties have been replaced by a single
AdwLeaflet:homogeneous property, set to
TRUE by default, applied when
the leaflet is folded for the opposite orientation.
When unfolded, children are never homogeneous. Use
GtkSizeGroup to make
them homogeneous if needed.
interpolate-size property has been removed with no replacement, it’s
always enabled when
AdwLeaflet:homogeneous is set to
AdwViewSwitcher API Changes
narrow-ellipsize property has been removed. Narrow view switchers always
ellipsize their labels, wide switchers never do.
AdwViewSwitcherBar API Changes
AdwViewSwitcherTitle API Changes
policy property has been removed, the behavior is similar to the removed
auto policy. If you had used
narrow policies, use an
AdwSqueezer with an
AdwViewSwitcher and an
with the switcher having the desired policy.
AdwAvatar API Changes
adw_avatar_draw_to_texture() does not have the
size parameter. Instead, it
uses the avatar’s current size, with no replacement.
AdwStyleManager Instead of
GtkSettings:gtk-application-prefer-dark-theme to control dark
appearance is not supported anymore, set
ADW_COLOR_SCHEME_PREFER_DARK and make sure the application can work with light
appearance as well. If that’s not possible, set it to or
If your application is using light appearance, make sure it works wit dark
appearance as well, or set the color scheme to
The following rules are used when deciding when to make buttons flat or not:
The following buttons get flat appearance:
- Icon-only buttons;
- Buttons with an icon and a label (using
- Menu buttons containing an arrow;
- Any other button with the
The following buttons keep default appearance:
- Text-only buttons;
- Buttons with other content;
- Buttons within widgets containing the
- Buttons with the
- Buttons with the
It’s important to avoid ambiguous layouts, for example text-only buttons with no icon, since such a button would be indistinguishable from the window title without hovering it.
In rare cases, the existing layout may need a redesign to work with the new style.
The same rules are also used for the
style class now, instead of making every button appear flat.
If you had text-only buttons, consider using
AdwButtonContent. For example,
the following button:
<object class="GtkButton"> <property name="label" translatable="yes">_Open</property> <property name="use-underline">True</property> </object>
can be changed into:
<object class="GtkButton"> <property name="child"> <object class="AdwButtonContent"> <property name="icon-name">document-open-symbolic</property> <property name="label" translatable="yes">_Open</property> <property name="use-underline">True</property> </object> </property> </object>
One exception are the two primary buttons in a dialog, for example, “Cancel” and “Open”. Those buttons should retain their default appearance.
<object class="AdwSplitButton"> <property name="menu-model">some_menu</property> <property name="icon-name">view-list-symbolic</property> </object>
For other linked together buttons, simply stop linking them.
If multiple linked groups were used to separate different groups of actions, insert extra spacing as follows:
<object class="GtkSeparator"> <style> <class name="spacer"/> </style> </object>
GtkButton:has-frame property will not be set to
FALSE when a button gets the flat appearance automatically. It also cannot be
TRUE to make a button raised, the style class should be used directly instead.
AdwExpanderRow API Changes
use-underline property and its accessors have been removed. Use
AdwPreferencesRow:use-underline and its accessors instead.
The title and subtitle have markup enabled, make sure to escape it with
g_markup_escape_text() if this is unwanted.
AdwExpanderRow API Changes
adw_expander_row_add() function has been renamed to
If you’re using the
object-select-symbolic icon in a header bar button
(typically for selection mode), use
.sidebar style class is now deprecated,
although still works for compatibility reasons. The main use case - adjusting
the background color of
GtkListView - can now
be done with the
class on those widgets instead, along with adjusting the item selection style.
The border can be replicated by manually adding a
.combo popover style class has been removed. Use
.menu instead. You may need to remove
manually added margins, padding or minimum height from the list items inside
while doing it.
.content style class currently remains for compatibility purposes.
.content style class nor the
.boxed-list style class work
GtkListView, as the widget cannot currently be used for the
boxed list pattern.
AdwSwipeTracker API Changes
AdwSwipeTracker::begin-swipe signal is now emitted immediately before
the swipe starts, after the drag threshold has been reached, and it has lost its
direction parameter. The new
AdwSwipeTracker::prepare signal behaves
begin-swipe did, and can be used instead of it.
The type of the
duration parameter in
AdwTabView API Changes
HdyTabView:shortcut-widget property has been removed with no replacement;
AdwTabView automatically installs shortcuts with the
GTK_SHORTCUT_SCOPE_MANAGED scope, so they are automatically available
throughout the window without the need to set shortcut widget.
If some of these shortcuts conflict with another widget, the latter has priority, and it should work automatically if the widget correctly stops event propagation.
AdwLeaflet API Changes
can-swipe-forward properties have been renamed to
AdwLeaflet:can-navigate-forward, along with their accessors. The new
properties also handle keyboard and mouse shortcuts in addition to swipes.
AdwLeaflet now uses spring animations instead of timed animations for child
transitions. As such, the
child-transition-duration property has been replaced
AdwLeaflet:child-transition-params, allowing to customize the
animation. Unlike the duration, spring parameters are also used for animation
triggered by swipe gestures.
AdwFlap API Changes
AdwFlap now uses spring animations instead of timed animations for reveal
animations. As such, the
reveal-duration property has been replaced with
AdwFlap:reveal-params, allowing to customize the animation. Unlike the
duration, spring parameters are also used for transitions triggered by swipe gestures.
AdwCarousel API Changes
AdwCarousel now uses spring animations instead of timed animations for
scrolling. As such, the
animation-duration property has been replaced with
AdwCarousel:scroll-params, allowing to customize the animation. Unlike
the duration, spring parameters are also used for animation triggered by swipe gestures.
adw_carousel_scroll_to_full() method has been removed. Instead,
adw_carousel_scroll_to() has got an additional parameter
AdwPreferencesWindow API Changes
can-swipe-back property have been renamed to
AdwPreferencesWindow:can-navigate-back, along with its accessors. The
new properties also handle keyboard and mouse shortcuts in addition to swipes.
AdwViewStack API Changes
AdwViewStack has stopped supporting transitions. As such, the
transition-running properties have been removed with
adw_ease_out_cubic() function has been removed. Instead,
adw_easing_ease() can be used with the
.outline style class has been removed with no replacement. The regular
button style should be used instead.