forked from AuroraMiddleware/gtk
647 lines
26 KiB
XML
647 lines
26 KiB
XML
<?xml version="1.0"?>
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
||
]>
|
||
<chapter id="gtk-migrating-2-to-3">
|
||
<title>Migrating from GTK+ 2.x to GTK+ 3</title>
|
||
|
||
<para>
|
||
GTK+ 3 is a major new version of GTK+ that breaks both API and ABI
|
||
compared to GTK+ 2.x, which has remained API- and ABI-stable for a
|
||
long time. Thankfully, most of the changes are not hard to adapt to
|
||
and there are a number of steps that you can take to prepare your
|
||
GTK+ 2.x application for the switch to GTK+ 3. After that, there's
|
||
a small number of adjustments that you may have to do when you actually
|
||
switch your application to build against GTK+ 3.
|
||
</para>
|
||
|
||
<section>
|
||
<title>Preparation in GTK+ 2.x</title>
|
||
|
||
<para>
|
||
The steps outlined in the following sections assume that your
|
||
application is working with GTK+ 2.22, which is the final stable
|
||
release of GTK+ 2.x. It includes all the necessary APIs and tools
|
||
to help you port your application to GTK+ 3. If you are still using
|
||
an older version of GTK+ 2.x, you should first get your application
|
||
to build and work with 2.22.
|
||
</para>
|
||
|
||
<section>
|
||
<title>Do not include individual headers</title>
|
||
<para>
|
||
With GTK+ 2.x it was common to include just the header files for
|
||
a few widgets that your application was using, which could lead
|
||
to problems with missing definitions, etc. GTK+ 3 tightens the
|
||
rules about which header files you are allowed to include directly.
|
||
The allowed header files are are
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><filename>gtk/gtk.h</filename></term>
|
||
<listitem>for GTK</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><filename>gtk/gtkunixprint.h</filename></term>
|
||
<listitem>for low-level, UNIX-specific printing functions</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><filename>gdk/gdk.h</filename></term>
|
||
<listitem>for GDK</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><filename>gdk/gdkx.h</filename></term>
|
||
<listitem>for GDK functions that are X11-specific</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><filename>gdk/gdkwin32.h</filename></term>
|
||
<listitem>for GDK functions that are Windows-specific</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
(these relative paths are assuming that you are using the include
|
||
paths that are specified in the gtk+-2.0.pc file, as returned by
|
||
<literal>pkg-config --cflags gtk+-2.0.pc</literal>.)
|
||
</para>
|
||
<para>
|
||
To check that your application only includes the allowed headers,
|
||
you can use defines to disable inclusion of individual headers,
|
||
as follows:
|
||
<programlisting>
|
||
make CFLAGS+="-DGTK_DISABLE_SINGLE_INCLUDES"
|
||
</programlisting>
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Do not use deprecated symbols</title>
|
||
<para>
|
||
Over the years, a number of functions, and in some cases, entire
|
||
widgets have been deprecated. These deprecations are clearly spelled
|
||
out in the API reference, with hints about the recommended replacements.
|
||
The API reference also includes an
|
||
<link linkend="api-index-deprecated">index</link> of all deprecated
|
||
symbols.
|
||
</para>
|
||
<para>
|
||
To verify that your program does not use any deprecated symbols,
|
||
you can use defines to remove deprecated symbols from the header files,
|
||
as follows:
|
||
<programlisting>
|
||
make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
|
||
</programlisting>
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Use accessor functions instead of direct access</title>
|
||
<para>
|
||
GTK+ 3 removes many implementation details and struct members from
|
||
its public headers.
|
||
</para>
|
||
<para>
|
||
To ensure that your application does not have problems with this, you
|
||
define the preprocessor symbol <literal>GSEAL_ENABLE</literal>. This
|
||
will make the compiler catch all uses of direct access to struct fields
|
||
so that you can go through them one by one and replace them with a call
|
||
to an accessor function instead.
|
||
<programlisting>
|
||
make CFLAGS+="-DGSEAL_ENABLE"
|
||
</programlisting>
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Replace GDK_<keyname> with GDK_KEY_<keyname></title>
|
||
|
||
<para>
|
||
Key constants have gained a <literal>_KEY_</literal> infix.
|
||
For example, <literal>GDK_a</literal> is now
|
||
<literal>GDK_KEY_a</literal>. In GTK+ 2, the old names continue
|
||
to be available. In GTK+ 3 however, the old names will require
|
||
an explicit include of the <literal>gdkkeysyms-compat.h</literal> header.
|
||
</para>
|
||
|
||
</section>
|
||
|
||
<section>
|
||
<title>Use cairo for drawing</title>
|
||
<para>
|
||
In GTK+ 3, the GDK drawing API (which closely mimics the X
|
||
drawing API, which is itself modeled after PostScript) has been
|
||
removed. All drawing in GTK+ 3 is done via cairo.
|
||
</para>
|
||
<para>
|
||
The #GdkGC and #GdkImage objects, as well as all the functions using
|
||
them, are gone. This includes the <literal>gdk_draw</literal> family
|
||
of functions like gdk_draw_rectangle() and gdk_draw_drawable(). As
|
||
#GdkGC is roughly equivalent to #cairo_t and #GdkImage was used for
|
||
drawing images to GdkDrawables, which cairo supports automatically,
|
||
a transition is usually straightforward.
|
||
</para>
|
||
<para>
|
||
The following examples show a few common drawing idioms used by
|
||
applications that have been ported to use cairo and how the code
|
||
was replaced.
|
||
</para>
|
||
<example>
|
||
<title>Drawing a GdkPixbuf onto a GdkDrawable</title>
|
||
<para>
|
||
Drawing a pixbuf onto a drawable used to be done like this:
|
||
<programlisting><![CDATA[
|
||
gdk_draw_pixbuf (window,
|
||
gtk_widget_get_style (widget)->black_gc,
|
||
pixbuf,
|
||
0, 0
|
||
x, y,
|
||
gdk_pixbuf_get_width (pixbuf),
|
||
gdk_pixbuf_get_height (pixbuf),
|
||
GDK_RGB_DITHER_NORMAL,
|
||
0, 0);
|
||
]]></programlisting>
|
||
Doing the same thing with cairo:
|
||
<programlisting><![CDATA[
|
||
cairo_t *cr = gdk_cairo_create (window);
|
||
gdk_cairo_set_source_pixbuf (cr, pixbuf, x, y);
|
||
cairo_paint (cr);
|
||
cairo_destroy (cr);
|
||
]]></programlisting>
|
||
Note that very similar code can be used for drawing pixmaps
|
||
by using gdk_cairo_set_source_pixmap() instead of
|
||
gdk_cairo_set_source_pixbuf().
|
||
</para>
|
||
</example>
|
||
<example>
|
||
<title>Drawing a tiled GdkPixmap to a GdkDrawable</title>
|
||
<para>
|
||
Tiled pixmaps are often used for drawing backgrounds.
|
||
Old code looked something like this:
|
||
<programlisting><![CDATA[
|
||
GdkGCValues gc_values;
|
||
GdkGC *gc;
|
||
|
||
/* setup */
|
||
gc = gtk_widget_get_style (widget)->black_gc;
|
||
gdk_gc_set_tile (gc, pixmap);
|
||
gdk_gc_set_fill (gc, GDK_TILED);
|
||
gdk_gc_set_ts_origin (gc, x_origin, y_origin);
|
||
/* use */
|
||
gdk_draw_rectangle (drawable, gc, TRUE, 0, 0, width, height);
|
||
/* restore */
|
||
gdk_gc_set_tile (gc, NULL);
|
||
gdk_gc_set_fill (gc, GDK_SOLID);
|
||
gdk_gc_set_ts_origin (gc, 0, 0);
|
||
]]></programlisting>
|
||
The equivalent cairo code looks like this:
|
||
<programlisting><![CDATA[
|
||
cairo_t *cr;
|
||
|
||
cr = gdk_cairo_create (drawable);
|
||
gdk_cairo_set_source_pixmap (cr, pixmap, x_origin, y_origin);
|
||
cairo_pattern_set_extend (cairo_get_source (cr), CAIRO_EXTEND_REPEAT);
|
||
cairo_rectangle (cr, 0, 0, width, height);
|
||
cairo_fill (cr);
|
||
cairo_destroy (cr);
|
||
]]></programlisting>
|
||
Again, you can exchange pixbufs and pixmaps by using
|
||
gdk_cairo_set_source_pixbuf() instead of
|
||
gdk_cairo_set_source_pixmap().
|
||
</para>
|
||
</example>
|
||
<example>
|
||
<title>Drawing a PangoLayout to a clipped area</title>
|
||
<para>
|
||
Drawing layouts clipped is often used to avoid overdraw or to
|
||
allow drawing selections. Code would have looked like this:
|
||
<programlisting><![CDATA[
|
||
GdkGC *gc;
|
||
|
||
/* setup */
|
||
gc = gtk_widget_get_style (widget)->text_gc[state];
|
||
gdk_gc_set_clip_rectangle (gc, &area);
|
||
/* use */
|
||
gdk_draw_layout (drawable, gc, x, y, layout);
|
||
/* restore */
|
||
gdk_gc_set_clip_rectangle (gc, NULL);
|
||
]]></programlisting>
|
||
With cairo, the same effect can be achieved using:
|
||
<programlisting><![CDATA[
|
||
cairo_t *cr;
|
||
|
||
cr = gdk_cairo_create (drawable);
|
||
/* clip */
|
||
gdk_cairo_rectangle (cr, &area);
|
||
cairo_clip (cr);
|
||
/* set the correct source color */
|
||
gdk_cairo_set_source_color (cr, >k_widget_get_style (widget)->text[state]);
|
||
/* draw the text */
|
||
cairo_move_to (cr, x, y);
|
||
pango_cairo_show_layout (cr, layout);
|
||
cairo_destroy (cr);
|
||
]]></programlisting>
|
||
Clipping using cairo_clip() is of course not restricted to text
|
||
rendering and can be used everywhere where GC clips were used.
|
||
And using gdk_cairo_set_source_color() with style colors should
|
||
be used in all the places where a style’s GC was used to achieve
|
||
a particular color.
|
||
</para>
|
||
</example>
|
||
<section>
|
||
<title>What should you be aware of ?</title>
|
||
<formalpara><title>No more stippling</title>
|
||
<para>
|
||
Stippling is the usage of a bi-level mask, called a #GdkBitmap.
|
||
It was often used to achieve a checkerboard effect. You can use
|
||
cairo_mask() to achieve this effect. To get a checkerbox mask,
|
||
you can use code like this:
|
||
<programlisting><![CDATA[
|
||
static cairo_pattern_t *
|
||
gtk_color_button_get_checkered (void)
|
||
{
|
||
/* need to respect pixman's stride being a multiple of 4 */
|
||
static unsigned char data[8] = { 0xFF, 0x00, 0x00, 0x00,
|
||
0x00, 0xFF, 0x00, 0x00 };
|
||
cairo_surface_t *surface;
|
||
cairo_pattern_t *pattern;
|
||
|
||
surface = cairo_image_surface_create_for_data (data,
|
||
CAIRO_FORMAT_A8,
|
||
2, 2,
|
||
4);
|
||
pattern = cairo_pattern_create_for_surface (surface);
|
||
cairo_surface_destroy (surface);
|
||
cairo_pattern_set_extend (pattern, CAIRO_EXTEND_REPEAT);
|
||
cairo_pattern_set_filter (pattern, CAIRO_FILTER_NEAREST);
|
||
|
||
return pattern;
|
||
}
|
||
]]></programlisting>
|
||
Note that stippling looks very outdated in UIs, and is rarely
|
||
used in modern applications. All properties that made use of
|
||
stippling have been removed from GTK+ 3. Most prominently,
|
||
stippling is absent from text rendering, in particular #GtkTextTag.
|
||
</para>
|
||
</formalpara>
|
||
<formalpara><title>Using the the target drawable also as source or mask</title>
|
||
<para>
|
||
The gdk_draw_drawable() function allowed using the same drawable
|
||
as source and target. This was often used to achieve a scrolling
|
||
effect. Cairo does not allow this yet. You can however use
|
||
cairo_push_group() to get a different intermediate target that
|
||
you can copy to. So you can replace this code:
|
||
<programlisting><![CDATA[
|
||
gdk_draw_drawable (pixmap,
|
||
gc,
|
||
pixmap,
|
||
area.x + dx, area.y + dy,
|
||
area.x, area.y,
|
||
area.width, area.height);
|
||
]]></programlisting>
|
||
By using this code:
|
||
<programlisting><![CDATA[
|
||
cairo_t *cr = gdk_cairo_create (pixmap);
|
||
/* clipping restricts the intermediate surface's size, so it's a good idea
|
||
* to use it. */
|
||
gdk_cairo_rectangle (cr, &area);
|
||
cairo_clip (cr);
|
||
/* Now push a group to change the target */
|
||
cairo_push_group (cr);
|
||
gdk_cairo_set_source_pixmap (cr, pixmap, dx, dy);
|
||
cairo_paint (cr);
|
||
/* Now copy the intermediate target back */
|
||
cairo_pop_group_to_source (cr);
|
||
cairo_paint (cr);
|
||
cairo_destroy (cr);
|
||
]]></programlisting>
|
||
The cairo developers plan to add self-copies in the future to allow
|
||
exactly this effect, so you might want to keep up on cairo
|
||
development to be able to change your code.
|
||
</para>
|
||
</formalpara>
|
||
<formalpara><title>Using pango_cairo_show_layout(<!-- -->) instead of gdk_draw_layout_with_colors(<!-- -->)</title>
|
||
<para>
|
||
GDK provided a way to ignore the color attributes of text and use
|
||
a hardcoded text color with the gdk_draw_layout_with_colors()
|
||
function. This is often used to draw text shadows or selections.
|
||
Pango’s cairo support does not yet provide this functionality. If
|
||
you use Pango layouts that change colors, the easiest way to achieve
|
||
a similar effect is using pango_cairo_layout_path() and cairo_fill()
|
||
instead of gdk_draw_layout_with_colors(). Note that this results in
|
||
a slightly uglier-looking text, as subpixel anti-aliasing is not
|
||
supported.
|
||
</para>
|
||
</formalpara>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Changes that need to be done at the time of the switch</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<section>
|
||
<title>Replace GdkRegion by cairo_region_t</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
Porting your application to the cairo region API should be a straight
|
||
find-and-replace task. Please refer to the following table:
|
||
<table>
|
||
<tgroup cols="2">
|
||
<thead>
|
||
<row><entry>GDK</entry><entry>cairo</entry></row>
|
||
</thead>
|
||
<tbody>
|
||
<row><entry>#GdkRegion</entry><entry>#cairo_region_t</entry></row>
|
||
<row><entry>#GdkRectangle</entry><entry>#cairo_rectangle_int_t</entry></row>
|
||
<row><entry>gdk_rectangle_intersect()</entry><entry>this function is still there</entry></row>
|
||
<row><entry>gdk_rectangle_union()</entry><entry>this function is still there</entry></row>
|
||
<row><entry>gdk_region_new()</entry><entry>cairo_region_create()</entry></row>
|
||
<row><entry>gdk_region_copy()</entry><entry>cairo_region_copy()</entry></row>
|
||
<row><entry>gdk_region_destroy()</entry><entry>cairo_region_destroy()</entry></row>
|
||
<row><entry>gdk_region_rectangle()</entry><entry>cairo_region_create_rectangle()</entry></row>
|
||
<row><entry>gdk_region_get_clipbox()</entry><entry>cairo_region_get_extents()</entry></row>
|
||
<row><entry>gdk_region_get_rectangles()</entry><entry>cairo_region_num_rectangles() and
|
||
cairo_region_get_rectangle()</entry></row>
|
||
<row><entry>gdk_region_empty()</entry><entry>cairo_region_is_empty()</entry></row>
|
||
<row><entry>gdk_region_equal()</entry><entry>cairo_region_equal()</entry></row>
|
||
<row><entry>gdk_region_point_in()</entry><entry>cairo_region_contains_point()</entry></row>
|
||
<row><entry>gdk_region_rect_in()</entry><entry>cairo_region_contains_rectangle()</entry></row>
|
||
<row><entry>gdk_region_offset()</entry><entry>cairo_region_translate()</entry></row>
|
||
<row><entry>gdk_region_union_with_rect()</entry><entry>cairo_region_union_rectangle()</entry></row>
|
||
<row><entry>gdk_region_intersect()</entry><entry>cairo_region_intersect()</entry></row>
|
||
<row><entry>gdk_region_union()</entry><entry>cairo_region_union()</entry></row>
|
||
<row><entry>gdk_region_subtract()</entry><entry>cairo_region_subtract()</entry></row>
|
||
<row><entry>gdk_region_xor()</entry><entry>cairo_region_xor()</entry></row>
|
||
<row><entry>gdk_region_shrink()</entry><entry>no replacement</entry></row>
|
||
<row><entry>gdk_region_polygon()</entry><entry>no replacement, use cairo paths instead</entry></row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Replace GdkPixmap by cairo surfaces</title>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Replace colormaps by visuals</title>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<example><title>Setting up a translucent window</title>
|
||
<para>You might have a screen-changed handler like the following
|
||
to set up a translucent window with an alpha-channel:
|
||
</para>
|
||
<programlisting>
|
||
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);
|
||
}
|
||
</programlisting>
|
||
<para>
|
||
With visuals instead of colormaps, this will look as follows:
|
||
</para>
|
||
<programlisting>
|
||
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);
|
||
}
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
|
||
<section>
|
||
<title>The GtkWidget::draw signal</title>
|
||
<para>
|
||
The GtkWidget #GtkWidget::expose-event signal has been replaced by
|
||
a new #GtkWidget::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.
|
||
</para>
|
||
<note><para>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'.
|
||
</para></note>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
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:
|
||
<informalexample><programlisting>
|
||
if (event->window == widget->window1)
|
||
{
|
||
/* ... draw window1 ... */
|
||
}
|
||
else if (event->window == widget->window2)
|
||
{
|
||
/* ... draw window2 ... */
|
||
}
|
||
...
|
||
</programlisting></informalexample>
|
||
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):
|
||
<informalexample><programlisting>
|
||
if (gtk_cairo_should_draw_window (cr, widget->window1)
|
||
{
|
||
/* ... draw window1 ... */
|
||
}
|
||
if (gtk_cairo_should_draw_window (cr, widget->window2)
|
||
{
|
||
/* ... draw window2 ... */
|
||
}
|
||
...
|
||
</programlisting></informalexample>
|
||
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.
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<example><title>A simple ::draw function</title>
|
||
<programlisting>
|
||
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);
|
||
}
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
|
||
<section>
|
||
<title>GtkProgressBar orientation</title>
|
||
|
||
<para>
|
||
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>
|
||
<tgroup cols="3">
|
||
<colspec colname="1"/>
|
||
<colspec colname="2"/>
|
||
<colspec colname="3"/>
|
||
<thead>
|
||
<row><entry>GTK+ 2.x</entry><entry namest="2" nameend="3">GTK+ 3</entry></row>
|
||
<row><entry>GtkProgressBarOrientation</entry><entry>GtkOrientation</entry><entry>inverted</entry></row>
|
||
</thead>
|
||
<tbody>
|
||
<row><entry>GTK_PROGRESS_LEFT_TO_RIGHT</entry><entry>GTK_ORIENTATION_HORIZONTAL</entry><entry>FALSE</entry></row>
|
||
<row><entry>GTK_PROGRESS_RIGHT_TO_LEFT</entry><entry>GTK_ORIENTATION_HORIZONTAL</entry><entry>TRUE</entry></row>
|
||
<row><entry>GTK_PROGRESS_TOP_TO_BOTTOM</entry><entry>GTK_ORIENTATION_VERTICAL</entry><entry>FALSE</entry></row>
|
||
<row><entry>GTK_PROGRESS_BOTTOM_TO_TOP</entry><entry>GTK_ORIENTATION_VERTICAL</entry><entry>TRUE</entry></row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>GtkScrolledWindow policy</title>
|
||
|
||
<para>
|
||
The default values for the #GtkScrolledWindow:hscrollbar-policy and
|
||
#GtkScrolledWindow: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.
|
||
</para>
|
||
</section>
|
||
<section>
|
||
<title>Prevent mixed linkage</title>
|
||
<para>
|
||
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).
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Install GTK+ modules in the right place</title>
|
||
<para>
|
||
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
|
||
<filename><replaceable>libdir</replaceable>/gtk-2.0</filename>
|
||
(and its subdirectories), for GTK+ 3 the location is
|
||
<filename><replaceable>libdir</replaceable>/gtk-3.0</filename>
|
||
(and its subdirectories).
|
||
</para>
|
||
<para>
|
||
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
|
||
<filename><replaceable>sysconfdir</replaceable>/gtk-2.0</filename>.
|
||
For GTK+ 3, they have been moved to
|
||
<filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/</filename>.
|
||
The commands that create these cache files have been renamed with a -3
|
||
suffix to make them parallel-installable.
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</section>
|
||
|
||
</section>
|
||
|
||
</chapter>
|