]> 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.

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.

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.

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

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.

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

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

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().

This section outlines porting tasks that you need to tackle when you get to the point that you actually build your application against GTK+ 4. Making it possible to prepare for these in GTK+ 3 would have been either impossible or impractical.

The gdk_window_new() function has been replaced by a number of more specialized constructors: gdk_window_new_toplevel(), gdk_window_new_popup(), gdk_window_new_temp(), gdk_window_new_child(), gdk_window_new_input(), gdk_wayland_window_new_subsurface(). Use the appropriate ones to create your windows. Native and foreign subwindows are no longer supported. These concepts were complicating the code and could not be supported across backends. gdk_window_reparent() is no longer available.

The getters in the GtkStyleContext API, such as gtk_style_context_get_property(), gtk_style_context_get(), or gtk_style_context_get_color() have lost their state argument, and always use the context's current state. Update all callers to omit the state argument.

In GTK+ 4, the various #GtkCssProvider load functions have lost their #GError argument. If you want to handle CSS loading errors, use the #GtkCssProvider::parsing-error signal instead.

GTK+ 4 has removed the #GtkContainer::border-width property. Use other means to influence the spacing of your containers, such as the CSS margin and padding properties on child widgets.

GTK+ 3 used five different virtual functions in GtkWidget to implement size requisition, namely the gtk_widget_get_preferred_width() family of functions. To simplify widget implementations, GTK+4 uses only one virtual function, GtkWidgetClass::measure() that widgets have to implement.

Instead of the GtkContainer subclass, in GTK+ 4, any widget can have children, and there is new API to navigate the widget tree: gtk_widget_get_first_child(), gtk_widget_get_last_child(), gtk_widget_get_next_sibling(), gtk_widget_get_prev_sibling(). The GtkContainer API still works, but if you are implementing your own widgets, you should consider using the new APIs.

GTK+ now supports standard CSS syntax for both linear and radial gradients, just use those.

GTK+ now supports a more versatile -gtk-icon-filter instead. Replace -gtk-icon-effect: dim; with -gtk-icon-filter: opacity(0.5); and -gtk-icon-effect: hilight; with -gtk-icon-filter: brightness(1.2);.

gtk_widget_measure replaces the various gtk_widget_get_preferred_ functions for querying sizes.

This area has seen the most radical changes in the transition from GTK+ 3 to GTK+ 4. Widgets no longer use a draw() function to render their contents to a cairo surface. Instead, they have a snapshot() function that creates one or more GskRenderNodes to represent their content. Third-party widgets that use a draw() function or a #GtkWidget::draw signal handler for custom drawing will need to be converted to use gtk_snapshot_append_cairo(). The auxiliary #GtkSnapshot object has APIs to help with creating render nodes. If you are using a #GtkDrawingArea for custom drawing, you need to switch to using gtk_drawing_area_set_draw_func() to set a draw function. This is pretty much a direct replacement for a #GtkWidget::draw signal handler.

A number of APIs for querying special-purpose windows have been removed, since these windows are no longer publically available: gtk_tree_view_get_pin_window(), gtk_viewport_get_bin_window(), gtk_viewport_get_view_window().

Widgets that appear and disappear with an animation, such as GtkPopover, GtkInfoBar, GtkRevealer no longer use gtk_widget_show() and gtk_widget_hide() for this, but have gained dedicated APIs for this purpose that you should use.

The gtk_init() and gtk_init_check() functions no longer accept commandline arguments. Just call them without arguments. Other initialization functions that were purely related to commandline argument handling, such as gtk_parse_args() and gtk_get_option_group(), are gone. The APIs to initialize GDK separately are also gone, but it is very unlikely that you are affected by that.