GTK3 → GTK4 Migration Assessment

[TurboGit]

For the record here is a document contributed by @masterpiga. The document is an analysis from Claude AI about the migration. Post here in the hope it will help.

GTK3 → GTK4 Migration Assessment: darktable

Assessment date: March 2026

---

1. Executive Summary

Migrating darktable from GTK3 to GTK4 is a large, high-risk, multi-month undertaking. The codebase has ~506,000 lines of C across 501 source files, of which roughly 205 files touch GTK directly. darktable is not a typical GTK application: it has built an entire second layer of custom widgets on top of GTK (the bauhaus system for sliders and combo boxes, and the dtgtk library of icon buttons and range selectors), and its main canvas relies on hand-crafted event handling for pixel-accurate interactions with images. These layers are precisely what GTK4 changes most radically.

The migration is feasible but requires deliberate phasing. The core GTK API changes are mechanical enough to automate large portions of the work, but the event system rewrite and the bauhaus custom widget system require careful design decisions that go beyond search-and-replace. A realistic estimate with AI assistance is 12–18 weeks of focused effort, of which roughly 65% can be handled autonomously by an AI coding assistant, with the remaining 35% requiring human judgment, visual validation, and platform testing.

---

2. What Changed Between GTK3 and GTK4 (and Why It Matters)

If you are unfamiliar with the differences between the two toolkit versions, here is what you need to understand. GTK4 is not a minor revision: it is a deliberate modernisation that broke backward compatibility in several fundamental areas.

2.1 The Event System Was Completely Redesigned

In GTK3, user input (mouse clicks, keyboard presses, pointer motion, scrolling) was delivered as raw event structures (GdkEventButton, GdkEventKey, GdkEventMotion, etc.) passed directly to signal callback functions. A handler for a mouse click looked like:

// GTK3
gboolean on_click(GtkWidget *widget, GdkEventButton *event, gpointer data) {
    if (event->button == 1) { ... }
}
g_signal_connect(widget, "button-press-event", G_CALLBACK(on_click), NULL);

In GTK4 this pattern is entirely gone. The "button-press-event", "key-press-event", "motion-notify-event", and similar signals no longer exist. Instead, GTK4 introduces a family of event controller objects (GtkGestureClick, GtkEventControllerKey, GtkEventControllerMotion, GtkEventControllerScroll, etc.) that you attach to widgets:

// GTK4
GtkGestureClick *click = gtk_gesture_click_new();
g_signal_connect(click, "pressed", G_CALLBACK(on_click), NULL);
gtk_widget_add_controller(widget, GTK_EVENT_CONTROLLER(click));

This is not a rename — it is a fundamentally different model. Every single event handler in the application needs to be examined and rewritten individually. darktable has approximately 1,192 g_signal_connect calls across the codebase, a significant fraction of which use the deprecated event signal names.

2.2 GtkContainer and Widget Packing Were Simplified

GTK3 had a GtkContainer base class with methods like gtk_container_add(), and GtkBox had gtk_box_pack_start() / gtk_box_pack_end() with boolean parameters controlling expansion and fill. GTK4 removed GtkContainer entirely and simplified the packing API:

// GTK3
gtk_box_pack_start(GTK_BOX(box), child, TRUE, TRUE, 4);

// GTK4
gtk_box_append(GTK_BOX(box), child);  // expansion/fill handled via child properties

darktable has ~631 gtk_box_pack_start/end calls across 68+ files. These are mechanical to update but numerous.

2.3 GtkEventBox Was Removed

GtkEventBox was a GTK3 trick: a transparent container that added event-handling capability to widgets that otherwise would not receive mouse/keyboard input. GTK4 removed this widget because in GTK4, all widgets can receive events via the new event controller system. The problem for darktable is that GtkEventBox is used as the base class for several custom widgets in src/dtgtk/ (specifically GtkDarktableIcon and GtkDarktableRange). Those widgets need to be rebased onto a different parent.

2.4 GtkMenu and the Entire Menu System Were Removed

GtkMenu, GtkMenuItem, GtkMenuBar, and related types were completely removed in GTK4. They are replaced by a model-based system using GMenu (a data model) rendered via GtkPopoverMenu (the visual component). This is not a trivial rename: the programming model is different enough that context menus and popup menus need to be redesigned, not just ported.

darktable uses menus in ~28 files (~360 occurrences).

2.5 The Drawing Model Changed

GTK3 widgets overrode the "draw" signal to receive a cairo_t * context and paint themselves:

// GTK3
g_signal_connect(widget, "draw", G_CALLBACK(my_draw), NULL);
static gboolean my_draw(GtkWidget *w, cairo_t *cr, gpointer data) { ... }

In GTK4, GtkDrawingArea uses a dedicated draw function registered once:

// GTK4
gtk_drawing_area_set_draw_func(GTK_DRAWING_AREA(widget), my_draw, NULL, NULL);
static void my_draw(GtkDrawingArea *da, cairo_t *cr, int w, int h, gpointer data) { ... }

Cairo itself still works and the drawing code inside the function is largely unchanged — only the registration mechanism changed. There are ~414 occurrences of custom drawing across ~104 files.

2.6 gtk_main() Was Removed

GTK4 moved to a GApplication-based event loop. gtk_main() and gtk_main_quit() are gone. darktable's main entry point will need to be restructured around g_application_run().

2.7 gtk_widget_show_all() Was Removed

In GTK3, widgets were hidden by default and you had to call gtk_widget_show() or gtk_widget_show_all() (recursive) to make them visible. In GTK4, widgets are visible by default, and gtk_widget_show_all() does not exist. Explicit gtk_widget_set_visible(FALSE) is used to hide things. This is widespread in darktable and produces both compilation errors and invisible widgets if not handled.

2.8 GdkWindow → GdkSurface

GdkWindow was renamed GdkSurface and its API was revised. Most of darktable's direct gdk_window_* usage is incidental (e.g., inside gdk/cairo bridge calls) and lower risk.

2.9 What Did NOT Change (Good News)

