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:


Replace GdkPixmap by cairo surfaces

The GdkPixmap object and related functions have been removed. In the cairo-centric world of GTK+ 3, cairo surfaces take over the role of pixmaps.

Example 64. Creating custom cursors

One place where pixmaps were commonly used is to create custom cursors:

GdkCursor *cursor;
GdkPixmap *pixmap;
cairo_t *cr;
GdkColor fg = { 0, 0, 0, 0 };

pixmap = gdk_pixmap_new (NULL, 1, 1, 1);

cr = gdk_cairo_create (pixmap);
cairo_rectangle (cr, 0, 0, 1, 1);
cairo_fill (cr);
cairo_destroy (cr);

cursor = gdk_cursor_new_from_pixmap (pixmap, pixmap, &fg, &fg, 0, 0);

g_object_unref (pixmap);
      

The same can be achieved without pixmaps, by drawing onto an image surface:

GdkCursor *cursor;
cairo_surface_t *s;
cairo_t *cr;
GdkPixbuf *pixbuf;

s = cairo_image_surface_create (CAIRO_FORMAT_A1, 3, 3);
cr = cairo_create (s);
cairo_arc (cr, 1.5, 1.5, 1.5, 0, 2 * M_PI);
cairo_fill (cr);
cairo_destroy (cr);

pixbuf = gdk_pixbuf_get_from_surface (NULL, s,
                                      0, 0, 0, 0,
                                      3, 3);

cairo_surface_destroy (s);

cursor = gdk_cursor_new_from_pixbuf (display, pixbuf, 0, 0);

g_object_unref (pixbuf);
      


Replace colormaps by visuals

For drawing with cairo, it is not necessary to allocate colors, and a GdkVisual provides enough information for cairo to handle colors in 'native' surfaces. Therefore, GdkColormap and related functions have been removed in GTK+ 3, and visuals are used instead. The colormap-handling functions of GtkWidget (gtk_widget_set_colormap(), etc) have been removed and gtk_window_set_visual() has been added.

Example 65. Setting up a translucent window

You might have a screen-changed handler like the following to set up a translucent window with an alpha-channel:

static void
on_alpha_screen_changed (GtkWidget *widget,
                         GdkScreen *old_screen,
                         GtkWidget *label)
{
  GdkScreen *screen = gtk_widget_get_screen (widget);
  GdkColormap *colormap = gdk_screen_get_rgba_colormap (screen);

  if (colormap == NULL)
    colormap = gdk_screen_get_default_colormap (screen);

  gtk_widget_set_colormap (widget, colormap);
}
    

With visuals instead of colormaps, this will look as follows:

static void
on_alpha_screen_changed (GtkWindow *window,
                         GdkScreen *old_screen,
                         GtkWidget *label)
{
  GdkScreen *screen = gtk_widget_get_screen (GTK_WIDGET (window));
  GdkVisual *visual = gdk_screen_get_rgba_visual (screen);

  if (visual == NULL)
    visual = gdk_screen_get_system_visual (screen);

  gtk_window_set_visual (window, visual);
}
    

The GtkWidget::draw signal

The GtkWidget "expose-event" signal has been replaced by a new "draw" signal, which takes a cairo_t instead of an expose event. The cairo context is being set up so that the origin at (0, 0) coincides with the upper left corner of the widget, and is properly clipped.

Note

In other words, the cairo context of the draw signal is set up in 'widget coordinates', which is different from traditional expose event handlers, which always assume 'window coordinates'.

The widget is expected to draw itself with its allocated size, which is available via the new gtk_widget_get_allocated_width() and gtk_widget_get_allocated_height() functions. It is not necessary to check for GTK_WIDGET_IS_DRAWABLE(), since GTK+ already does this check before emitting the ::draw signal.

There are some special considerations for widgets with multiple windows. Expose events are window-specific, and widgets with multiple windows could expect to get an expose event for each window that needs to be redrawn. Therefore, multi-window expose event handlers typically look like this:

1
2
3
4
5
6
7
8
9
if (event->window == widget->window1)
  {
     /* ... draw window1 ... */
  }
else if (event->window == widget->window2)
  {
     /* ... draw window2 ... */
  }
...

In contrast, the ::draw signal handler may have to draw multiple windows in one call. GTK+ has a convenience function gtk_cairo_should_draw_window() that can be used to find out if a window needs to be drawn. With that, the example above would look like this (note that the 'else' is gone):

1
2
3
4
5
6
7
8
9
if (gtk_cairo_should_draw_window (cr, widget->window1)
  {
     /* ... draw window1 ... */
  }
if (gtk_cairo_should_draw_window (cr, widget->window2)
  {
     /* ... draw window2 ... */
  }
...

Another convenience function that can help when implementing ::draw for multi-window widgets is gtk_cairo_transform_to_window(), which transforms a cairo context from widget-relative coordinates to window-relative coordinates.

All GtkStyle drawing functions (gtk_paint_box(), etc) have been changed to take a cairo_t instead of a window and a clip area. ::draw implementations will usually just use the cairo context that has been passed in for this.

Example 66. A simple ::draw function

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
gboolean
gtk_arrow_draw (GtkWidget *widget,
                cairo_t   *cr)
{
  gint x, y;
  gint width, height;
  gint extent;

  width = gtk_widget_get_allocated_width (widget);
  height = gtk_widget_get_allocated_height (widget);

  extent = MIN (width - 2 * PAD, height - 2 * PAD);
  x = PAD;
  y = PAD;

  gtk_paint_arrow (gtk_widget_get_style (widget),
                   cr,
                   gtk_widget_get_state (widget),
                   GTK_SHADOW_OUT,
                   widget,
                   "arrow",
                   widget->priv->arrow_type,
                   TRUE,
                   x, y, extent, extent);
}

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


GtkScrolledWindow policy

The default values for the "hscrollbar-policy" and "vscrollbar-policy" properties have been changed from 'never' to 'automatic'. If your application was relying on the default value, you will have explicitly set it explicitly.

GtkObject is gone

GtkObject has been removed in GTK+ 3. Its remaining functionality, the ::destroy signal, has been moved to GtkWidget. If you have non-widget classes that are directly derived from GtkObject, you have to make them derive from GInitiallyUnowned (or, if you don't need the floating functionality, GObject). If you have widgets that override the destroy class handler, you have to adust your class_init function, since destroy is now a member of GtkWidgetClass:

1
2
3
GtkObjectClass *object_class = GTK_OBJECT_CLASS (class);

object_class->destroy = my_destroy;

becomes

1
2
3
GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);

widget_class->destroy = my_destroy;

In the unlikely case that you have a non-widget class that is derived from GtkObject and makes use of the destroy functionality, you have to implement ::destroy yourself.

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.