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.

Stop using GdkScreen

The GdkScreen object has been removed in GTK+ 4. Most of its APIs already had replacements in GTK+ 3 and were deprecated, a few remaining replacements have been added to GdkDisplay.

Stop using the root window

The root window is an X11-centric concept that is no longer exposed in the backend-neutral GDK API. gdk_window_get_parent() will return NULL for toplevel windows. If you need to interact with the X11 root window, you can use gdk_x11_display_get_xrootwindow() to get its XID.

Stop using GdkVisual

This object is not useful with current GTK+ drawing APIs and has been removed without replacement.

Stop using GdkDeviceManager

The GdkDeviceManager object has been removed in GTK+ 4. Most of its APIs already had replacements in GTK+ 3 and were deprecated in favor of GdkSeat.

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.

Stop accessing GdkEvent fields

Direct access to GdkEvent structs is no longer possible in GTK+ 4. Some frequently-used fields already had accessors in GTK+ 3, and the remaining fields have gained accessors in GTK+ 4.

Stop using gdk_window_set_event_compression

Event compression is now always enabled. If you need to see the uncoalesced motion history, use gdk_event_get_motion_history().

Adapt to GdkKeymap API changes

The way to get a keymap has changed slightly. gdk_keymap_get_for_display() has been renamed to gdk_display_get_keymap().

Adapt to GtkHeaderBar API changes

The gtk_header_bar_set_show_close_button() function has been renamed to the more accurate name gtk_header_bar_set_show_title_buttons(). The corresponding getter and the property itself have also been renamed.

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 instead of connnecting a handler to the “draw” signal.

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_bin_window(), gtk_viewport_get_bin_window(), gtk_viewport_get_view_window().

Widgets are now visible by default

The default value of “visible” in GTK+ 4 is TRUE, so you no longer need to explicitly show all your widgets. On the flip side, you need to hide widgets that are not meant to be visible from the start.

A convenient way to remove unnecessary property assignments like this from ui files it run the command gtk4-builder-tool simplify --replace on them.

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.

GdkPixbuf is deemphasized

A number of GdkPixbuf-based APIs have been removed. The available replacements are either using GIcon, cairo_surface_t or the newly introduced GdkTexture class instead.

If you are dealing with pixbufs, you can use gdk_texture_new_for_pixbuf() to convert them to texture objects where needed.

GtkWidget event signals are deemphasized

Event controllers and GtkGestures have already been introduced in GTK+ 3 to handle input for many cases. In GTK+ 4, even more are available, such as GtkEventControllerScroll and GtkEventControllerMotion, and the traditional widget signals for handling input, such as “motion-event” or “event” have been deprecated.

The gtk_window_fullscreen_on_monitor API has changed

Instead of a monitor number, gtk_window_fullscreen_on_monitor() now takes a GdkMonitor argument.

Adapt to cursor API changes

Use the new gtk_widget_set_cursor() function to set cursors, instead of setting the cursor on the underlying window directly. This is necessary because most widgets don't have their own window anymore, turning any such calls into global cursor changes.

For creating standard cursors, gdk_cursor_new_for_display() has been removed, you have to use cursor names instead of GdkCursorType. For creating custom cursors, use gdk_cursor_new_from_texture(). The ability to get cursor images has been removed.

Adapt to icon size API changes

Instead of the existing extensible set of symbolic icon sizes, GTK+ now only supports normal and large icons with the GtkIconSize enumeration. The actual sizes can be defined by themes via the CSS property -gtk-icon-size.

GtkImage setters like gtk_image_set_from_icon_name() no longer take a GtkIconSize argument. You can use the separate gtk_image_set_icon_size() setter if you need to override the icon size.

The ::stock-size property of GtkCellRendererPixbuf has been renamed to “icon-size”.