Libadwaita

If you target a certain platform with your GUI, you will want to follow the platform's Human Interface Guidelines (HIG). With a GTK application, chances are the platform is either elementary OS or GNOME. In this chapter we will discuss how to follow GNOME's HIG with libadwaita.

Libadwaita is a library augmenting GTK 4 which:

  • provides widgets to better follow GNOME's HIG
  • provides widgets to let applications change their layout based on the available space
  • integrates the Adwaita stylesheet
  • allows runtime recoloring with CSS variables
  • adds API to support the cross-desktop dark style preference

In order to use the Rust bindings, add the libadwaita crate as dependency by executing:

cargo add libadwaita --rename adw --features v1_5

The versions of the gtk4 and libadwaita crates need to be synced. Just remember that when you update one of them to the newest version to update the other one as well.

Installation of the library itself works similar to GTK. Just follow the installation instruction that is suitable for your distribution.

Linux

Fedora and derivatives:

sudo dnf install libadwaita-devel

Debian and derivatives:

sudo apt install libadwaita-1-dev

Arch and derivatives:

sudo pacman -S libadwaita

macOS

brew install libadwaita

Windows

If using gvsbuild

If you used gvsbuild to build GTK 4:

gvsbuild build libadwaita librsvg

If building manually with MSVC:

From the Windows start menu, search for x64 Native Tools Command Prompt for VS 2019. That will open a terminal configured to use MSVC x64 tools. From there, run the following commands:

cd /
git clone --branch libadwaita-1-3 https://gitlab.gnome.org/GNOME/libadwaita.git --depth 1
cd libadwaita
meson setup builddir -Dprefix=C:/gnome -Dintrospection=disabled -Dvapi=false
meson install -C builddir

Work around missing icons

This workaround is needed for GTK < 4.10 due to this issue.

gvsbuild

From a command prompt:

xcopy /s /i C:\gtk-build\gtk\x64\release\share\icons\hicolor\scalable\apps C:\gtk-build\gtk\x64\release\share\icons\hicolor\scalable\actions
gtk4-update-icon-cache.exe -t -f C:\gtk-build\gtk\x64\release\share\icons\hicolor

Manually with MSVC

xcopy /s /i C:\gnome\share\icons\hicolor\scalable\apps C:\gnome\share\icons\hicolor\scalable\actions
gtk4-update-icon-cache.exe -t -f C:\gnome\share\icons\hicolor