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.

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. FIXME: what are those ?

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.

Don't use -gtk-gradient in your CSS

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

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

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.