• Cairo is still the primary drawing API. Drawing code inside callbacks is largely unchanged.
• GObject / GLib (the type system, memory management, signals on non-widget objects) is fully compatible.
• Pango (text layout) is compatible.
• CSS theming works in GTK4 with minor selector adjustments.
• GtkTreeView is deprecated in GTK4 but still compiles and runs. Replacement is not urgent.
• GtkScrolledWindow, GtkLabel, GtkEntry, GtkCheckButton, GtkSpinButton and most basic widgets are compatible with minor API adjustments.

---

3. Codebase Audit

3.1 Scale

Metric	Value
Total source files	501
Total lines of code	~506,000
Files importing gtk.h	107
Files using GtkWidget / gtk_widget_*	205
g_signal_connect calls	~1,192
Custom widget files (src/dtgtk/)	30
bauhaus system (src/bauhaus/)	4,530 lines
Image operation modules (src/iop/)	105 files
Library modules (src/libs/)	40 files

3.2 The Two Custom Widget Layers

darktable has two internal GTK widget frameworks that are critical to understand before any migration work begins.

The bauhaus system (src/bauhaus/bauhaus.c, 4,098 lines + bauhaus.h, 432 lines) is the workhorse UI component for image processing parameters. It implements three widget types — a slider, a combo box, and a button — all rendered from scratch on a GtkDrawingArea using Cairo. It handles its own mouse, keyboard, and scroll input via raw GdkEvent structures, and manages a custom popup window for the expanded slider/combobox view. Every single image processing module (all 105 of them in src/iop/) uses bauhaus widgets. This system is the single largest migration risk in the entire codebase.

The dtgtk widget library (src/dtgtk/, 30 files, ~17,800 lines) provides icon buttons, gradient sliders, range selectors, thumbnail widgets, and painting utilities. It subclasses GTK base types and adds Cairo-rendered icons via a function-pointer pattern (DTGTKCairoPaintIconFunc). The paint.c file alone defines 80+ icon painting functions. Several dtgtk widgets subclass GtkEventBox (which is removed in GTK4) and must be rebased.

3.3 What Is Surprisingly Unproblematic

No OpenGL-GTK binding. darktable's GPU processing pipeline (OpenCL) does not use GtkGLArea or any direct GTK-OpenGL bridge. The GPU work happens entirely outside GTK. This eliminates one of the most painful GTK4 migration scenarios.

Modern GObject declarations. The custom widgets already use the G_DECLARE_FINAL_TYPE / G_DEFINE_FINAL_TYPE macros introduced to modernise GObject code. These macros are GTK4-compatible.

GtkTreeView is not an emergency. While GTK4 deprecates GtkTreeView in favour of GtkListView/GtkColumnView, it still compiles and runs under GTK4. The ~32 files using it (tagging, filtering, collection browser, metadata, styles, masks) do not block the migration.

---

4. The Seven Migration Categories

Category 1 — Event System Rewrite (CRITICAL)

Affected files: 73–84
Occurrences: ~499 GdkEvent type references + ~219 deprecated signal connections
Effort share: ~35% of total migration work

Every callback connected to "button-press-event", "button-release-event", "motion-notify-event", "key-press-event", "key-release-event", "scroll-event", and similar signals must be refactored. The bauhaus system is the epicentre: it bypasses GTK's signal system and polls GdkEvent structures directly in its own event loop. The darkroom canvas (src/views/darkroom.c) is the second largest problem, as it implements pixel-accurate tablet/stylus interactions that depend on event field access.

Each widget that previously handled raw events needs one or more GtkEventController objects created, connected, and added via gtk_widget_add_controller(). This is not a mechanical transformation — the new gesture objects have different semantics (e.g., GtkGestureDrag encapsulates a full press-move-release sequence that was previously three separate handlers).

Category 2 — bauhaus Custom Widget System (CRITICAL)

Files: src/bauhaus/bauhaus.c (4,098 lines), src/bauhaus/bauhaus.h
Effort share: ~25% of total migration work

The bauhaus system needs a near-complete rewrite of its input handling layer. Its draw callbacks need updating from the "draw" signal pattern to gtk_drawing_area_set_draw_func(). Its popup window lifecycle interacts with the window system in ways that changed in GTK4 (GdkWindow → GdkSurface, window hints API). The global dt_bauhaus_t state struct uses GTK3 types that need updating. Because all 105 IOP modules depend on bauhaus, any bauhaus bug will break the entire darkroom.

Category 3 — Container and Packing API (HIGH)

Affected files: 68+
Occurrences: ~631
Effort share: ~10% of total migration work

gtk_box_pack_start() and gtk_box_pack_end() → gtk_box_append() / gtk_box_prepend(). gtk_container_add() → widget-specific gtk_xxx_set_child() or append calls. gtk_widget_show_all() → explicit visibility management. These are largely mechanical changes but are spread across the entire codebase. src/libs/modulegroups.c alone has 119 packing calls.

Category 4 — GtkEventBox Removal (HIGH)

Affected files: src/dtgtk/range.c, src/dtgtk/icon.c, parts of src/gui/gtk.c
Effort share: ~5% of total migration work

Widgets subclassing GtkEventBox need to be rebased. In GTK4, the simplest replacement is GtkBox (which now receives events natively via controllers) or GtkWidget itself (for truly custom widgets). The range selector and icon widgets need their base class changed and their event handling migrated to controllers simultaneously.

Category 5 — Menu System (HIGH)

Affected files: ~28
Occurrences: ~360
Effort share: ~10% of total migration work

All context menus and popup menus must be rebuilt using GtkPopoverMenu with GMenu models. This is a conceptual change: GTK3 menus were widget trees you built imperatively; GTK4 menus are data models (like XML action maps) rendered by the framework. The migration for each menu involves defining a GMenu, attaching GAction objects to the widget's action group, and replacing the old construction code. Files most affected: src/libs/tagging.c, src/libs/masks.c, src/libs/collect.c, src/develop/blend_gui.c.

Category 6 — Drawing Callbacks (MEDIUM)

Affected files: ~104 (Cairo usage), ~74 (explicit queue_draw)
Effort share: ~7% of total migration work

