Adw – 1: Migrating between development versions
Description: Reference for Adw-1: Migrating between development versions

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