Migrating Between Development Versions

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.

Migrating From alpha 1 to alpha 2

Adapt to view switcher API Changes

AdwViewSwitcher, AdwViewSwitcherBar and AdwViewSwitcherTitle now use AdwViewStack instead of GtkStack.

You should stop using GtkStack:transition-type and GtkStack:transition-duration properties before switching to AdwViewStack.

Adapt to Stylesheet Changes

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.

Migrating From alpha 2 to alpha 3

Stop Using AdwValueObject With Non-string Values

AdwValueObject has been removed. The typical use for storing strings in combination with GListStore can be replaced by using GtkStringList, others cases can be replaced by creating your own objects to store those values .

Adapt to AdwEnumValueObject API Changes

AdwEnumValueObject has been renamed to AdwEnumListItem.

Adapt to Window API Changes

The child property in AdwWindow and AdwApplicationWindow has been renamed to content.

Adapt to AdwLeaflet API Changes

The hhomogeneous-folded, vhomogeneous-folded, hhomogeneous-unfolded, and 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.

The interpolate-size property has been removed with no replacement, it’s always enabled when AdwLeaflet:homogeneous is set to FALSE.

Adapt to View Switcher API Changes

The auto view switcher policy has been removed. AdwViewSwitcher only has narrow and wide policies; if you had used the auto policy, use an AdwSqueezer with two view switchers inside.

Adapt to AdwViewSwitcher API Changes

The narrow-ellipsize property has been removed. Narrow view switchers always ellipsize their labels, wide switchers never do.

Adapt to AdwViewSwitcherBar API Changes

The policy property has been removed. If you had used it, use a plain AdwViewSwitcher in a GtkActionBar instead.

Adapt to AdwViewSwitcherTitle API Changes

The policy property has been removed, the behavior is similar to the removed auto policy. If you had used wide or narrow policies, use an AdwSqueezer with an AdwViewSwitcher and an AdwWindowTitle inside, with the switcher having the desired policy.

Adapt to AdwAvatar API Changes

The adw_avatar_draw_to_pixbuf() function have been removed, use the newly added adw_avatar_draw_to_texture() instead. GdkTexture implements GIcon, so it should just work for that case.

adw_avatar_draw_to_texture() does not have the size parameter. Instead, it uses the avatar’s current size, with no replacement.

Use AdwStyleManager Instead of GtkSettings:gtk-application-prefer-dark-theme

Using GtkSettings:gtk-application-prefer-dark-theme to control dark appearance is not supported anymore, set AdwStyleManager:color-scheme to 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 ADW_COLOR_SCHEME_FORCE_DARK instead.

If your application is using light appearance, make sure it works wit dark appearance as well, or set the color scheme to ADW_COLOR_SCHEME_FORCE_LIGHT otherwise.

Adapt to Stylesheet Changes

Adapt to Header Bar, Action Bar and Toolbar Style Changes

When possible, buttons in GtkHeaderBar and GtkActionBar will use flat appearance by default.

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 AdwButtonContent);
• Menu buttons containing an arrow;
• AdwSplitButton;
• Any other button with the .flat style class.

The following buttons keep default appearance:

• Text-only buttons;
• Buttons with other content;
• Buttons within widgets containing the .linked class;
• Buttons with the .suggested-action, .destructive-action or .opaque style classes.
• Buttons with the .raised style class.

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 .toolbar style class now, instead of making every button appear flat.

Adjusting Icon+Arrow Menu Buttons

If you had menu buttons containing an icon and a dropdown arrow, switch to GtkMenuButton:icon-name and set the GtkMenuButton:always-show-arrow property to TRUE.

Adjusting Text-only Buttons

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.

Adjusting Split Buttons

If you had split buttons implemented via a GtkBox with the .linked style class and two buttons packed inside, use AdwSplitButton as follows:

<object class="AdwSplitButton">
  <property name="menu-model">some_menu</property>
  <property name="icon-name">view-list-symbolic</property>
</object>

Adjusting Linked Buttons

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>

Custom Adjustments

The .flat and .raised style classes can always be used to override the default appearance.

Important: the GtkButton:has-frame property will not be set to FALSE when a button gets the flat appearance automatically. It also cannot be set to TRUE to make a button raised, the style class should be used directly instead.

Migrating From alpha 3 to alpha 4

Adapt to AdwActionRow and AdwExpanderRow API Changes

The 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.

Adapt to AdwExpanderRow API Changes

The adw_expander_row_add() function has been renamed to adw_expander_row_add_row().

Adjusting Header Bar Icons

If you’re using the object-select-symbolic icon in a header bar button (typically for selection mode), use selection-mode-symbolic instead.

Adapt to Stylesheet Changes

Stop Using the .sidebar Style Class

The .sidebar style class is now deprecated, although still works for compatibility reasons. The main use case - adjusting the background color of GtkListBox and GtkListView - can now be done with the .navigation-sidebar style class on those widgets instead, along with adjusting the item selection style. The border can be replicated by manually adding a GtkSeparator.

Adapt to the popover.combo Style Removal

The .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.

Adapt to List Style Changes

For boxed lists we now have the .boxed-list style class that matches the name of the design pattern. If you were using the .content style class, you should use .boxed-list instead.

The .content style class currently remains for compatibility purposes.

Neither the .content style class nor the .boxed-list style class work for GtkListView, as the widget cannot currently be used for the boxed list pattern.

Migrating From alpha 4 to beta 1

Adapt to AdwSwipeTracker API Changes

The 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 exactly like begin-swipe did, and can be used instead of it.

The type of the duration parameter in AdwSwipeTracker::end-swipe has changed from gint64 to guint.

Adapt to AdwTabView API Changes

The 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.

Adapt to AdwLeaflet API Changes

The can-swipe-back and can-swipe-forward properties have been renamed to AdwLeaflet:can-navigate-back and 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 with AdwLeaflet:child-transition-params, allowing to customize the animation. Unlike the duration, spring parameters are also used for animation triggered by swipe gestures.

Adapt to 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.

Adapt to 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.

The adw_carousel_scroll_to_full() method has been removed. Instead, adw_carousel_scroll_to() has got an additional parameter animate.

Adapt to AdwPreferencesWindow API Changes

The 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.

Adapt to AdwViewStack API Changes

AdwViewStack has stopped supporting transitions. As such, the interpolate-size and transition-running properties have been removed with no replacement.

Adapt to Miscellaneous Changes

The adw_ease_out_cubic() function has been removed. Instead, adw_easing_ease() can be used with the ADW_EASE_OUT_CUBIC parameter.

Adapt to Stylesheet Changes

Adapt to the button.outline Style Removal

The .outline style class has been removed with no replacement. The regular button style should be used instead.

Adapt to the content-view Check Button Style Removal

The selection mode GtkCheckButton style, used inside views with the .content-view has been changed into a separate style class .selection-mode that can be applied directly onto check buttons.