Changes that need to be done at the time of the switch

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.

Adapt to GdkWindow API changes

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.

Adapt to GtkStyleContext API changes

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.

Adapt to GtkCssProvider API changes

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

Stop using GtkContainer::border-width

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

Adapt to GtkWidget's size request changes

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.

Switch to GtkWidget's children APIs

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.

Don't use -gtk-gradient in your CSS

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

Don't use -gtk-icon-effect in your CSS

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

Use gtk_widget_measure

gtk_widget_measure replaces the various gtk_widget_get_preferred_ functions for querying sizes.

Adapt to drawing model changes

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 “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 “draw” signal handler.

Stop using APIs to query GdkWindows

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

Adapt to changes in animated hiding and showing of widgets

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.

Stop passing commandline arguments to gtk_init()

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.