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:


GtkProgressBar orientation

In GTK+ 2.x, GtkProgressBar and GtkCellRendererProgress were using the GtkProgressBarOrientation enumeration to specify their orientation and direction. In GTK+ 3, both the widget and the cell renderer implement GtkOrientable, and have an additional 'inverted' property to determine their direction. Therefore, a call to gtk_progress_bar_set_orientation() needs to be replaced by a pair of calls to gtk_orientable_set_orientation() and gtk_progress_bar_set_inverted(). The following values correspond:

Table 2. 

GTK+ 2.x GTK+ 3
GtkProgressBarOrientation GtkOrientation inverted
GTK_PROGRESS_LEFT_TO_RIGHT GTK_ORIENTATION_HORIZONTAL FALSE
GTK_PROGRESS_RIGHT_TO_LEFT GTK_ORIENTATION_HORIZONTAL TRUE
GTK_PROGRESS_TOP_TO_BOTTOM GTK_ORIENTATION_VERTICAL FALSE
GTK_PROGRESS_BOTTOM_TO_TOP GTK_ORIENTATION_VERTICAL TRUE


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.