GTK 4 is a major new version of GTK that breaks both API and ABI compared to GTK 3.x. Thankfully, most of the changes are not hard to adapt to and there are a number of steps that you can take to prepare your GTK 3.x application for the switch to GTK 4. After that, there's a number of adjustments that you may have to do when you actually switch your application to build against GTK 4.
The steps outlined in the following sections assume that your application is working with GTK 3.24, which is the final stable release of GTK 3.x. It includes all the necessary APIs and tools to help you port your application to GTK 4. If you are using an older version of GTK 3.x, you should first get your application to build and work with the latest minor release in the 3.24 series.
Over the years, a number of functions, and in some cases, entire widgets have been deprecated. These deprecations are clearly spelled out in the API reference, with hints about the recommended replacements. The API reference for GTK 3 also includes an index of all deprecated symbols.
To verify that your program does not use any deprecated symbols, you can use defines to remove deprecated symbols from the header files, as follows:
make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
Note that some parts of our API, such as enumeration values, are not well covered by the deprecation warnings. In most cases, using them will require you to also use deprecated functions, which will trigger warnings.
Deprecations of properties and signals cannot be caught at compile
time, as both properties and signals are installed and used after
types have been instantiated. In order to catch deprecations and
changes in the run time components, you should use the
G_ENABLE_DIAGNOSTIC environment variable when
running your application, e.g.:
Style properties do not exist in GTK 4. You should stop using them in your custom CSS and in your code.
GTK 4 removes the GDK_WA_CURSOR flag. Instead, just use
gdk_window_set_cursor() to set a cursor on the window after
GTK 4 also removes the GDK_WA_VISUAL flag, and always uses
an RGBA visual for windows. To prepare your code for this, use
after creating your window.
GTK 4 also removes the GDK_WA_WMCLASS flag. If you need this
X11-specific functionality, use
GTK 4 always uses RGBA visuals for its windows; you should make sure that your code works with that.
At the same time, you should stop using GdkVisual APIs, this object not longer exist in GTK 4. Most of its APIs are deprecated already and not useful when dealing with RGBA visuals.
The fill child property can be replaced by setting appropriate values
for the “halign” and “valign” properties of the child
widgets. If you previously set the fill child property to
TRUE, you can
achieve the same effect by setting the halign or valign properties to
GTK_ALIGN_FILL, depending on the parent box -- halign for a horizontal
box, valign for a vertical one.
GtkBox also uses the expand child property. It can be replaced by setting “hexpand” or “vexpand” on the child widgets. To match the old behavior of the GtkBox's expand child property, you need to set “hexpand” on the child widgets of a horizontal GtkBox and “vexpand” on the child widgets of a vertical GtkBox.
Note that there's a subtle but important difference between GtkBox's
expand and fill child properties and the ones in GtkWidget: setting
“hexpand” or “vexpand” to
TRUE will propagate up
the widget hierarchy, so a pixel-perfect port might require you to reset
the expansion flags to
FALSE in a parent widget higher up the hierarchy.
The getters in the GtkStyleContext API, such as
gtk_style_context_get_color() only accept the context's current
state for their state argument. You should update all callers to pass
the current state.
These functions are not supported in GTK 4. Instead, either use backend-specific
APIs, or render your widgets using
The functions and properties related to automatically add a GtkImage
to a GtkButton, and using a GtkSetting to control its visibility, are
not supported in GTK 4. Instead, you can just pack a GtkImage inside
a GtkButton, and control its visibility like you would for any other
widget. If you only want to add a named icon to a GtkButton, you can
Event controllers and GtkGestures replace event signals in GTK 4. They have been backported to GTK 3.x so you can prepare for this change.
In GTK 4 we want the application's GApplication
'application-id' (and therefore the D-Bus name), the desktop
file basename and Wayland's xdg-shell app_id to match. In
order to achieve this with GTK 3.x call
g_set_prgname() with the same
application ID you passed to GtkApplication. Rename your
desktop files to match the application ID if needed.
The call to
g_set_prgname() can be removed once you fully migrated
to GTK 4.
You should be aware that changing the application ID makes your application appear as a new, different app to application installers. You should consult the appstream documentation for best practices around renaming applications.