# Migrating from GTK+ 3.x to GTK+ 4

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, GtkBox:fill and GtkBox:expand

GTK+4 removes these #GtkBox child properties, so you should not use them. You can replace GtkBox:padding using the #GtkWidget:margin properties on your #GtkBox child widgets.

The fill child property can be replaced by setting appropriate values for the #GtkWidget:halign and #GtkWidget:valign properties of the child widgets. If you previously set the fill child property to %TRUE, you can achieve the same effect by setting the halign or valign properties to %GTK_ALIGN_FILL, depending on the parent box -- halign for a horizontal box, valign for a vertial one.

#GtkBox also uses the expand child property. It can be replaced by setting #GtkWidget:hexpand or #GtkWidget:vexpand on the child widgets. To match the old behavior of the #GtkBox's expand child property, you need to set #GtkWidget:hexpand on the child widgets of a horizontal #GtkBox and #GtkWidget:vexpand on the child widgets of a vertical #GtkBox. Note that there's a subtle but important difference between #GtkBox's expand and fill child properties and the ones in #GtkWidget: setting #GtkWidget:hexpand or #GtkWidget:vexpand to %TRUE will propagate up the widget hierarchy, so a pixel-perfect port migth require a reset of the expansion flags to %FALSE in a parent widget higher up the hierarchy.

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

### Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_window()

These functions are not supported in GTK+ 4. Instead, either use backend-specific APIs, or render your widgets using gtk_widget_render().

## 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 #GtkCssProvider::parsing-error signal instead.

### Stop using GtkContainer::border-width

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.

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

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