Part VI. Migrating from Previous Versions of GTK

This part describes what you need to change in programs use older versions of GTK so that they can use the new features. It also mentions how to convert applications using widgets found in the libgnomeui library to use their counterparts in GTK.

Table of Contents

Migrating from GTK 2.x to GTK 4
Migrating from GTK 3.x to GTK 4
Preparation in GTK 3.x
Do not use deprecated symbols
Enable diagnostic warnings
Do not use GTK-specific command line arguments
Do not use widget style properties
Review your window creation flags
Stop using direct access to GdkEvent structs
Stop using gdk_pointer_warp()
Stop using non-RGBA visuals
Stop using GtkBox padding, fill and expand child properties
Stop using the state argument of GtkStyleContext getters
Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()
Stop using GtkButton’s image-related API
Stop using GtkWidget event signals
Set a proper application ID
Stop using gtk_main() and related APIs
Reduce the use of gtk_widget_destroy()
Reduce the use of generic container APIs
Review your use of icon resources
Changes that need to be done at the time of the switch
Larger changes
Stop using GdkScreen
Stop using the root window
Stop using GdkVisual
Stop using GdkDeviceManager
Adapt to GdkWindow API changes
The iconified window state has been renamed to minimized
Adapt to GdkEvent API changes
Stop using grabs
Adapt to coordinate API changes
Adapt to GdkKeymap API changes
Adapt to changes in keyboard modifier handling
Replace GtkClipboard with GdkClipboard
Stop using gtk_get_current_... APIs
Convert your ui files
Adapt to GtkBuilder API changes
Adapt to event controller API changes
Focus handling changes
Use the new apis for keyboard shortcuts
Stop using GtkEventBox
Stop using GtkButtonBox
Adapt to GtkBox API changes
Adapt to GtkWindow API changes
Adapt to GtkHeaderBar and GtkActionBar API changes
Adapt to GtkStack, GtkAssistant and GtkNotebook API changes
Adapt to button class hierarchy changes
Adapt to GtkScrolledWindow API changes
Adapt to GtkBin removal
Adapt to GtkContainer removal
Stop using GtkContainer::border-width
Adapt to gtk_widget_destroy() removal
Adapt to coordinate API changes
Adapt to GtkStyleContext API changes
Adapt to GtkCssProvider API changes
Stop using GtkShadowType and GtkRelief properties
Adapt to GtkWidget’s size request changes
Adapt to GtkWidget’s size allocation changes
Switch to GtkWidget’s children APIs
Don’t use -gtk-gradient in your CSS
Don’t use -gtk-icon-effect in your CSS
Don’t use -gtk-icon-theme in your CSS
Don’t use -gtk-outline-…-radius in your CSS
Adapt to drawing model changes
Stop using APIs to query GdkSurfaces
Widgets are now visible by default
Adapt to changes in animated hiding and showing of widgets
Stop passing commandline arguments to gtk_init
GdkPixbuf is deemphasized
GtkWidget event signals are removed
Invalidation handling has changed
Stop using GtkWidget::draw
Window content observation has changed
Monitor handling has changed
Adapt to monitor API changes
Adapt to cursor API changes
Adapt to icon size API changes
Adapt to changes in the GtkAssistant API
Adapt to changes in the API of GtkEntry, GtkSearchEntry and GtkSpinButton
Adapt to changes in GtkOverlay API
Use GtkFixed instead of GtkLayout
Adapt to search entry changes
Adapt to GtkScale changes
Stop using gtk_window_activate_default()
Stop using gtk_widget_grab_default()
Stop setting ::has-default and ::has-focus in .ui files
Stop using the GtkWidget::display-changed signal
GtkPopover::modal has been renamed to autohide
gtk_widget_get_surface has been removed
gtk_widget_is_toplevel has been removed
gtk_widget_get_toplevel has been removed
GtkEntryBuffer ::deleted-text has changed
GtkMenu, GtkMenuBar and GtkMenuItem are gone
GtkToolbar has been removed
GtkAspectFrame is no longer a frame
Stop using custom tooltip windows
Switch to the new Drag-and-Drop api
Adapt to GtkIconTheme API changes
Update to GtkFileChooser API changes
Stop using blocking dialog functions
Stop using GtkBuildable API
Adapt to GtkAboutDialog API changes
Adapt to GtkTreeView and GtkIconView tooltip context changes
Stop using GtkFileChooserButton
Adapt to changed GtkSettings properties
Changes to consider after the switch
Consider porting to the new list widgets