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+ 3. Making it possible to prepare for these in GTK+ 2.22 would have been either impossible or impractical.

Replace GdkRegion by cairo_region_t

Starting with version 1.10, cairo provides a region API that is equivalent to the GDK region API (which was itself copied from the X server). Therefore, the region API has been removed in GTK+ 3.

Porting your application to the cairo region API should be a straight find-and-replace task. Please refer to the following table:


Prevent mixed linkage

Linking against GTK+ 2.x and GTK+ 3 in the same process is problematic and can lead to hard-to-diagnose crashes. The gtk_init() function in both GTK+ 2.22 and in GTK+ 3 tries to detect this situation and abort with a diagnostic message, but this check is not 100% reliable (e.g. if the problematic linking happens only in loadable modules).

Direct linking of your application against both versions of GTK+ is easy to avoid; the problem gets harder when your application is using libraries that are themselves linked against some version of GTK+. In that case, you have to verify that you are using a version of the library that is linked against GTK+ 3.

If you are using packages provided by a distributor, it is likely that parallel installable versions of the library exist for GTK+ 2.x and GTK+ 3, e.g for vte, check for vte3; for webkitgtk look for webkitgtk3, and so on.

Install GTK+ modules in the right place

Some software packages install loadable GTK+ modules such as theme engines, gdk-pixbuf loaders or input methods. Since GTK+ 3 is parallel-installable with GTK+ 2.x, the two GTK+ versions have separate locations for their loadable modules. The location for GTK+ 2.x is libdir/gtk-2.0 (and its subdirectories), for GTK+ 3 the location is libdir/gtk-3.0 (and its subdirectories).

For some kinds of modules, namely input methods and pixbuf loaders, GTK+ keeps a cache file with extra information about the modules. For GTK+ 2.x, these cache files are located in sysconfdir/gtk-2.0. For GTK+ 3, they have been moved to libdir/gtk-3.0/3.0.0/. The commands that create these cache files have been renamed with a -3 suffix to make them parallel-installable.

Note that GTK+ modules often link against libgtk, libgdk-pixbuf, etc. If that is the case for your module, you have to be careful to link the GTK+ 2.x version of your module against the 2.x version of the libraries, and the GTK+ 3 version against hte 3.x versions. Loading a module linked against libgtk 2.x into an application using GTK+ 3 will lead to unhappiness and must be avoided.