![]() |
![]() |
![]() |
GTK+ Reference Manual | ![]() |
---|
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.24 would have been either impossible or impractical.
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:
Table 1.
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 65. 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);
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 66. 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 "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.
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 67. 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); } |
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 |
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 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.
The resize grip functionality has been moved from GtkStatusbar
to GtkWindow. Any window can now have resize grips, regardless whether
it has a statusbar or not. The functions
gtk_statusbar_set_has_resize_grip()
and gtk_statusbar_get_has_resize_grip()
have disappeared, and instead there are now
gtk_window_set_has_resize_grip()
and gtk_window_get_has_resize_grip()
.
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.
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
(and its subdirectories), for GTK+ 3 the location is
libdir
/gtk-2.0
(and its subdirectories).
libdir
/gtk-3.0
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
.
For GTK+ 3, they have been moved to
sysconfdir
/gtk-2.0
.
The commands that create these cache files have been renamed with a -3
suffix to make them parallel-installable.
libdir
/gtk-3.0/3.0.0/
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.