The "draw" signal pattern needs updating to gtk_drawing_area_set_draw_func(). The cairo drawing code inside the callbacks is largely unchanged — only the registration mechanism differs. The function signature changes slightly (receives explicit width/height). gtk_widget_queue_draw() and gtk_widget_queue_draw_area() still exist and work.

Category 7 — Application Lifecycle and Miscellaneous (MEDIUM)

Affected files: primarily src/gui/gtk.c (4,787 lines), src/main.c
Effort share: ~8% of total migration work

• gtk_main() → g_application_run() / GtkApplication
• gtk_widget_destroy() → gtk_window_destroy() (for windows) or g_object_unref() (for non-windows)
• gtk_dialog_* changes (GtkDialog is deprecated but still works)
• GdkWindow references → GdkSurface
• Build system: FindGTK3.cmake → GTK4 pkg-config or cmake module
• CSS themes: selector/property audit for GTK4 compatibility

---

5. Migration Strategy and Phasing

Guiding Principles

1. Keep it working at every phase. The codebase should compile and run (even if imperfectly) after each phase. Do not attempt a "big bang" replacement.
2. Start at the foundation, not the leaves. Fix infrastructure (build system, lifecycle, widget base classes) before touching the application logic.
3. Defer non-blocking deprecations. GtkTreeView, GtkDialog, and GtkFileChooser are deprecated but functional in GTK4. Leave them for a later pass.
4. Test bauhaus in isolation first. Build a minimal test harness for the bauhaus widget system before attempting full integration.

Recommended Phases

Phase 0 — Environment Setup (1 week)

• Add GTK4 as a build dependency alongside GTK3
• Create a feature-flagged build path (e.g., -DUSE_GTK4=ON) that compiles against GTK4 headers
• Fix all compilation errors without changing behavior
• Identify the exact GTK4 version floor (GTK4 4.10+ recommended for stability)
• Deliverable: codebase compiles against GTK4 with errors/warnings documented

Phase 1 — Mechanical Fixes (2–3 weeks)

• gtk_box_pack_start/end → gtk_box_append/prepend (automated, 631 calls)
• gtk_container_add → widget-specific append/set_child (automated)
• gtk_widget_show_all → explicit gtk_widget_set_visible (requires semantic check: is "show all" actually needed?)
• gtk_widget_destroy → correct GTK4 destructor per context
• gtk_main → GtkApplication structure in src/gui/gtk.c
• Build system update: CMakeLists.txt, FindGTK4.cmake
• Deliverable: all Phase 1 patterns replaced; application starts up (UI may be broken)

Phase 2 — Custom Widget Base Classes (2–3 weeks)

• Rebase GtkEventBox-derived widgets in src/dtgtk/ onto GTK4-compatible parents
• Update G_DEFINE_TYPE patterns where base class was removed
• Migrate draw signal registration to gtk_drawing_area_set_draw_func() across all dtgtk widgets
• Deliverable: dtgtk widgets compile and render correctly; events still not working

Phase 3 — Event System Migration (4–5 weeks)

• Rewrite bauhaus event handling: press/release/motion/scroll → GtkGesture controllers
• Rewrite darkroom canvas event handling (src/views/darkroom.c) — most complex file
• Migrate all other views: lighttable, map, slideshow
• Migrate dtgtk range selector, thumbnail, and culling event handlers
• Deliverable: basic interaction works; tablet/pressure events tested separately

Phase 4 — Menu System Replacement (2 weeks)

• Define GMenu models for all context menus
• Wire GAction implementations for each menu item
• Replace GtkMenu construction with GtkPopoverMenu
• Deliverable: all context menus functional

Phase 5 — Integration Testing and Hardening (3–4 weeks)

• Full functional testing across all views (darkroom, lighttable, map, print, slideshow)
• CSS theme audit: fix any broken selectors or properties
• Tablet/stylus testing
• macOS-specific testing (GTK4 on macOS has historically lagged behind Linux)
• Performance profiling: GTK4's rendering pipeline differs and some drawing paths may need optimisation
• Deliverable: release-quality GTK4 build

Total Timeline: 14–18 weeks

---

6. Effort Estimate with AI Assistance

The estimate below assumes working with an AI coding assistant (such as myself) on a dedicated branch, with the human developer providing feedback, running builds, and doing visual/functional testing.

Phase	Duration	Primary Actor
Phase 0 — Environment setup	1 week	AI (build scripts) + Human (testing)
Phase 1 — Mechanical fixes	2–3 weeks	AI (can automate ~90%)
Phase 2 — Custom widget bases	2–3 weeks	AI (~70%) + Human review
Phase 3 — Event system	4–5 weeks	AI + Human (design decisions, testing)
Phase 4 — Menu system	2 weeks	AI (~60%) + Human review
Phase 5 — Integration testing	3–4 weeks	Human primary, AI support
Total	14–18 weeks

Without AI assistance, double the estimate (28–36 weeks for an experienced GTK developer).

---

7. What I Can Do Autonomously vs. What Requires You

I Can Do Fully (or Near-Fully) Autonomously

• Build system migration: Update CMakeLists.txt, find/replace GTK3 package with GTK4, update compiler flags. This is deterministic.
• Mechanical API replacements: gtk_box_pack_start → gtk_box_append, gtk_container_add → appropriate append, gtk_widget_destroy variants, gdk_window_get_* → gdk_surface_get_*. I can write scripts to do these globally and verify each file.
• Draw callback migration: Changing g_signal_connect(w, "draw", ...) to gtk_drawing_area_set_draw_func(...) is pattern-matching work I can do file by file.
• dtgtk widget base class changes: Given clear GTK4 documentation, I can rebase GtkEventBox subclasses onto GtkBox or GtkWidget and add the appropriate controllers.
• CSS theme audit and fixes: GTK4 CSS changes are documented and finite; I can go through each theme file systematically.
• GtkMenu → GtkPopoverMenu: For straightforward context menus with fixed items, I can write the GMenu model and GAction wiring.
• Application lifecycle (gtk_main → GtkApplication): This is a well-documented, one-time structural change I can do in src/gui/gtk.c.
• gtk_widget_show_all elimination: Replace with explicit per-widget visibility, with appropriate default-visible logic.

