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
The public colors theme_selected_bg_color
and theme_selected_fg_color
have
been renamed to accent_bg_color
and accent_fg_color
.
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
style class; - Buttons with the
.suggested-action
or.destructive-action
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.