Pileus Git - ~andy/gtk/blob - docs/reference/gtk/migrating-2to3.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 ]>
   5 <chapter id="gtk-migrating-2-to-3">
   6   <title>Migrating from GTK+ 2.x to GTK+ 3</title>
   7
   8   <para>
   9     GTK+ 3 is a major new version of GTK+ that breaks both API and ABI
  10     compared to GTK+ 2.x, which has remained API- and ABI-stable for a
  11     long time. Thankfully, most of the changes are not hard to adapt to
  12     and there are a number of steps that you can take to prepare your
  13     GTK+ 2.x application for the switch to GTK+ 3. After that, there's
  14     a small number of adjustments that you may have to do when you actually
  15     switch your application to build against GTK+ 3.
  16   </para>
  17
  18   <section>
  19     <title>Preparation in GTK+ 2.x</title>
  20
  21     <para>
  22       The steps outlined in the following sections assume that your
  23       application is working with GTK+ 2.24, which is the final stable
  24       release of GTK+ 2.x. It includes all the necessary APIs and tools
  25       to help you port your application to GTK+ 3. If you are still using
  26       an older version of GTK+ 2.x, you should first get your application
  27       to build and work with 2.24.
  28     </para>
  29
  30   <section>
  31   <title>Do not include individual headers</title>
  32   <para>
  33     With GTK+ 2.x it was common to include just the header files for
  34     a few widgets that your application was using, which could lead
  35     to problems with missing definitions, etc. GTK+ 3 tightens the
  36     rules about which header files you are allowed to include directly.
  37     The allowed header files are are
  38     <variablelist>
  39       <varlistentry>
  40         <term><filename>gtk/gtk.h</filename></term>
  41         <listitem>for GTK</listitem>
  42       </varlistentry>
  43       <varlistentry>
  44         <term><filename>gtk/gtkunixprint.h</filename></term>
  45         <listitem>for low-level, UNIX-specific printing functions</listitem>
  46       </varlistentry>
  47       <varlistentry>
  48         <term><filename>gdk/gdk.h</filename></term>
  49         <listitem>for GDK</listitem>
  50       </varlistentry>
  51       <varlistentry>
  52         <term><filename>gdk/gdkx.h</filename></term>
  53         <listitem>for GDK functions that are X11-specific</listitem>
  54       </varlistentry>
  55       <varlistentry>
  56         <term><filename>gdk/gdkwin32.h</filename></term>
  57         <listitem>for GDK functions that are Windows-specific</listitem>
  58       </varlistentry>
  59     </variablelist>
  60     (these relative paths are assuming that you are using the include
  61      paths that are specified in the gtk+-2.0.pc file, as returned by
  62      <literal>pkg-config --cflags gtk+-2.0.pc</literal>.)
  63   </para>
  64   <para>
  65     To check that your application only includes the allowed headers,
  66     you can use defines to disable inclusion of individual headers,
  67     as follows:
  68     <programlisting>
  69     make CFLAGS+="-DGTK_DISABLE_SINGLE_INCLUDES"
  70     </programlisting>
  71   </para>
  72   </section>
  73
  74   <section>
  75   <title>Do not use deprecated symbols</title>
  76   <para>
  77     Over the years, a number of functions, and in some cases, entire
  78     widgets have been deprecated. These deprecations are clearly spelled
  79     out in the API reference, with hints about the recommended replacements.
  80     The API reference also includes an
  81     <link linkend="api-index-deprecated">index</link> of all deprecated
  82     symbols.
  83   </para>
  84   <para>
  85     To verify that your program does not use any deprecated symbols,
  86     you can use defines to remove deprecated symbols from the header files,
  87     as follows:
  88     <programlisting>
  89     make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
  90     </programlisting>
  91   </para>
  92   </section>
  93
  94   <section>
  95   <title>Use accessor functions instead of direct access</title>
  96   <para>
  97     GTK+ 3 removes many implementation details and struct members from
  98     its public headers.
  99   </para>
 100   <para>
 101     To ensure that your application does not have problems with this, you
 102     define the preprocessor symbol <literal>GSEAL_ENABLE</literal>. This
 103     will make the compiler catch all uses of direct access to struct fields
 104     so that you can go through them one by one and replace them with a call
 105     to an accessor function instead.
 106     <programlisting>
 107     make CFLAGS+="-DGSEAL_ENABLE"
 108     </programlisting>
 109   </para>
 110   </section>
 111
 112   <section>
 113     <title>Replace GDK_&lt;keyname&gt; with GDK_KEY_&lt;keyname&gt;</title>
 114
 115     <para>
 116       Key constants have gained a <literal>_KEY_</literal> infix.
 117       For example, <literal>GDK_a</literal> is now
 118       <literal>GDK_KEY_a</literal>.  In GTK+ 2, the old names continue
 119       to be available.  In GTK+ 3 however, the old names will require
 120       an explicit include of the <literal>gdkkeysyms-compat.h</literal> header.
 121     </para>
 122
 123   </section>
 124
 125   <section>
 126     <title>Use cairo for drawing</title>
 127     <para>
 128       In GTK+ 3, the GDK drawing API (which closely mimics the X
 129       drawing API, which is itself modeled after PostScript) has been
 130       removed. All drawing in GTK+ 3 is done via cairo.
 131     </para>
 132     <para>
 133       The #GdkGC and #GdkImage objects, as well as all the functions using
 134       them, are gone. This includes the <literal>gdk_draw</literal> family
 135       of functions like gdk_draw_rectangle() and gdk_draw_drawable(). As
 136       #GdkGC is roughly equivalent to #cairo_t and #GdkImage was used for
 137       drawing images to GdkDrawables, which cairo supports automatically,
 138       a transition is usually straightforward.
 139     </para>
 140     <para>
 141       The following examples show a few common drawing idioms used by
 142       applications that have been ported to use cairo and how the code
 143       was replaced.
 144     </para>
 145     <example>
 146        <title>Drawing a GdkPixbuf onto a GdkDrawable</title>
 147          <para>
 148            Drawing a pixbuf onto a drawable used to be done like this:
 149 <programlisting><![CDATA[
 150 gdk_draw_pixbuf (window,
 151                  gtk_widget_get_style (widget)->black_gc,
 152                  pixbuf,
 153                  0, 0
 154                  x, y,
 155                  gdk_pixbuf_get_width (pixbuf),
 156                  gdk_pixbuf_get_height (pixbuf),
 157                  GDK_RGB_DITHER_NORMAL,
 158                  0, 0);
 159 ]]></programlisting>
 160            Doing the same thing with cairo:
 161 <programlisting><![CDATA[
 162 cairo_t *cr = gdk_cairo_create (window);
 163 gdk_cairo_set_source_pixbuf (cr, pixbuf, x, y);
 164 cairo_paint (cr);
 165 cairo_destroy (cr);
 166 ]]></programlisting>
 167            Note that very similar code can be used for drawing pixmaps
 168            by using gdk_cairo_set_source_pixmap() instead of
 169            gdk_cairo_set_source_pixbuf().
 170          </para>
 171       </example>
 172       <example>
 173         <title>Drawing a tiled GdkPixmap to a GdkDrawable</title>
 174         <para>
 175           Tiled pixmaps are often used for drawing backgrounds.
 176           Old code looked something like this:
 177           <programlisting><![CDATA[
 178 GdkGCValues gc_values;
 179 GdkGC *gc;
 180
 181 /* setup */
 182 gc = gtk_widget_get_style (widget)->black_gc;
 183 gdk_gc_set_tile (gc, pixmap);
 184 gdk_gc_set_fill (gc, GDK_TILED);
 185 gdk_gc_set_ts_origin (gc, x_origin, y_origin);
 186 /* use */
 187 gdk_draw_rectangle (drawable, gc, TRUE, 0, 0, width, height);
 188 /* restore */
 189 gdk_gc_set_tile (gc, NULL);
 190 gdk_gc_set_fill (gc, GDK_SOLID);
 191 gdk_gc_set_ts_origin (gc, 0, 0);
 192 ]]></programlisting>
 193           The equivalent cairo code looks like this:
 194 <programlisting><![CDATA[
 195 cairo_t *cr;
 196
 197 cr = gdk_cairo_create (drawable);
 198 gdk_cairo_set_source_pixmap (cr, pixmap, x_origin, y_origin);
 199 cairo_pattern_set_extend (cairo_get_source (cr), CAIRO_EXTEND_REPEAT);
 200 cairo_rectangle (cr, 0, 0, width, height);
 201 cairo_fill (cr);
 202 cairo_destroy (cr);
 203 ]]></programlisting>
 204           Again, you can exchange pixbufs and pixmaps by using
 205           gdk_cairo_set_source_pixbuf() instead of
 206           gdk_cairo_set_source_pixmap().
 207         </para>
 208       </example>
 209       <example>
 210         <title>Drawing a PangoLayout to a clipped area</title>
 211         <para>
 212           Drawing layouts clipped is often used to avoid overdraw or to
 213           allow drawing selections. Code would have looked like this:
 214 <programlisting><![CDATA[
 215 GdkGC *gc;
 216
 217 /* setup */
 218 gc = gtk_widget_get_style (widget)->text_gc[state];
 219 gdk_gc_set_clip_rectangle (gc, &area);
 220 /* use */
 221 gdk_draw_layout (drawable, gc, x, y, layout);
 222 /* restore */
 223 gdk_gc_set_clip_rectangle (gc, NULL);
 224 ]]></programlisting>
 225           With cairo, the same effect can be achieved using:
 226 <programlisting><![CDATA[
 227 cairo_t *cr;
 228
 229 cr = gdk_cairo_create (drawable);
 230 /* clip */
 231 gdk_cairo_rectangle (cr, &area);
 232 cairo_clip (cr);
 233 /* set the correct source color */
 234 gdk_cairo_set_source_color (cr, &gtk_widget_get_style (widget)->text[state]);
 235 /* draw the text */
 236 cairo_move_to (cr, x, y);
 237 pango_cairo_show_layout (cr, layout);
 238 cairo_destroy (cr);
 239 ]]></programlisting>
 240           Clipping using cairo_clip() is of course not restricted to text
 241           rendering and can be used everywhere where GC clips were used.
 242           And using gdk_cairo_set_source_color() with style colors should
 243           be used in all the places where a style’s GC was used to achieve
 244           a particular color.
 245         </para>
 246       </example>
 247     <section>
 248       <title>What should you be aware of ?</title>
 249       <formalpara><title>No more stippling</title>
 250         <para>
 251           Stippling is the usage of a bi-level mask, called a #GdkBitmap.
 252           It was often used to achieve a checkerboard effect. You can use
 253           cairo_mask() to achieve this effect. To get a checkerbox mask,
 254           you can use code like this:
 255 <programlisting><![CDATA[
 256 static cairo_pattern_t *
 257 gtk_color_button_get_checkered (void)
 258 {
 259     /* need to respect pixman's stride being a multiple of 4 */
 260     static unsigned char data[8] = { 0xFF, 0x00, 0x00, 0x00,
 261                                      0x00, 0xFF, 0x00, 0x00 };
 262     cairo_surface_t *surface;
 263     cairo_pattern_t *pattern;
 264
 265     surface = cairo_image_surface_create_for_data (data,
 266                                                    CAIRO_FORMAT_A8,
 267                                                    2, 2,
 268                                                    4);
 269     pattern = cairo_pattern_create_for_surface (surface);
 270     cairo_surface_destroy (surface);
 271     cairo_pattern_set_extend (pattern, CAIRO_EXTEND_REPEAT);
 272     cairo_pattern_set_filter (pattern, CAIRO_FILTER_NEAREST);
 273
 274     return pattern;
 275 }
 276 ]]></programlisting>
 277           Note that stippling looks very outdated in UIs, and is rarely
 278           used in modern applications. All properties that made use of
 279           stippling have been removed from GTK+ 3. Most prominently,
 280           stippling is absent from text rendering, in particular #GtkTextTag.
 281         </para>
 282       </formalpara>
 283       <formalpara><title>Using the the target drawable also as source or mask</title>
 284         <para>
 285           The gdk_draw_drawable() function allowed using the same drawable
 286           as source and target. This was often used to achieve a scrolling
 287           effect. Cairo does not allow this yet. You can however use
 288           cairo_push_group() to get a different intermediate target that
 289           you can copy to. So you can replace this code:
 290 <programlisting><![CDATA[
 291 gdk_draw_drawable (pixmap,
 292                    gc,
 293                    pixmap,
 294                    area.x + dx, area.y + dy,
 295                    area.x, area.y,
 296                    area.width, area.height);
 297 ]]></programlisting>
 298           By using this code:
 299 <programlisting><![CDATA[
 300 cairo_t *cr = gdk_cairo_create (pixmap);
 301 /* clipping restricts the intermediate surface's size, so it's a good idea
 302  * to use it. */
 303 gdk_cairo_rectangle (cr, &area);
 304 cairo_clip (cr);
 305 /* Now push a group to change the target */
 306 cairo_push_group (cr);
 307 gdk_cairo_set_source_pixmap (cr, pixmap, dx, dy);
 308 cairo_paint (cr);
 309 /* Now copy the intermediate target back */
 310 cairo_pop_group_to_source (cr);
 311 cairo_paint (cr);
 312 cairo_destroy (cr);
 313 ]]></programlisting>
 314           The cairo developers plan to add self-copies in the future to allow
 315           exactly this effect, so you might want to keep up on cairo
 316           development to be able to change your code.
 317         </para>
 318       </formalpara>
 319       <formalpara><title>Using pango_cairo_show_layout(<!-- -->) instead of gdk_draw_layout_with_colors(<!-- -->)</title>
 320         <para>
 321           GDK provided a way to ignore the color attributes of text and use
 322           a hardcoded text color with the gdk_draw_layout_with_colors()
 323           function. This is often used to draw text shadows or selections.
 324           Pango’s cairo support does not yet provide this functionality. If
 325           you use Pango layouts that change colors, the easiest way to achieve
 326           a similar effect is using pango_cairo_layout_path() and cairo_fill()
 327           instead of gdk_draw_layout_with_colors(). Note that this results in
 328           a slightly uglier-looking text, as subpixel anti-aliasing is not
 329           supported.
 330         </para>
 331       </formalpara>
 332     </section>
 333     </section>
 334   </section>
 335
 336   <section>
 337     <title>Changes that need to be done at the time of the switch</title>
 338
 339   <para>
 340     This section outlines porting tasks that you need to tackle when
 341     you get to the point that you actually build your application against
 342     GTK+ 3. Making it possible to prepare for these in GTK+ 2.24 would
 343     have been either impossible or impractical.
 344   </para>
 345
 346   <section>
 347     <title>Replace size_request by get_preferred_width/height</title>
 348
 349     <para>
 350       The request-phase of the traditional GTK+ geometry management
 351       has been replaced by a more flexible height-for-width system,
 352       which is described in detail in the API documentation
 353       (see <xref linkend="geometry-management"/>). As a consequence,
 354       the ::size-request signal and vfunc has been removed from
 355       #GtkWidgetClass. The replacement for size_request() can
 356       take several levels of sophistication:
 357       <itemizedlist>
 358         <listitem>
 359         <para>
 360         As a minimal replacement to keep current functionality,
 361         you can simply implement the #GtkWidgetClass.get_preferred_width() and
 362         #GtkWidgetClass.get_preferred_height() vfuncs by calling your existing
 363         size_request() function. So you go from
 364         <informalexample><programlisting>
 365 static void
 366 my_widget_class_init (MyWidgetClass *class)
 367 {
 368   GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);
 369
 370   /* ... */
 371
 372   widget_class->size_request = my_widget_size_request;
 373
 374   /* ... */
 375 }
 376         </programlisting></informalexample>
 377         <para>
 378         to something that looks more like this:
 379         </para>
 380         <informalexample><programlisting>
 381 static void
 382 my_widget_get_preferred_width (GtkWidget *widget,
 383                                gint      *minimal_width,
 384                                gint      *natural_width)
 385 {
 386   GtkRequisition requisition;
 387
 388   my_widget_size_request (widget, &amp;requisition);
 389
 390   *minimal_width = *natural_width = requisition.width;
 391 }
 392
 393 static void
 394 my_widget_get_preferred_height (GtkWidget *widget,
 395                                 gint      *minimal_height,
 396                                 gint      *natural_height)
 397 {
 398   GtkRequisition requisition;
 399
 400   my_widget_size_request (widget, &amp;requisition);
 401
 402   *minimal_height = *natural_height = requisition.height;
 403 }
 404
 405  /* ... */
 406
 407 static void
 408 my_widget_class_init (MyWidgetClass *class)
 409 {
 410   GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);
 411
 412   /* ... */
 413
 414   widget_class->get_preferred_width = my_widget_get_preferred_width;
 415   widget_class->get_preferred_height = my_widget_get_preferred_height;
 416
 417   /* ... */
 418
 419 }
 420         </programlisting></informalexample>
 421           <para>
 422           Sometimes you can make things a little more streamlined
 423           by replacing your existing size_request() implementation by
 424           one that takes an orientation parameter:
 425           </para>
 426           <informalexample><programlisting>
 427 static void
 428 my_widget_get_preferred_size (GtkWidget      *widget,
 429                               GtkOrientation  orientation,
 430                                gint          *minimal_size,
 431                                gint          *natural_size)
 432 {
 433
 434   /* do things that are common for both orientations ... */
 435
 436   if (orientation == GTK_ORIENTATION_HORIZONTAL)
 437     {
 438       /* do stuff that only applies to width... */
 439
 440       *minimal_size = *natural_size = ...
 441     }
 442   else
 443    {
 444       /* do stuff that only applies to height... */
 445
 446       *minimal_size = *natural_size = ...
 447    }
 448 }
 449
 450 static void
 451 my_widget_get_preferred_width (GtkWidget *widget,
 452                                gint      *minimal_width,
 453                                gint      *natural_width)
 454 {
 455   my_widget_get_preferred_size (widget,
 456                                 GTK_ORIENTATION_HORIZONTAL,
 457                                 minimal_width,
 458                                 natural_width);
 459 }
 460
 461 static void
 462 my_widget_get_preferred_height (GtkWidget *widget,
 463                                 gint      *minimal_height,
 464                                 gint      *natural_height)
 465 {
 466   my_widget_get_preferred_size (widget,
 467                                 GTK_ORIENTATION_VERTICAL,
 468                                 minimal_height,
 469                                 natural_height);
 470 }
 471
 472  /* ... */
 473           </programlisting></informalexample>
 474           </para>
 475         </listitem>
 476         <listitem>
 477           <para>If your widget can cope with a small size,
 478           but would appreciate getting some more space (a common
 479           example would be that it contains ellipsizable labels),
 480           you can do that by making your #GtkWidgetClass.get_preferred_width() /
 481           #GtkWidgetClass.get_preferred_height()
 482           functions return a smaller value for @minimal than for @natural.
 483           For @minimal, you probably want to return the same value
 484           that your size_request() function returned before (since
 485           size_request() was defined as returning the minimal size
 486           a widget can work with). A simple way to obtain good
 487           values for @natural, in the case of containers, is to use
 488           gtk_widget_get_preferred_width() and
 489           gtk_widget_get_preferred_height() on the children of the
 490           container, as in the following example:
 491           <informalexample><programlisting>
 492 static void
 493 gtk_fixed_get_preferred_height (GtkWidget *widget,
 494                                 gint      *minimum,
 495                                 gint      *natural)
 496 {
 497   GtkFixed *fixed = GTK_FIXED (widget);
 498   GtkFixedPrivate *priv = fixed->priv;
 499   GtkFixedChild *child;
 500   GList *children;
 501   gint child_min, child_nat;
 502
 503   *minimum = 0;
 504   *natural = 0;
 505
 506   for (children = priv->children; children; children = children->next)
 507     {
 508       child = children->data;
 509
 510       if (!gtk_widget_get_visible (child->widget))
 511         continue;
 512
 513       gtk_widget_get_preferred_height (child->widget, &amp;child_min, &amp;child_nat);
 514
 515       *minimum = MAX (*minimum, child->y + child_min);
 516       *natural = MAX (*natural, child->y + child_nat);
 517     }
 518 }
 519           </programlisting></informalexample>
 520           </para>
 521         </listitem>
 522         <listitem>
 523           <para>
 524           Note that the #GtkWidgetClass.get_preferred_width() /
 525           #GtkWidgetClass.get_preferred_height() functions
 526           only allow you to deal with one dimension at a time. If your
 527           size_request() handler is doing things that involve both
 528           width and height at the same time (e.g. limiting the aspect
 529           ratio), you will have to implement
 530           #GtkWidgetClass.get_preferred_height_for_width()
 531           and #GtkWidgetClass.get_preferred_width_for_height().
 532           </para>
 533         </listitem>
 534         <listitem>
 535           <para>
 536           To make full use of the new capabilities of the
 537           height-for-width geometry management, you need to additionally
 538           implement the #GtkWidgetClass.get_preferred_height_for_width() and
 539           #GtkWidgetClass.get_preferred_width_for_height(). For details on
 540           these functions, see <xref linkend="geometry-management"/>.
 541           </para>
 542         </listitem>
 543       </itemizedlist>
 544     </para>
 545   </section>
 546
 547   <section>
 548     <title>Replace GdkRegion by cairo_region_t</title>
 549
 550     <para>
 551       Starting with version 1.10, cairo provides a region API that is
 552       equivalent to the GDK region API (which was itself copied from
 553       the X server). Therefore, the region API has been removed in GTK+ 3.
 554     </para>
 555     <para>
 556       Porting your application to the cairo region API should be a straight
 557       find-and-replace task. Please refer to the following table:
 558       <table>
 559         <tgroup cols="2">
 560           <thead>
 561             <row><entry>GDK</entry><entry>cairo</entry></row>
 562           </thead>
 563           <tbody>
 564             <row><entry>#GdkRegion</entry><entry>#cairo_region_t</entry></row>
 565             <row><entry>#GdkRectangle</entry><entry>#cairo_rectangle_int_t</entry></row>
 566             <row><entry>gdk_rectangle_intersect()</entry><entry>this function is still there</entry></row>
 567             <row><entry>gdk_rectangle_union()</entry><entry>this function is still there</entry></row>
 568             <row><entry>gdk_region_new()</entry><entry>cairo_region_create()</entry></row>
 569             <row><entry>gdk_region_copy()</entry><entry>cairo_region_copy()</entry></row>
 570             <row><entry>gdk_region_destroy()</entry><entry>cairo_region_destroy()</entry></row>
 571             <row><entry>gdk_region_rectangle()</entry><entry>cairo_region_create_rectangle()</entry></row>
 572             <row><entry>gdk_region_get_clipbox()</entry><entry>cairo_region_get_extents()</entry></row>
 573             <row><entry>gdk_region_get_rectangles()</entry><entry>cairo_region_num_rectangles() and
 574                                 cairo_region_get_rectangle()</entry></row>
 575             <row><entry>gdk_region_empty()</entry><entry>cairo_region_is_empty()</entry></row>
 576             <row><entry>gdk_region_equal()</entry><entry>cairo_region_equal()</entry></row>
 577             <row><entry>gdk_region_point_in()</entry><entry>cairo_region_contains_point()</entry></row>
 578             <row><entry>gdk_region_rect_in()</entry><entry>cairo_region_contains_rectangle()</entry></row>
 579             <row><entry>gdk_region_offset()</entry><entry>cairo_region_translate()</entry></row>
 580             <row><entry>gdk_region_union_with_rect()</entry><entry>cairo_region_union_rectangle()</entry></row>
 581             <row><entry>gdk_region_intersect()</entry><entry>cairo_region_intersect()</entry></row>
 582             <row><entry>gdk_region_union()</entry><entry>cairo_region_union()</entry></row>
 583             <row><entry>gdk_region_subtract()</entry><entry>cairo_region_subtract()</entry></row>
 584             <row><entry>gdk_region_xor()</entry><entry>cairo_region_xor()</entry></row>
 585             <row><entry>gdk_region_shrink()</entry><entry>no replacement</entry></row>
 586             <row><entry>gdk_region_polygon()</entry><entry>no replacement, use cairo paths instead</entry></row>
 587           </tbody>
 588         </tgroup>
 589       </table>
 590     </para>
 591   </section>
 592
 593   <section>
 594     <title>Replace GdkPixmap by cairo surfaces</title>
 595     <para>
 596       The #GdkPixmap object and related functions have been removed.
 597       In the cairo-centric world of GTK+ 3, cairo surfaces take over
 598       the role of pixmaps.
 599     </para>
 600     <example>
 601       <title>Creating custom cursors</title>
 602       <para>
 603         One place where pixmaps were commonly used is to create custom
 604         cursors:
 605       <programlisting>
 606 GdkCursor *cursor;
 607 GdkPixmap *pixmap;
 608 cairo_t *cr;
 609 GdkColor fg = { 0, 0, 0, 0 };
 610
 611 pixmap = gdk_pixmap_new (NULL, 1, 1, 1);
 612
 613 cr = gdk_cairo_create (pixmap);
 614 cairo_rectangle (cr, 0, 0, 1, 1);
 615 cairo_fill (cr);
 616 cairo_destroy (cr);
 617
 618 cursor = gdk_cursor_new_from_pixmap (pixmap, pixmap, &amp;fg, &amp;fg, 0, 0);
 619
 620 g_object_unref (pixmap);
 621       </programlisting>
 622       The same can be achieved without pixmaps, by drawing onto
 623       an image surface:
 624       <programlisting>
 625 GdkCursor *cursor;
 626 cairo_surface_t *s;
 627 cairo_t *cr;
 628 GdkPixbuf *pixbuf;
 629
 630 s = cairo_image_surface_create (CAIRO_FORMAT_A1, 3, 3);
 631 cr = cairo_create (s);
 632 cairo_arc (cr, 1.5, 1.5, 1.5, 0, 2 * M_PI);
 633 cairo_fill (cr);
 634 cairo_destroy (cr);
 635
 636 pixbuf = gdk_pixbuf_get_from_surface (NULL, s,
 637                                       0, 0, 0, 0,
 638                                       3, 3);
 639
 640 cairo_surface_destroy (s);
 641
 642 cursor = gdk_cursor_new_from_pixbuf (display, pixbuf, 0, 0);
 643
 644 g_object_unref (pixbuf);
 645       </programlisting>
 646       </para>
 647     </example>
 648   </section>
 649
 650   <section>
 651     <title>Replace colormaps by visuals</title>
 652     <para>
 653       For drawing with cairo, it is not necessary to allocate colors, and
 654       a #GdkVisual provides enough information for cairo to handle colors
 655       in 'native' surfaces. Therefore, #GdkColormap and related functions
 656       have been removed in GTK+ 3, and visuals are used instead. The
 657       colormap-handling functions of #GtkWidget (gtk_widget_set_colormap(),
 658       etc) have been removed and gtk_window_set_visual() has been added.
 659     </para>
 660     <example><title>Setting up a translucent window</title>
 661     <para>You might have a screen-changed handler like the following
 662      to set up a translucent window with an alpha-channel:
 663     </para>
 664     <programlisting>
 665 static void
 666 on_alpha_screen_changed (GtkWidget *widget,
 667                          GdkScreen *old_screen,
 668                          GtkWidget *label)
 669 {
 670   GdkScreen *screen = gtk_widget_get_screen (widget);
 671   GdkColormap *colormap = gdk_screen_get_rgba_colormap (screen);
 672
 673   if (colormap == NULL)
 674     colormap = gdk_screen_get_default_colormap (screen);
 675
 676   gtk_widget_set_colormap (widget, colormap);
 677 }
 678     </programlisting>
 679     <para>
 680     With visuals instead of colormaps, this will look as follows:
 681     </para>
 682     <programlisting>
 683 static void
 684 on_alpha_screen_changed (GtkWindow *window,
 685                          GdkScreen *old_screen,
 686                          GtkWidget *label)
 687 {
 688   GdkScreen *screen = gtk_widget_get_screen (GTK_WIDGET (window));
 689   GdkVisual *visual = gdk_screen_get_rgba_visual (screen);
 690
 691   if (visual == NULL)
 692     visual = gdk_screen_get_system_visual (screen);
 693
 694   gtk_window_set_visual (window, visual);
 695 }
 696     </programlisting>
 697     </example>
 698   </section>
 699
 700   <section>
 701     <title>The GtkWidget::draw signal</title>
 702     <para>
 703       The GtkWidget #GtkWidget::expose-event signal has been replaced by
 704       a new #GtkWidget::draw signal, which takes a #cairo_t instead of
 705       an expose event. The cairo context is being set up so that the origin
 706       at (0, 0) coincides with the upper left corner of the widget, and
 707       is properly clipped.
 708     </para>
 709     <note><para>In other words, the cairo context of the draw signal is set
 710       up in 'widget coordinates', which is different from traditional expose
 711       event handlers, which always assume 'window coordinates'.
 712     </para></note>
 713     <para>
 714       The widget is expected to draw itself with its allocated size, which
 715       is available via the new gtk_widget_get_allocated_width() and
 716       gtk_widget_get_allocated_height() functions. It is not necessary to
 717       check for GTK_WIDGET_IS_DRAWABLE(), since GTK+ already does this check
 718       before emitting the ::draw signal.
 719     </para>
 720     <para>
 721       There are some special considerations for widgets with multiple windows.
 722       Expose events are window-specific, and widgets with multiple windows
 723       could expect to get an expose event for each window that needs to be
 724       redrawn. Therefore, multi-window expose event handlers typically look
 725       like this:
 726       <informalexample><programlisting>
 727       if (event->window == widget->window1)
 728         {
 729            /* ... draw window1 ... */
 730         }
 731       else if (event->window == widget->window2)
 732         {
 733            /* ... draw window2 ... */
 734         }
 735       ...
 736       </programlisting></informalexample>
 737       In contrast, the ::draw signal handler may have to draw multiple
 738       windows in one call. GTK+ has a convenience function
 739       gtk_cairo_should_draw_window() that can be used to find out if
 740       a window needs to be drawn. With that, the example above would look
 741       like this (note that the 'else' is gone):
 742       <informalexample><programlisting>
 743       if (gtk_cairo_should_draw_window (cr, widget->window1)
 744         {
 745            /* ... draw window1 ... */
 746         }
 747       if (gtk_cairo_should_draw_window (cr, widget->window2)
 748         {
 749            /* ... draw window2 ... */
 750         }
 751       ...
 752       </programlisting></informalexample>
 753       Another convenience function that can help when implementing
 754       ::draw for multi-window widgets is gtk_cairo_transform_to_window(),
 755       which transforms a cairo context from widget-relative coordinates
 756       to window-relative coordinates.
 757     </para>
 758     <para>
 759       All GtkStyle drawing functions (gtk_paint_box(), etc) have been changed
 760       to take a #cairo_t instead of a window and a clip area. ::draw
 761       implementations will usually just use the cairo context that has been
 762       passed in for this.
 763     </para>
 764     <example><title>A simple ::draw function</title>
 765     <programlisting>
 766 gboolean
 767 gtk_arrow_draw (GtkWidget *widget,
 768                 cairo_t   *cr)
 769 {
 770   gint x, y;
 771   gint width, height;
 772   gint extent;
 773
 774   width = gtk_widget_get_allocated_width (widget);
 775   height = gtk_widget_get_allocated_height (widget);
 776
 777   extent = MIN (width - 2 * PAD, height - 2 * PAD);
 778   x = PAD;
 779   y = PAD;
 780
 781   gtk_paint_arrow (gtk_widget_get_style (widget),
 782                    cr,
 783                    gtk_widget_get_state (widget),
 784                    GTK_SHADOW_OUT,
 785                    widget,
 786                    "arrow",
 787                    widget->priv->arrow_type,
 788                    TRUE,
 789                    x, y, extent, extent);
 790 }
 791     </programlisting>
 792     </example>
 793   </section>
 794
 795   <section>
 796     <title>GtkProgressBar orientation</title>
 797
 798     <para>
 799       In GTK+ 2.x, #GtkProgressBar and #GtkCellRendererProgress were using the
 800       GtkProgressBarOrientation enumeration to specify their orientation and
 801       direction. In GTK+ 3, both the widget and the cell renderer implement
 802       #GtkOrientable, and have an additional 'inverted' property to determine
 803       their direction. Therefore, a call to gtk_progress_bar_set_orientation()
 804       needs to be replaced by a pair of calls to
 805       gtk_orientable_set_orientation() and gtk_progress_bar_set_inverted().
 806       The following values correspond:
 807       <table>
 808         <tgroup cols="3">
 809           <colspec colname="1"/>
 810           <colspec colname="2"/>
 811           <colspec colname="3"/>
 812           <thead>
 813             <row><entry>GTK+ 2.x</entry><entry namest="2" nameend="3">GTK+ 3</entry></row>
 814             <row><entry>GtkProgressBarOrientation</entry><entry>GtkOrientation</entry><entry>inverted</entry></row>
 815           </thead>
 816           <tbody>
 817             <row><entry>GTK_PROGRESS_LEFT_TO_RIGHT</entry><entry>GTK_ORIENTATION_HORIZONTAL</entry><entry>FALSE</entry></row>
 818             <row><entry>GTK_PROGRESS_RIGHT_TO_LEFT</entry><entry>GTK_ORIENTATION_HORIZONTAL</entry><entry>TRUE</entry></row>
 819             <row><entry>GTK_PROGRESS_TOP_TO_BOTTOM</entry><entry>GTK_ORIENTATION_VERTICAL</entry><entry>FALSE</entry></row>
 820             <row><entry>GTK_PROGRESS_BOTTOM_TO_TOP</entry><entry>GTK_ORIENTATION_VERTICAL</entry><entry>TRUE</entry></row>
 821           </tbody>
 822         </tgroup>
 823       </table>
 824     </para>
 825   </section>
 826
 827   <section>
 828     <title>Check your expand flags</title>
 829
 830     <para>
 831       The behaviour of expanding widgets has changed slightly in GTK+ 3,
 832       compared to GTK+ 2.x. It is now 'inherited', i.e. a container that
 833       has an expanding child is considered expanding itself. This is often
 834       the desired behaviour. In places where you don't want this to happen,
 835       setting the container explicity as not expanding will stop the
 836       expand flag of the child from being inherited. See
 837       gtk_widget_set_hexpand() and gtk_widget_set_vexpand().
 838     </para>
 839   </section>
 840
 841   <section>
 842     <title>Scrolling changes</title>
 843
 844     <para>
 845       The default values for the #GtkScrolledWindow:hscrollbar-policy and
 846       #GtkScrolledWindow:vscrollbar-policy properties have been changed from
 847       'never' to 'automatic'. If your application was relying on the default
 848       value, you will have explicitly set it explicitly.
 849     </para>
 850
 851     <para>
 852       The ::set-scroll-adjustments signal on GtkWidget has been replaced
 853       by the #GtkScrollable interface which must be implemented by a widget
 854       that wants to be placed in a #GtkScrolledWindow. Instead of emitting
 855       ::set-scroll-adjustments, the scrolled window simply sets the
 856       #GtkScrollable::hadjustment and #GtkScrollable::vadjustment properties.
 857     </para>
 858   </section>
 859
 860   <section>
 861     <title>GtkObject is gone</title>
 862
 863     <para>
 864       GtkObject has been removed in GTK+ 3. Its remaining functionality,
 865       the ::destroy signal, has been moved to GtkWidget. If you have non-widget
 866       classes that are directly derived from GtkObject, you have to make
 867       them derive from #GInitiallyUnowned (or, if you don't need the floating
 868       functionality, #GObject). If you have widgets that override the
 869       destroy class handler, you have to adust your class_init function,
 870       since destroy is now a member of GtkWidgetClass:
 871       <informalexample><programlisting>
 872       GtkObjectClass *object_class = GTK_OBJECT_CLASS (class);
 873
 874       object_class->destroy = my_destroy;
 875       </programlisting></informalexample>
 876       becomes
 877       <informalexample><programlisting>
 878       GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);
 879
 880       widget_class->destroy = my_destroy;
 881       </programlisting></informalexample>
 882       In the unlikely case that you have a non-widget class that is derived
 883       from GtkObject and makes use of the destroy functionality, you have
 884       to implement ::destroy yourself.
 885     </para>
 886   </section>
 887
 888   <section>
 889     <title>Resize grips</title>
 890
 891     <para>
 892      The resize grip functionality has been moved from #GtkStatusbar
 893      to #GtkWindow. Any window can now have resize grips, regardless whether
 894      it has a statusbar or not. The functions
 895      gtk_statusbar_set_has_resize_grip() and gtk_statusbar_get_has_resize_grip()
 896      have disappeared, and instead there are now
 897      gtk_window_set_has_resize_grip() and gtk_window_get_has_resize_grip().
 898     </para>
 899   </section>
 900
 901   <section>
 902     <title>Prevent mixed linkage</title>
 903     <para>
 904       Linking against GTK+ 2.x and GTK+ 3 in the same process is problematic
 905       and can lead to hard-to-diagnose crashes. The gtk_init() function in
 906       both GTK+ 2.22 and in GTK+ 3 tries to detect this situation and abort
 907       with a diagnostic message, but this check is not 100% reliable (e.g. if
 908       the problematic linking happens only in loadable modules).
 909     </para>
 910     <para>
 911       Direct linking of your application against both versions of GTK+ is
 912       easy to avoid; the problem gets harder when your application is using
 913       libraries that are themselves linked against some version of GTK+.
 914       In that case, you have to verify that you are using a version of the
 915       library that is linked against GTK+ 3.
 916     </para>
 917     <para>
 918       If you are using packages provided by a distributor, it is likely that
 919       parallel installable versions of the library exist for GTK+ 2.x and
 920       GTK+ 3, e.g for vte, check for vte3; for webkitgtk look for webkitgtk3,
 921       and so on.
 922     </para>
 923   </section>
 924
 925   <section>
 926   <title>Install GTK+ modules in the right place</title>
 927   <para>
 928     Some software packages install loadable GTK+ modules such as theme engines,
 929     gdk-pixbuf loaders or input methods. Since GTK+ 3 is parallel-installable
 930     with GTK+ 2.x, the two GTK+ versions have separate locations for their
 931     loadable modules. The location for GTK+ 2.x is
 932     <filename><replaceable>libdir</replaceable>/gtk-2.0</filename>
 933     (and its subdirectories), for GTK+ 3 the location is
 934     <filename><replaceable>libdir</replaceable>/gtk-3.0</filename>
 935     (and its subdirectories).
 936   </para>
 937   <para>
 938     For some kinds of modules, namely input methods and pixbuf loaders,
 939     GTK+ keeps a cache file with extra information about the modules.
 940     For GTK+ 2.x, these cache files are located in
 941     <filename><replaceable>sysconfdir</replaceable>/gtk-2.0</filename>.
 942     For GTK+ 3, they have been moved to
 943     <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/</filename>.
 944     The commands that create these cache files have been renamed with a -3
 945     suffix to make them parallel-installable.
 946   </para>
 947   <para>
 948     Note that GTK+ modules often link against libgtk, libgdk-pixbuf, etc.
 949     If that is the case for your module, you have to be careful to link the
 950     GTK+ 2.x version of your module against the 2.x version of the libraries,
 951     and the GTK+ 3 version against hte 3.x versions. Loading a module linked
 952     against libgtk 2.x into an application using GTK+ 3 will lead to
 953     unhappiness and must be avoided.
 954   </para>
 955   </section>
 956
 957   </section>
 958
 959 </chapter>