What Requires Your Involvement

• Visual regression testing: I cannot see the rendered UI. After each phase, you need to run the application and verify that panels, buttons, sliders, icons, and menus look and behave correctly. GTK4 changes subtleties in layout, spacing, and theming that only visual inspection reveals.

• Tablet and stylus pressure handling: darktable has specific support for Wacom and other pressure-sensitive input. GTK4's input device model changed. I can write the code using GtkEventControllerLegacy or GdkDeviceTool, but I cannot verify it works without a physical device and a Linux/Windows test environment.

• bauhaus design decisions: The bauhaus popup system (the floating window that appears when you click a slider) interacts with the window manager in non-trivial ways. GTK4's surface and subsurface model changed how transient windows work. There will be edge cases (popup positioning, grab behaviour, keyboard focus) that require interactive testing and design decisions about acceptable tradeoffs.

• Darkroom canvas interactions: The main editing canvas implements pixel-precise interactions (mask drawing, crop handles, color picking). These are the most complex event handling scenarios in the codebase. I can port the code, but only you can verify that the interactions feel right.

• macOS-specific issues: GTK4 on macOS (via the Quartz backend or via XWayland) has historically been less stable than on Linux. You will need to test on your target macOS versions, and some issues may require platform-specific workarounds that are hard to anticipate without a running build.

