Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml

   1 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
   2 Drawables to Pixbufs
   3
   4
   5 <!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
   6   <para>
   7     A function of this type can be used to override the default
   8     operation when a pixbuf loses its last reference, i.e. when
   9     gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
  10     reference count of 1.  This function should determine whether to
  11     finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
  12     to just resume normal execution.  The last unref handler for a
  13     #GdkPixbuf can be set using the
  14     gdk_pixbuf_set_last_unref_handler() function.  By default, pixbufs
  15     will be finalized automatically if no last unref handler has been
  16     defined.
  17   </para>
  18
  19 @pixbuf: The pixbuf that is losing its last reference.
  20 @data: User closure data.
  21
  22 <!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### -->
  23 <para>
  24
  25 </para>
  26
  27
  28 <!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
  29   <para>
  30     GdkRGB
  31   </para>
  32
  33
  34 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
  35 X Drawables to Pixbufs
  36
  37
  38 <!-- ##### FUNCTION gdk_pixbuf_render_pixmap_and_mask ##### -->
  39 <para>
  40
  41 </para>
  42
  43 @pixbuf:
  44 @pixmap_return:
  45 @mask_return:
  46 @alpha_threshold: <!--
  47 Local variables:
  48 mode: sgml
  49 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
  50 End:
  51 -->
  52
  53 <!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
  54   <para>
  55     Indicates the width the pixbuf will be scaled to.  This argument
  56     will only be used if the <link
  57     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
  58     is %TRUE.  If the <link
  59     linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
  60     argument is %FALSE, the width will be taken to be in canvas units,
  61     and thus will be scaled along with the canvas item's affine
  62     transformation.  If width_in_pixels is %TRUE, the width will be
  63     taken to be in pixels, and will visually remain a constant size
  64     even if the item's affine transformation changes.
  65   </para>
  66
  67
  68 <!-- ##### FUNCTION gdk_pixbuf_render_to_drawable ##### -->
  69 <para>
  70
  71 </para>
  72
  73 @pixbuf:
  74 @drawable:
  75 @gc:
  76 @src_x:
  77 @src_y:
  78 @dest_x:
  79 @dest_y:
  80 @width:
  81 @height:
  82 @dither:
  83 @x_dither:
  84 @y_dither:
  85
  86 <!-- ##### FUNCTION gdk_pixbuf_get_from_drawable ##### -->
  87 <para>
  88
  89 </para>
  90
  91 @dest:
  92 @src:
  93 @cmap:
  94 @src_x:
  95 @src_y:
  96 @dest_x:
  97 @dest_y:
  98 @width:
  99 @height:
 100 @Returns: <!--
 101 Local variables:
 102 mode: sgml
 103 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 104 End:
 105 -->
 106
 107 <!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
 108   <para>
 109     Indicates the horizontal translation offset of the pixbuf item's
 110     image.  This offset may not actually appear horizontal, since it
 111     will be affected by the item's affine transformation.  The default
 112     is 0.0.
 113   </para>
 114
 115
 116 <!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
 117   <para>
 118     Indicates the vertical translation offset of the pixbuf item's
 119     image.  Works in the same way as the <link
 120     linkend="GnomeCanvasPixbuf--x">x</link> argument.  The default is
 121     0.0.
 122   </para>
 123
 124
 125 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
 126 Initializing the &gdk-pixbuf; Xlib library.
 127
 128
 129 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
 130   <para>
 131     The functions in this section allow you to take the image data
 132     from an X drawable and dump it into a #GdkPixbuf.  This can be
 133     used for screenshots and other special effects.  Note that these
 134     operations can be expensive, since the image data has to be
 135     transferred from the X server to the client program and converted.
 136   </para>
 137
 138   <para>
 139     These functions are analogous to those for the Gdk version of
 140     &gdk-pixbuf;.
 141   </para>
 142
 143
 144 <!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @art_pixbuf:
 150 @Returns:
 151
 152 <!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
 153   <para>
 154     XlibRGB
 155   </para>
 156
 157
 158 <!-- ##### ARG GnomeCanvasPixbuf:y_in_pixels ##### -->
 159   <para>
 160     Works in the same way as the <link
 161     linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
 162     argument, but controls whether the <link
 163     linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
 164     scaled or not.  The default is %FALSE.
 165   </para>
 166
 167 <!--
 168 Local variables:
 169 mode: sgml
 170 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 171 End:
 172 -->
 173
 174
 175 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
 176   <para>
 177     #GnomeCanvas, #GdkPixbuf
 178   </para>
 179
 180
 181 <!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
 182   <para>
 183     Contains a pointer to a #GdkPixbuf structure that will be used by
 184     the pixbuf canvas item as an image source.  When a pixbuf is set
 185     its reference count is incremented; if the pixbuf item kept a
 186     pointer to another #GdkPixbuf structure, the reference count of
 187     this structure will be decremented.  Also, the GdkPixbuf's
 188     reference count will automatically be decremented when the
 189     #GnomeCanvasPixbuf item is destroyed.  When a pixbuf is queried, a
 190     reference count will not be added to the return value; you must do
 191     this yourself if you intend to keep the pixbuf structure around.
 192   </para>
 193
 194
 195 <!-- ##### ARG GnomeCanvasPixbuf:y_pixels ##### -->
 196 <para>
 197
 198 </para>
 199
 200
 201 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
 202   <para>
 203     GdkRGB
 204   </para>
 205
 206
 207 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
 208   <para>
 209     The &gdk-pixbuf; Xlib library provides several convenience
 210     functions to render pixbufs to X drawables.  It uses XlibRGB to
 211     render the image data.
 212   </para>
 213
 214   <para>
 215     These functions are analogous to those for the Gdk version of
 216     &gdk-pixbuf;.
 217   </para>
 218
 219
 220 <!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Short_Description ##### -->
 221
 222
 223
 224 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
 225 Canvas item to display #GdkPixbuf images.
 226
 227
 228 <!-- ##### ARG GnomeCanvasPixbuf:x_in_pixels ##### -->
 229   <para>
 230     If this argument is %TRUE, the pixbuf's translation with respect
 231     to its logical origin in item-relative coordinates will be in
 232     pixels, that is, the visible offset will not change even if the
 233     item's affine transformation changes.  If it is %FALSE, the
 234     pixbuf's translation will be taken to be in canvas units, and thus
 235     will change along with the item's affine transformation.  The
 236     default is %FALSE.
 237   </para>
 238
 239
 240 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
 241   <para>
 242     The functions in this section allow you to take the image data
 243     from a GDK drawable and dump it into a #GdkPixbuf.  This can be
 244     used for screenshots and other special effects.  Note that these
 245     operations can be expensive, since the image data has to be
 246     transferred from the X server to the client program and converted.
 247   </para>
 248
 249
 250 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
 251   <para>
 252     The XlibRGB set of functions is a port of the GdkRGB library to
 253     use plain Xlib and X drawables.  You can use these functions to
 254     render RGB buffers into drawables very quickly with high-quality
 255     dithering.
 256   </para>
 257
 258
 259 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
 260 Functions for rendering RGB buffers to X drawables.
 261
 262
 263 <!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
 264   <para>
 265     Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
 266   </para>
 267
 268 @obj: A GTK+ object.
 269
 270 <!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### -->
 271 <para>
 272
 273 </para>
 274
 275
 276 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
 277 Rendering a pixbuf to an X drawable.
 278
 279
 280 <!-- ##### FUNCTION gdk_pixbuf_finalize ##### -->
 281 <para>
 282
 283 </para>
 284
 285 @pixbuf: <!--
 286 Local variables:
 287 mode: sgml
 288 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 289 End:
 290 -->
 291
 292 <!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
 293 Rendering a pixbuf to a GDK drawable.
 294
 295
 296 <!-- ##### FUNCTION gdk_pixbuf_set_last_unref_handler ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @pixbuf:
 302 @last_unref_fn:
 303 @last_unref_fn_data:
 304
 305 <!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
 306   <para>
 307     Determines whether the <link
 308     linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
 309     translate the pixbuf from its logical origin in item-relative
 310     coordinates.
 311   </para>
 312
 313
 314 <!-- ##### ARG GnomeCanvasPixbuf:width_in_pixels ##### -->
 315   <para>
 316     If this argument is %TRUE, then the width of the pixbuf will be
 317     considered to be in pixels, that is, it will not be visually
 318     scaled even if the item's affine transformation changes.  If this
 319     is %FALSE, then the width of the pixbuf will be considered to be
 320     in canvas units, and so will be scaled normally by affine
 321     transformations.  The default is %FALSE.
 322   </para>
 323
 324
 325 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
 326   <para>
 327     In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
 328     package provides a small library that lets Xlib-only applications
 329     use #GdkPixbuf structures and render them to X drawables.  The
 330     functions in this section are used to initialize the &gdk-pixbuf;
 331     Xlib library.  This library must be initialized near the beginning
 332     or the program or before calling any of the other &gdk-pixbuf;
 333     Xlib functions; it cannot be initialized automatically since
 334     Xlib-only applications do not call gdk_rgb_init() like GNOME
 335     applications do.
 336   </para>
 337
 338
 339 <!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @pixbuf:
 345 @Returns:
 346
 347 <!-- ##### ARG GnomeCanvasPixbuf:height_in_pixels ##### -->
 348   <para>
 349     Works in the same way as the <link
 350     linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 351     argument.  The default is %FALSE.
 352   </para>
 353
 354
 355 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
 356 <para>
 357
 358 </para>
 359
 360
 361 <!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
 362   <para>
 363     Determines whether the <link
 364     linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
 365     into account when scaling the pixbuf item.  If this argument is
 366     %FALSE, then the width value of the pixbuf will be used instead.
 367     This argument is %FALSE by default.
 368   </para>
 369
 370
 371 <!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
 372 <para>
 373
 374 </para>
 375
 376 @pixbuf:
 377 @drawable:
 378 @src_x:
 379 @src_y:
 380 @dest_x:
 381 @dest_y:
 382 @width:
 383 @height:
 384 @alpha_mode:
 385 @alpha_threshold:
 386 @dither:
 387 @x_dither:
 388 @y_dither:
 389
 390 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
 391 &gdk-pixbuf; Xlib initialization
 392
 393
 394 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
 395 Getting parts of an X drawable's image data into a pixbuf.
 396
 397
 398 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
 399 XlibRGB
 400
 401
 402 <!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
 403 <para>
 404
 405 </para>
 406
 407
 408 <!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
 409   <para>
 410     Indicates the height the pixbuf will be scaled to.  This argument
 411     will only be used if the <link
 412     linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
 413     is %TRUE.  Works in the same way as the <link
 414     linkend="GnomeCanvasPixbuf--width">width</link> argument.
 415   </para>
 416
 417
 418 <!-- ##### SECTION ./tmpl/from-drawables.sgml:See_Also ##### -->
 419   <para>
 420     gdk_image_get().
 421   </para>
 422
 423
 424 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
 425 <para>
 426
 427 </para>
 428
 429
 430 <!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
 431 <para>
 432
 433 </para>
 434
 435
 436 <!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
 437 Rendering
 438
 439
 440 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
 441 GnomeCanvasPixbuf
 442
 443
 444 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
 445   <para>
 446     Casts a #GtkObject to a #GdkPixbufLoader.
 447   </para>
 448
 449 @obj: A GTK+ object.
 450
 451 <!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
 452   <para>
 453     Determines whether the <link
 454     linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
 455     translate the pixbuf from its logical origin in item-relative
 456     coordinates.  Works in the same way as the <link
 457     linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument.  The
 458     default is %FALSE.
 459   </para>
 460
 461
 462 <!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
 463   <para>
 464     The &gdk-pixbuf; library provides several convenience functions to
 465     render pixbufs to GDK drawables.  It uses the GdkRGB to render the
 466     image data.
 467   </para>
 468
 469   <para>
 470     At this point there is not a standard alpha channel extension for
 471     the X Window System, so it is not possible to use full opacity
 472     information when painting images to arbitrary drawables.  The
 473     &gdk-pixbuf; convenience functions will threshold the opacity
 474     information to create a bi-level clipping mask (black and white),
 475     and use that to draw the image onto a drawable.
 476   </para>
 477
 478   <important>
 479     <para>
 480       Since these functions use GdkRGB for rendering, you must
 481       initialize GdkRGB before using any of them.  You can do this by
 482       calling gdk_rgb_init() near the beginning of your program.
 483     </para>
 484   </important>
 485
 486
 487 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
 488 Getting parts of a drawable's image data into a pixbuf.
 489
 490
 491 <!-- ##### FUNCTION gdk_pixbuf_render_threshold_alpha ##### -->
 492 <para>
 493
 494 </para>
 495
 496 @pixbuf:
 497 @bitmap:
 498 @src_x:
 499 @src_y:
 500 @dest_x:
 501 @dest_y:
 502 @width:
 503 @height:
 504 @alpha_threshold:
 505
 506 <!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
 507 <para>
 508
 509 </para>
 510
 511
 512 <!-- ##### STRUCT GdkPixbufClass ##### -->
 513 <para>
 514
 515 </para>
 516
 517
 518 <!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Long_Description ##### -->
 519 <para>
 520
 521 </para>
 522
 523
 524 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
 525   <para>
 526     This canvas item displays #GdkPixbuf images.  It handles full
 527     affine transformations in both GDK and antialiased modes, and also
 528     supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
 529     url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
 530     translation semantics for absolute pixel values.
 531   </para>
 532
 533   <para>
 534     #GdkPixbuf structures may be shared among different pixbuf canvas
 535     items; the pixbuf item uses #GdkPixbuf's reference counting
 536     functions for this.
 537   </para>
 538
 539   <refsect2>
 540     <title>Custom Scaling and Translation</title>
 541
 542     <para>
 543       In addition to the normal affine transformations supported by
 544       canvas items, the #GnomeCanvasPixbuf item supports independent
 545       object arguments for scaling and translation.  This is useful
 546       for explicitly setting a size to which the pixbuf's image will
 547       be scaled, and for specifying translation offsets that take
 548       place in the item's local coordinate system.
 549     </para>
 550
 551     <para>
 552       By default, the pixbuf canvas item will attain the size in units
 553       of the #GdkPixbuf it contains.  If a #GnomeCanvasPixbuf is
 554       configured to use a #GdkPixbuf that has a size of 300 by 200
 555       pixels, then the pixbuf item will automatically obtain a size of
 556       300 by 200 units in the item's local coordinate system.  If the
 557       item is transformed with a scaling transformation of (0.5, 2.0),
 558       then the final image size will be of 150 by 400 pixels.
 559     </para>
 560
 561     <para>
 562       To set custom width and height values, you must set the <link
 563       linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
 564       linkend="GnomeCanvasPixbuf--height-set">height_set</link>
 565       arguments to %TRUE, and then set the <link
 566       linkend="GnomeCanvasPixbuf--width">width</link> or <link
 567       linkend="GnomeCanvasPixbuf--height">height</link> arguments to
 568       the desired values.  The former two arguments control whether
 569       the latter two are used when computing the final image's size;
 570       they are both %FALSE by default so that the pixbuf item will
 571       attain a size in units equal to the size in pixels of the
 572       #GdkPixbuf that the item contains.
 573     </para>
 574
 575     <para>
 576       The custom translation offsets are controlled by the <link
 577       linkend="GnomeCanvasPixbuf--x">x</link> and <link
 578       linkend="GnomeCanvasPixbuf--y">y</link> arguments.  The logical
 579       upper-left vertex of the image will be translated by the
 580       specified distance, aligned with the item's local coordinate
 581       system.
 582     </para>
 583   </refsect2>
 584
 585   <refsect2>
 586     <title>Absolute Pixel Scaling and Translation</title>
 587
 588     <para>
 589       The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
 590       Graphics</ulink> specification (SVG) of the <ulink
 591       url="http://www.w3.org">World Wide Web Consortium</ulink> also
 592       allows images to be translated and scaled by absolute pixel
 593       values that are independent of an item's normal affine
 594       transformation.
 595     </para>
 596
 597     <para>
 598       Normally, the pixbuf item's translation and scaling arguments
 599       are interpreted in units, so they will be modified by the item's
 600       affine transformation.  The <link
 601       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
 602       <link
 603       linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
 604       <link
 605       linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
 606       <link
 607       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 608       object arguments can be used to modify this behavior.  If one of
 609       these arguments is %TRUE, then the corresponding scaling or
 610       translation value will not be affected lengthwise by the pixbuf
 611       item's affine transformation.
 612     </para>
 613
 614     <para>
 615       For example, consider a pixbuf item whose size is (300, 200).
 616       If the item is modified with a scaling transformation of (0.5,
 617       2.0) but the <link
 618       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 619       is set to %TRUE, then the item will appear to be (300, 400)
 620       pixels in size.  This means that in this case the item's affine
 621       transformation only applies to the height value, while the width
 622       value is kept in absolute pixels.
 623     </para>
 624
 625     <para>
 626       Likewise, consider a pixbuf item whose (<link
 627       linkend="GnomeCanvasPixbuf--x">x</link>, <link
 628       linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
 629       (30, 40).  If the item is then modified by the same scaling
 630       transformation of (0.5, 2.0) but the <link
 631       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 632       argument is set to %TRUE, then the image's upper-left corner
 633       will appear to be at position (15, 40).  In this case, the
 634       affine transformation is applied only to the x offset, while the
 635       y offset is kept in absolute pixels.
 636     </para>
 637
 638     <para>
 639       In short, these arguments control whether a particular dimension
 640       of a pixbuf item is scaled or not in the normal way by the
 641       item's affine transformation.
 642     </para>
 643   </refsect2>
 644
 645   <refsect2>
 646     <title>Resource Management</title>
 647
 648     <para>
 649       When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
 650       item will use by setting the <link
 651       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
 652       reference count will be added to that #GdkPixbuf structure.
 653       When the pixbuf item no longer needs the #GdkPixbuf structure,
 654       such as when the item is destroyed or when a new pixbuf
 655       structure is passed to it, then the old #GdkPixbuf structure
 656       will be automatically unreferenced.
 657     </para>
 658
 659     <para>
 660       This means that if an application just needs to load a pixbuf
 661       image and set it into a pixbuf canvas item, it can do the
 662       following to &lsquo;forget&rsquo; about the pixbuf structure:
 663
 664       <programlisting>
 665         GdkPixbuf *pixbuf;
 666         GnomeCanvasItem *item;
 667
 668         pixbuf = gdk_pixbuf_new_from_file ("foo.png");
 669         g_assert (pixbuf != NULL);
 670
 671         item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
 672                                       gnome_canvas_pixbuf_get_type (),
 673                                       "pixbuf", pixbuf,
 674                                       NULL);
 675         gdk_pixbuf_unref (pixbuf);
 676       </programlisting>
 677     </para>
 678
 679     <para>
 680       After this happens, the reference count of the pixbuf structure
 681       will be 1:  the gdk_pixbuf_new_from_file() function creates it
 682       with a reference count of 1, then setting the <link
 683       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
 684       the #GnomeCanvasPixbuf item increases it to 2, and then it is
 685       decremented to 1 by the call to gdk_pixbuf_unref().  When the
 686       canvas item is destroyed, it will automatically unreference the
 687       pixbuf structure again, causing its reference count to drop to
 688       zero and thus be freed.
 689     </para>
 690   </refsect2>
 691
 692
 693 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
 694 Xlib Rendering
 695
 696
 697 <!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
 698   <para>
 699     Determines whether the <link
 700     linkend="GnomeCanvasPixbuf--height">height</link> argument is
 701     taken into account when scaling the pixbuf item.  Works in the
 702     same way as the <link
 703     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
 704     The default is %FALSE.
 705   </para>
 706
 707
 708 <!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Title ##### -->
 709 gdk-pixbuf-io
 710
 711