Migrating from GTK+ 3.x to GTK+ 4

Preparation in GTK+ 3.x
Do not use deprecated symbols
Do not use widget style properties
Review your window creation flags
Stop using non-RGBA visuals
Stop using GtkBox::padding
Stop using the state argument of GtkStyleContext getters
Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_window()
Changes that need to be done at the time of the switch
Adapt to GdkWindow API changes
Adapt to GtkStyleContext API changes
Adapt to GtkCssProvider API changes
Stop using GtkContainer::border-width
Adapt to GtkWidget's size request changes
Don't use -gtk-gradient in your CSS
Use gtk_widget_measure
Adapt to drawing model changes

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 small number of adjustments that you may have to do when you actually switch your application to build against GTK+ 4.

Preparation in GTK+ 3.x

The steps outlined in the following sections assume that your application is working with GTK+ 3.22, 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 still using an older version of GTK+ 3.x, you should first get your application to build and work with 3.22.

Do not use deprecated symbols

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.

Do not use widget style properties

Style properties do not exist in GTK+ 4. You should stop using them in your custom CSS.

Review your window creation flags

GTK+ 4 removes the GDK_WA_CURSOR flag. Instead, just use gdk_window_set_cursor() to set a cursor on the window after creating it.

GTK+ 4 also removes the GDK_WA_VISUAL flag, and always uses an RGBA visual for windows. To prepare your code for this, use gdk_window_set_visual (gdk_screen_get_rgba_visual()) after creating your window.

GTK+ 4 also removes the GDK_WA_WMCLASS flag. If you need this X11-specific functionality, use XSetClassHint() directly.

Stop using non-RGBA visuals

GTK+ 4 always uses RGBA visuals for its windows; you should make sure that your code works with that.

Stop using GtkBox::padding

GTK+ 4 removes the “padding” child property, so you should use other ways to influence the layout of your boxes.

Stop using the state argument of GtkStyleContext getters

The getters in the GtkStyleContext API, such as gtk_style_context_get_property(), gtk_style_context_get(), or gtk_style_context_get_color() only accept the context's current state for their state argument. 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 gtk_widget_render().