• Performance regression identification: GTK4 renders differently (it uses GSK, a scene graph, which can be better or worse than GTK3's direct Cairo rendering depending on the use case). If the UI becomes sluggish — especially the thumbnail view and the darkroom canvas — profiling and optimisation require running the application.

• Final acceptance testing: Regression testing across all modules, all views, all export paths, all shortcuts. I can write a test plan, but execution requires you.

---

8. Necessary Compromises

A pragmatic GTK4 migration for darktable will need to accept some deliberate deferments and imperfections. These are not failures — they are engineering choices that keep the project moving.

8.1 Keep GtkTreeView (for now)

GTK4 deprecated GtkTreeView but did not remove it. The replacement (GtkListView + GtkColumnView with factory-based item rendering) is a complete conceptual overhaul. Replacing GtkTreeView across the 32 files that use it (tagging, filtering, collection browser, metadata, export, styles, masks) would add 4–6 weeks to the migration and risks introducing regressions in complex list interactions. The pragmatic choice is to leave GtkTreeView in place for the initial GTK4 release and plan a separate follow-up.

8.2 GtkDialog and GtkFileChooser Remain as-is

These are deprecated in GTK4 (the replacements are GtkAlertDialog and GtkFileDialog, which use async patterns). They still work. Replace them in a subsequent release.

8.3 CSS Visual Regression Acceptance

Some of the 31 CSS files use GTK3-specific selectors or properties that may not map perfectly to GTK4. The safe approach is to accept minor visual differences (spacing, border radii, colour accuracy) in the first GTK4 release and refine the themes iteratively based on user feedback. A full CSS visual-parity effort is a separate task from the migration itself.

8.4 bauhaus May Need a Simplified Intermediate State

The bauhaus popup positioning and grab logic was written to exploit GTK3 internal behaviour. A pragmatic first port may need to simplify the popup (e.g., use a GtkPopover instead of a raw GtkWindow) even if the UX is slightly different, in order to ship a working release. Full fidelity can be restored incrementally.

8.5 No New GTK4 Features in v1

GTK4 offers genuinely better primitives: GtkListView for large lists, native drag-and-drop with content providers, accessibility improvements, Vulkan rendering. None of these should be pursued during the migration itself — the goal of the migration pass is functional parity, not improvement. Improvements come after the codebase is stable on GTK4.

---

9. Appendix: Key Files by Category

Foundation (start here)

• src/CMakeLists.txt — GTK version requirement
• cmake/modules/FindGTK3.cmake — needs GTK4 equivalent
• src/gui/gtk.c — main window setup, gtk_main(), 4,787 lines
• src/gui/gtk.h — central GTK utility header, many macros

bauhaus System (highest risk)

• src/bauhaus/bauhaus.c — 4,098 lines, custom widget rendering + event handling
• src/bauhaus/bauhaus.h — struct definitions, signal declarations

Custom Widget Library

• src/dtgtk/paint.c — 80+ icon paint functions (Cairo, largely compatible)
• src/dtgtk/range.c — complex range selector, uses GtkEventBox
• src/dtgtk/icon.c — uses GtkEventBox, needs rebasing
• src/dtgtk/thumbnail.c — 254+ gtk_widget calls, heavy drawing
• src/dtgtk/thumbtable.c — grid layout management
• src/dtgtk/button.c — simplest custom widget, good reference
• src/dtgtk/gradientslider.c — gradient rendering

Views (complex event handling)

• src/views/darkroom.c — main editing canvas, tablet input
• src/views/lighttable.c — thumbnail grid view
• src/views/map.c — map view with custom events

Libraries with Heavy Menu/Tree Usage

• src/libs/tagging.c — 40 signal connections, GtkTreeView
• src/libs/masks.c — 25 signal connections, context menus
• src/libs/collect.c — 23 signal connections, collection browser
• src/libs/filtering.c — 16 signal connections
• src/libs/modulegroups.c — 119 box packing calls

IOP Modules (uniform pattern, bauhaus-dependent)

• src/iop/colorharmonizer.c — representative IOP module
• All 105 files in src/iop/ — will be fixed when bauhaus is fixed

Themes

• data/themes/darktable.css — master theme
• data/themes/ — all theme and icon variants (31 CSS files total)

---

This assessment was produced by static analysis of the darktable source tree. All line and file counts are approximate. The effort estimates assume a single developer working with an AI assistant; parallel team effort would reduce calendar time proportionally.

[TurboGit]

@dterrahe @zisoft @Christian-Kr : Maybe something to take from this?

[zisoft]

I have already spend quite some effort in Phase 4 — Menu System Replacement

• Collection popover menu (see [GTK4]: migrate popover menus #19657)
• Preset menu (almost ready to review, haven't created a PR so far).

This is not a trivial rename: the programming model is different enough that context menus and popup menus need to be redesigned, not just ported.

This is true and requires a decision on how we should proceed here.

[andriiryzhkov]

I'm a relatively new contributor to darktable, but UI is another topic (besides AI) that interests me a lot. I've been looking into the migration topic lately and discovered that many things that bother me in the UI could be addressed by the GTK4 migration - so I'm motivated to help here.

Looking at the GTK3→4 migration guide, there's a whole section on preparation steps that can be done while still on GTK3 before the actual switch. The assessment above is great but doesn't cover this angle. Here's a TODO list based on codebase analysis (assisted by Claude Code) and the migration guide.

GTK4 Preparation Steps - What Can Be Done Now on GTK3

The migration guide recommends completing as many preparation steps as possible while still on GTK3, to minimize the actual switchover effort. darktable already compiles with -DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED (good!), but many things that are not deprecated in GTK3 are removed in GTK4. Here's a concrete TODO list based on codebase analysis, focused on changes that compile and work on GTK 3.24 today.

---

1. Event signals → Event controllers (~36 signal connections + ~84 add_events calls)

Priority: High | Difficulty: Medium

This is the most fundamental paradigm shift in GTK4. In GTK3, user input is delivered as raw event structs (GdkEventButton, GdkEventKey, etc.) via signals on the widget itself:

// GTK3 pattern - signal on the widget, handler receives GdkEvent struct:
g_signal_connect(widget, "button-press-event", G_CALLBACK(handler), data);

static gboolean handler(GtkWidget *w, GdkEventButton *event, gpointer data)
{
  if(event->button == 1) { ... }  // direct struct field access
}

In GTK4, this entire pattern is gone. Widgets no longer emit input event signals. Instead, you create separate event controller objects, attach them to widgets, and connect to the controller's signals. The controller delivers parsed values directly - no GdkEvent struct at all:

// GTK4 pattern - controller object, handler receives values directly:
GtkGesture *gesture = gtk_gesture_multi_press_new(widget);  // GTK 3.24 name
g_signal_connect(gesture, "pressed", G_CALLBACK(handler), data);

static void handler(GtkGestureMultiPress *gesture,
                    int n_press, double x, double y, gpointer data) { ... }

GTK 3.24 already provides the replacement controllers:

GTK3 Signal	GTK 3.24 Replacement
button-press-event, button-release-event	GtkGestureMultiPress (renamed to GtkGestureClick in GTK4)
motion-notify-event	GtkEventControllerMotion
key-press-event, key-release-event	GtkEventControllerKey
scroll-event	GtkEventControllerScroll

Not available until GTK4: GtkEventControllerFocus (replaces focus-in/out-event), GtkGestureClick name (use GtkGestureMultiPress for now).

Key files: src/bauhaus/bauhaus.c (5 signals), src/libs/modulegroups.c (6), src/develop/imageop.c (4), src/gui/gtk.c (3), src/views/darkroom.c (2).

When event controllers are in place, the gtk_widget_set_events() / gtk_widget_add_events() calls (84 occurrences, 41 files) become unnecessary and can be removed - event controllers auto-subscribe to the events they need.

---

2. GdkEvent struct access → accessor functions (remaining cases)

Priority: High | Difficulty: Low (mechanical)

Step 1 (event controllers) eliminates GdkEvent struct access for most handlers - the controller delivers values directly as function parameters. However, some code accesses events outside of signal handlers (e.g., gtk_get_current_event() in bauhaus, shared helper functions that take GdkEvent *). For these remaining cases, GTK4 makes GdkEvent fully opaque, so direct field access must use accessor functions that already exist in GTK 3.x:

• event->button → gdk_event_get_button(event, &button)
• event->state → gdk_event_get_state(event, &state)
• event->keyval → gdk_event_get_keyval(event, &keyval)
• event->direction / event->delta_x/y → gdk_event_get_scroll_direction() / gdk_event_get_scroll_deltas()
• event->time → gdk_event_get_time(event)
• event->window → gdk_event_get_window(event)

Note: event->x/event->y → gdk_event_get_coords() is already done (branch gtk4_event_coords_accessors).

Deferred (no GTK3 accessor): event->detail, event->mode (GdkEventCrossing), event->key.is_modifier, event->key.group - these need GtkEventControllerMotion in GTK4.

Current total of direct struct access: ~365 occurrences across 54 files. Most will be eliminated by step 1 (event controllers); the remainder need accessor functions.

---

3. GtkMenu → GtkPopoverMenu + GMenu (~195 occurrences, 23 files)

Priority: High | Difficulty: Medium-High

GtkMenu, GtkMenuItem, and related types are completely removed in GTK4. GtkPopoverMenu + GMenu + GAction are available since GTK 3.16 and can be adopted now.

This is not a rename - it's an architectural change from imperative widget trees to declarative menu models. Each context menu needs: a GMenu model, GAction objects in the widget's action group, and a GtkPopoverMenu to render them.

Top files: src/libs/tagging.c (20), src/libs/modulegroups.c (18), src/libs/masks.c (18), src/libs/collect.c (18), src/gui/presets.c (17), src/gui/gtk.c (16), src/libs/lib.c (13).

Note: @zisoft has already started this work - collection popover menu (#19657) and preset menu.

---

4. GtkBox packing: prepare child properties (~492 occurrences, 45 files)

Priority: Medium | Difficulty: Medium (needs visual testing)

GTK4 replaces gtk_box_pack_start(box, child, expand, fill, padding) with gtk_box_append(box, child) - the expand/fill/padding parameters are gone. The replacement is to set these as widget properties on the child.

Preparation step on GTK3: Wherever gtk_box_pack_start/end uses non-default values for expand/fill/padding, add explicit widget property calls before the pack:

// Before (GTK3):
gtk_box_pack_start(GTK_BOX(box), child, TRUE, TRUE, 4);

// Prepared (still GTK3, but ready for GTK4):
gtk_widget_set_hexpand(child, TRUE);
gtk_widget_set_halign(child, GTK_ALIGN_FILL);
gtk_widget_set_margin_start(child, 4);
gtk_widget_set_margin_end(child, 4);
gtk_box_pack_start(GTK_BOX(box), child, FALSE, FALSE, 0);
// Later for GTK4, the pack_start line just becomes: gtk_box_append(GTK_BOX(box), child);

Caveat: Unlike GTK3's expand parameter (which only affects the box), gtk_widget_set_hexpand() propagates up the widget hierarchy. Setting hexpand on a child may cause parent containers to expand too. You may need to explicitly set gtk_widget_set_hexpand(parent, FALSE) to prevent unwanted layout changes. Each conversion needs visual testing.

Calls with (FALSE, FALSE, 0) (no expand, no fill, no padding) need no property changes - they map directly to gtk_box_append.

Top files: src/libs/modulegroups.c (105), src/libs/print_settings.c (47), src/gui/gtk.c (40), src/libs/filtering.c (35), src/libs/import.c (29).

---

5. gtk_widget_show / gtk_widget_show_all - inventory only (~302 combined, 62+ files)

Priority: Medium | Difficulty: N/A on GTK3

In GTK4, widgets are visible by default. gtk_widget_show_all() is removed, gtk_widget_show() remains but is rarely needed.

Cannot be done on GTK3. In GTK3, widgets are hidden by default - removing show/show_all calls would make widgets invisible. This step is only actionable at the GTK4 switch. However, it's worth inventorying the patterns now to plan the transition:

• Panel/window init show_all (~10 sites) - become no-ops on GTK4, just delete
• show_all + set_no_show_all pairs (several IOP modules) - need redesign, the no_show_all concept is gone in GTK4
• show_all on GtkMenu before popup (many) - goes away with menu migration (step 3)
• show_all on GtkDialog before gtk_dialog_run (many) - gtk_dialog_run is also removed in GTK4, needs async rewrite
• Dynamic visibility toggles (show_all/hide pairs in IOP modules) - replace with gtk_widget_set_visible()

---

6. Remove gtk_widget_set_app_paintable (11 occurrences, 9 files)

Priority: Medium | Difficulty: Low

Removed in GTK4 with no replacement needed (custom drawing is the default). For GtkDrawingArea widgets this is already a no-op in GTK3 and can be safely deleted now. For other widget types (GtkWindow, custom button subclasses, etc.) it suppresses the default theme background - removing it on GTK3 could cause visual artifacts, so those need the background handled via CSS (background: transparent) or the widget type changed to GtkDrawingArea first.

Safe to delete now (GtkDrawingArea): src/gui/gtk.c:1811, src/gui/gtk.c:1939, src/views/darkroom.c:4485, src/gui/styles_dialog.c:1043.

Needs care (non-drawing-area): src/bauhaus/bauhaus.c:547 (GtkWindow popup), src/gui/gtk.c:1583 (center widget), src/dtgtk/culling.c:1008, src/dtgtk/thumbtable.c:2504, src/dtgtk/thumbnail_btn.c:128, src/libs/navigation.c:216, src/libs/tools/ratings.c:98.

---

7. Cursor API: enum-based → CSS cursor names (33 occurrences, 8 files)

Priority: Medium | Difficulty: Low

GTK4 removes gdk_cursor_new(GDK_WATCH) and the entire GdkCursorType enum. Only gdk_cursor_new_from_name() with CSS cursor names (e.g., "wait", "crosshair", "pointer") remains. The CSS name API already works in GTK 3.24.

Note: PR #20431 (branch gtk4_cursor) already implements this - migrates dt_control_change_cursor() to use const char * CSS names with a GTK3 fallback for platform backends missing some names (Win32 "wait"/"help", Win32+X11 "none").

Files: src/iop/toneequal.c (13), src/libs/tools/global_toolbox.c (6), src/gui/gtk.c (4), src/iop/channelmixerrgb.c (3), src/control/control.c (2), src/views/darkroom.c (2), src/libs/backgroundjobs.c (2).

---

8. GdkScreen → GdkDisplay / GdkMonitor (14 occurrences, 4 files)

Priority: Medium | Difficulty: Low-Medium (partially doable on GTK3)

GdkScreen is removed in GTK4. Some replacements are available in GTK 3.22+, others are GTK4-only.

Can do now on GTK3:

• gtk_widget_get_screen() → gtk_widget_get_display() (available since GTK 2.2)
• gdk_screen_get_monitor_at_window() → gdk_display_get_monitor_at_window() (available since GTK 3.22, note: becomes ..._at_surface() in GTK4)

Cannot do on GTK3 (GTK4-only replacement):

• gtk_style_context_add_provider_for_screen() → ..._for_display() (GTK4 only)
• gdk_screen_get_rgba_visual() + gtk_widget_set_visual() - still needed on GTK3 for transparent windows (not needed in GTK4, RGBA is always used)
• gdk_screen_get_resolution() / set_resolution() - no direct GTK3 replacement (GTK4 uses monitor scale)

Files: src/common/colorspaces.c (6 - ICC profile lookup, includes X11-specific gdk_screen_get_root_window), src/bauhaus/bauhaus.c (3 - popup RGBA visual), src/gui/gtk.c (4 - CSS provider + DPI), src/views/darkroom.c (1).

---

9. gtk_widget_get_toplevel → gtk_widget_get_ancestor (17 occurrences, 8 files)

Priority: Low | Difficulty: Low (not trivial - needs NULL checks)

gtk_widget_get_toplevel() is removed in GTK4 (replaced by gtk_widget_get_root()). As a GTK3-compatible preparation, replace with gtk_widget_get_ancestor(widget, GTK_TYPE_WINDOW).

Important difference: get_toplevel never returns NULL (returns the widget itself if not in a window), but get_ancestor returns NULL if no ancestor of the given type exists. About ~8 call sites cast the result directly to GTK_WINDOW() with no NULL check - these would crash. Each call site needs a NULL guard or fallback (e.g., src/libs/import.c already has the right pattern: checks GTK_IS_WINDOW(topwindow) and falls back to dt_ui_main_window()).

Files: src/gui/accelerators.c (8 - several without NULL checks), src/gui/preferences.c (2 - direct GTK_WINDOW() cast), src/develop/imageop.c (2 - has NULL guard), src/bauhaus/bauhaus.c (1), src/dtgtk/range.c (1 - no NULL check), others.

---

10. GtkEventBox elimination (58 occurrences, 26 files)

Priority: Medium | Difficulty: Medium

GtkEventBox is removed in GTK4 since all widgets now receive events. Three custom widgets subclass it and need rebasing:

• GtkDarktableResetLabel (src/dtgtk/resetlabel.h)
• GtkDarktableIcon (src/dtgtk/icon.h)
• GtkDarktableRangeSelect (src/dtgtk/range.h)
• GtkDarktableThumbnail has GtkEventBox members (w_back, w_bottom_eb, w_zoom_eb)

Preparation: Reparent subclasses onto GtkBox (which receives events in GTK3 when gtk_widget_add_events is used) or wrap the event handling to be easily swapped later. Other files using gtk_event_box_new() as a simple event-receiving container (e.g., src/libs/modulegroups.c 13 uses, src/gui/preferences.c 9 uses) should be restructured.

---

11. gtk_main() → GtkApplication (10 occurrences, 4 files)

Priority: Medium | Difficulty: Medium-High

gtk_main() / gtk_main_quit() are removed in GTK4. GtkApplication has been available since GTK 3.0.

darktable currently uses gtk_init() + gtk_main() in src/gui/gtk.c and src/chart/main.c. The migration to GtkApplication is an architectural change (startup, activation, signal handling all change), but it can be done incrementally on GTK3.

Also replace: gtk_events_pending() → g_main_context_pending(), gtk_main_iteration() → g_main_context_iteration().

---

12. gtk_widget_destroy → minimize usage (103 occurrences, 40 files)

Priority: Low | Difficulty: Low

In GTK4, gtk_widget_destroy() only works on toplevel windows (gtk_window_destroy()). For other widgets, use gtk_container_remove() or g_object_unref().

Preparation: Audit calls and replace non-toplevel gtk_widget_destroy() with gtk_container_remove(parent, child) where appropriate. This works on GTK3.

---

13. Run with G_ENABLE_DIAGNOSTIC=1

Priority: Low | Difficulty: Trivial

Run darktable with G_ENABLE_DIAGNOSTIC=1 to catch runtime deprecation warnings for properties and signals that can't be caught at compile time, despite the existing -DGTK_DISABLE_DEPRECATED flag.

---

Suggested PR Order

For incremental PRs that are safe to merge to master while still on GTK3:

1. Remove gtk_widget_set_app_paintable (safe subset on GtkDrawingArea first, then the rest with CSS fixes)
2. Cursor API → CSS names (PR Use CSS cursor names for native platform cursors (GTK4 prep) #20431 already open)
3. GdkScreen → GdkDisplay/GdkMonitor (partial - only the calls with GTK3 replacements)
4. gtk_widget_get_toplevel → gtk_widget_get_ancestor (17 changes, add NULL guards)
5. GtkMenu → GtkPopoverMenu (ongoing, @zisoft already contributing)
6. Event controllers (start with simpler widgets, then bauhaus/darkroom - this subsumes most GdkEvent struct access)
7. GdkEvent accessor functions (for remaining non-signal event access only)
8. GtkBox packing properties (normalize expand/fill/padding to widget properties - needs visual testing per conversion)
9. GtkEventBox elimination (reparent subclasses)
10. gtk_main → GtkApplication (larger architectural change)

Each of these can be a separate PR, builds and works on GTK3, and reduces the GTK4 switchover delta.

I've already started looking at the event handling side - branch gtk4_event_coords_accessors in my clone replaces direct event->x/y access with gdk_event_get_coords() (item 2). But after this analysis I see it would be better to tackle item 1 (event controllers) first, since that eliminates most GdkEvent struct access altogether rather than just wrapping it in accessors.

[SilvioGrosso]

Hello everyone!

Just out of curiosity..
What will occur if you never move to GTK4?

Please, do not get me wrong: I am 100% positive that GTK4 transition would be a huge achievement for darktable!
However, it is also a gigantic amount of work with plenty of bug-fixing later on. Especially since darkable should work on all major platforms (Linux - Apple - Windows)
As of today, from what I have gathered, darktable also works fine on Wayland. It is also pretty much stable on Windows and Apple systems.

In the very long past Ardour developers decided not to switch to GTK3 and to remain to GTK2 for exactly this reason (too much work to do...): https://discourse.ardour.org/t/gtk3-migration/101873

Inkscape developers funded a developer to work full-time on the GTK4 port but even after many months of coding there are still plenty of bugs to fix e.g. on Windows - Apple systems since GTK4 is not much tested and fine-tuned on these platforms.

[masterpiga]

I would like to piggyback @SilvioGrosso's comment for a couple of related considerations:

1. IIUC, there are at least two years before GTK5 is released, which would mark the end of support for GTK3. Even after that, GTK3 will be a very mature toolkit, predictably with many years of life ahead.

2. The new generation of LLMs (Gemini3.1 Pro, Claude Opus) are extremely capable. Previous generations had very limited ability to deal with large codebases, but the landscape is changing quickly. These models are already excellent, and there is a lot effort going into making them even better.

3. Already now in Antigravity (and possibly similar tools that I haven't tried) the agentic models can start the applications that they build and play with the interface interactively to iterate with real-time feedback on the applications that they are building, to find regressions and fix bugs. It seems pretty realistic to me that in 6 months / 1 year, one of these models will be able to pull out this migration almost if not completely by itself.

4. If it's not one year, maybe it's going to be 2, or 5, but anyways before urgently migrating away from GTK3 becomes a matter of life or death for darktable.

So, where I am going with this is the following:

Instead of investing a lot of engineering effort now, wouldn't it make sense to pause the migration effort, and wait until GTK3 end of life approaches, to carry out the migration using the best tools that will be available at that time?

(And, by the way, by the time that GTK5 is available, or maybe GTK5.1, one could migrate directly to that)

[TurboGit]

Instead of investing a lot of engineering effort now, wouldn't it make sense to pause the migration effort, and wait until GTK3 end of life approaches, to carry out the migration using the best tools that will be available at that time?

I'm not fond of waiting too much. We can certainly start migration that is compatible with Gtk3 anyway.

(And, by the way, by the time that GTK5 is available, or maybe GTK5.1, one could migrate directly to that)

And have even a harder work to do, no I don't think that's a sane option.

[wpferguson]

I wonder what AI is using to estimate the time? What level of resources (man hours) are required to meet those estimates. I think a much more realistic (but probably still optimistic) estimate is to replace week with month.

If we decide to use AI then I think the PRs need to be small so that they can reasonably be reviewed by humans. In my (small) experience with AI generated code (Lua script PRs) the code will work but also crash darktable, writes functions instead of using libraries and doesn't mesh well with the system. Working code does not equal good code. Maybe after we've reviewed 1000 or so AI generated changes and it got everyone correct then we can start to relax our vigilance.

I think the object of porting should be duplicating the existing functionality and not slipping in "features" and "changes" to make darktable "better". Making darktable "better" should be separate PRs that can receive the attention they deserve. Also, there is way more than enough work to just accomplish the port without adding extras.

This may be a time where we want to use the sub issue feature of github to break changes down to small PRs.

Some code in darktable is "difficult" to understand and is going to be a real challenge to convert.

What do we do with normal PRs while this is going on? Maybe "hold" a PR that affects, or is affected by, a section being worked on until that section is complete and the PR can be adjusted to/for the changes?

The biggest issue will be testing. If we break things down to small PRs, then individual testing of PRs is probably not going to work because there will be dependencies between PRs. Again, using the sub issue feature of github could let us organize the work into testable units, then further break that down to small "digestible" PRs. That way when we finish a testable unit, we can do extensive testing to make sure all the individual PRs we couldn't test because of dependencies, work and that the unit as a whole works correctly. We can test against the last released version of darktable as the baseline.

I wonder how much we can use AI to determine "testable units". It would probably do a better job of determining the interconnections between functions and modules than humans (I hope).

If we use AI, what are the associated costs?

Doing the work to prepare to do the port, is a significant amount of work all on it's own.

[masterpiga]

@wpferguson My intuition is that the LLM's estimate is grossly exaggerated. The reason for that being that it does not have a lot of data on which to ground its reasoning. I would argue that those estimates match more or less the amount of work that it would take a FULL TIME human develper to carry out those tasks, maybe with the help of a much lesser coding assistant than what is available today.

My educated guess is that with the latest Claude / Gemini one dedicated developer could pull this out in 2-4 weeks.

If I were the one doing this, I would create a branch in which there are only the "mandatory" modules and just a minimal set of modules to cover the funkiest widgets that there are (the agent can help identifying a minimal subset of modules). Or, create one "dummy" module that includes all the funkiest widgets, and only include that one.

I would migrate this subset and make sure that all the interaction works as expected. I would be surprised if this would take more than two weeks. 1-2 days for the bulk of the mechanical migration. A few days to fix whatever breaks. Debugging this stuff can be very tricky, but the coding agent makes this much easier.

When this is done, migrating all the other modules should just be a matter of brute force. Give it one or two more days if one wants to do it one by one, more slowly. Then, one more week of testing.

I think this is a realistic estimate. Using common engineering best practices, let's double this and say 8 weeks. I would be very, very surprised if this took more than 8 weeks for one dedicated engineer.

One could try to see how far one can go in one or two weeks, and then an actual timeline can be reassessed.

If we use AI, what are the associated costs?

As a matter of fact, a couple of days ago I told to @TurboGit that I would be happy to sponsor this migration work, paying for a Claude Max subscription for the devs that would be carrying out the work.

I am still on board with this proposal, and I would be happy to follow through. However, this makes sense is there is someone who can spend a sizable amount of hours daily to pull this off. Otherwise it is very difficult to do this in a way that is effective and cost efficient.

If there is someone who can allocate 5-8 per day to this effort, the dev team is on board and @TurboGit agrees, than I am happy to pay for a Claude Max subscription for one month. After two/three weeks we assess the progress and if necessary we can renew the subscription for one more month. If after two weeks we understand that the LLM is not yet good enough, then we can repeat the exercise a few months down the line.

Any thoughts?

[wpferguson]

My educated guess is that with the latest Claude / Gemini one dedicated developer could pull this out in 2-4 weeks.

I think YOU might be able to do that. You use a "good" LLM every day so you have experience and a skill set that (probably) no dev has. If it was me I'd spend 2-4 weeks just figuring out how to talk to it and get anything useful.

[masterpiga]

I think YOU might be able to do that. You use a "good" LLM every day so you have experience and a skill set that (probably) no dev has. If it was me I'd spend 2-4 weeks just figuring out how to talk to it and get anything useful.

Believe me, I would be happy to do it myself. Unfortunately, I really do not have the cycles. I barely have time to write long rants on Pixls. A few years ago I would have done it at night, but nowadays I just don't have enough steam for that.

[wpferguson]

barely have time to write long rants on Pixls

🤣

Let me know when we need to declare a "truce" so that you can get some sleep and I can write code instead of rants 😄.

[masterpiga]

If there is someone who can allocate 5-8 per day to this effort, the dev team is on board and @TurboGit agrees, than I am happy to pay for a Claude Max subscription for one month. After two/three weeks we assess the progress and if necessary we can renew the subscription for one more month. If after two weeks we understand that the LLM is not yet good enough, then we can repeat the exercise a few months down the line.

An alternative to this would be to have two people in 2 different time zones (or with very different circadian rhythms) that share one account and can allocate 2-3 hours each every day. When they are done with their shift they push their changes and let the other continue. If they share the account they would also be able to share the LLM chat history, which would make it easier for the model to pick up from where the other one left.