beeware / beeware/toga

Upgrade to GTK4 and libadwaita for Linux

Open
#3,069 30 comments 0 reactions 0 assignees View on GitHub
enhancement gtk linux
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
9h 45m
Merged PRs (30d)
58

Description

### What is the problem or limitation you are having?

The current implementation backend for Linux uses GTK3. While this was a great choice when Toga was first created, it is now in maintenance only mode. Apps written in GTK3 now look out of place on a new GNOME desktop and no longer have the modern feel that users are expecting when creating a new app. GTK4 and libadwaita have the following advantages:

1. More modern looking including accent colors, window decorations, and dialogs
2. Adaptability for different screen sizes and orientations (including Linux phones)
3. Better performance with rendering done with render nodes and GPU offloading instead of frame rendering
4. Event controllers
5. Easier support for Composite Widgets

GTK4 was initially released 4 years ago, and it is in all distros at this point (even Debian stable). Libadwaita 1.0 is also everywhere, although some of the newer dialogs and widgets are supported up to version 1.6 which is the latest.

### Describe the solution you'd like

Unfortunately, the GTK3 to GTK4 change is a breaking change and it would be a large project to upgrade all the Toga widgets. One approach to work on this would be to slowly transition by supporting both, and then remove the GTK3 calls once it has reached feature parity:

```
if Gtk.get_major_version() == 3:
... # GTK3 calls
else:
... # GTK4 equivalent
```

We could also set an environmental variable for development, and then load the right library version based on it:

```
import gi

gtk_version = "4.0" if os.getenv("TOGA_UPGRADE_GTK") == "4" else "3.0"

gi.require_version("Gtk", gtk_version)
gi.require_version("Gdk", gtk_version)
```

### Describe alternatives you've considered

We could keep GTK3, maybe even theme it to make it look more modern like https://github.com/rafaelmardojai/firefox-gnome-theme.

### Additional context

GTK3 Toga Hello World:
![image](https://github.com/user-attachments/assets/303d13fe-5d6c-487e-9fdb-50e6598c4ee4)
![image](https://github.com/user-attachments/assets/25919dac-8f38-452b-a40e-2906ef693ad1)

GTK4 and libadwaita Hello World:
![image](https://github.com/user-attachments/assets/24f5b582-ddcf-49ae-a29a-897ff3437033)
![image](https://github.com/user-attachments/assets/f585c1a8-1e66-4bed-9387-65347fb8430c)

Checklist of GTK4 Support:

- [x] app
- [x] fonts
- [x] icons
- [ ] images
- [ ] keys
- [x] paths
- [x] window
- [x] activityindicator
- [x] base
- [x] box
- [x] button
- [x] canvas
- [x] dateinput
- [ ] detailedlist
- [ ] divider
- [ ] imageview
- [X] label
- [ ] multilinetextinput
- [ ] numberinput
- [ ] optioncontainer
- [x] paswordinput
- [ ] progressbar
- [ ] scrollcontainer
- [ ] selection
- [ ] slider
- [ ] splitcontainer
- [ ] switch
- [ ] table
- [x] textinput
- [ ] timeinput
- [ ] tree
- [ ] webview

Contributor guide

Open the contributing guide

Research direction

The issue describes a repository-wide Linux backend migration from GTK3 to GTK4 and libadwaita, with a checklist showing completed and missing widgets. Start by locating the Linux GTK implementation and comparing one unchecked widget with its GTK4 requirements. No specific file, test, or entry point is named, and the overall completion target is feature parity.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.