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:y_pixels ##### -->
 182 <para>
 183
 184 </para>
 185
 186
 187 <!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
 188   <para>
 189     Contains a pointer to a #GdkPixbuf structure that will be used by
 190     the pixbuf canvas item as an image source.  When a pixbuf is set
 191     its reference count is incremented; if the pixbuf item kept a
 192     pointer to another #GdkPixbuf structure, the reference count of
 193     this structure will be decremented.  Also, the GdkPixbuf's
 194     reference count will automatically be decremented when the
 195     #GnomeCanvasPixbuf item is destroyed.  When a pixbuf is queried, a
 196     reference count will not be added to the return value; you must do
 197     this yourself if you intend to keep the pixbuf structure around.
 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 <!-- ##### FUNCTION gdk_pixbuf_new_subpixbuf ##### -->
 399 <para>
 400
 401 </para>
 402
 403 @src_pixbuf:
 404 @src_x:
 405 @src_y:
 406 @width:
 407 @height:
 408 @Returns:
 409
 410 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
 411 XlibRGB
 412
 413
 414 <!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
 415 <para>
 416
 417 </para>
 418
 419
 420 <!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
 421   <para>
 422     Indicates the height the pixbuf will be scaled to.  This argument
 423     will only be used if the <link
 424     linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
 425     is %TRUE.  Works in the same way as the <link
 426     linkend="GnomeCanvasPixbuf--width">width</link> argument.
 427   </para>
 428
 429
 430 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
 431 <para>
 432
 433 </para>
 434
 435
 436 <!-- ##### SECTION ./tmpl/from-drawables.sgml:See_Also ##### -->
 437   <para>
 438     gdk_image_get().
 439   </para>
 440
 441
 442 <!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
 443 <para>
 444
 445 </para>
 446
 447
 448 <!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
 449 Rendering
 450
 451
 452 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
 453 GnomeCanvasPixbuf
 454
 455
 456 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
 457   <para>
 458     Casts a #GtkObject to a #GdkPixbufLoader.
 459   </para>
 460
 461 @obj: A GTK+ object.
 462
 463 <!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
 464   <para>
 465     Determines whether the <link
 466     linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
 467     translate the pixbuf from its logical origin in item-relative
 468     coordinates.  Works in the same way as the <link
 469     linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument.  The
 470     default is %FALSE.
 471   </para>
 472
 473
 474 <!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
 475   <para>
 476     The &gdk-pixbuf; library provides several convenience functions to
 477     render pixbufs to GDK drawables.  It uses the GdkRGB to render the
 478     image data.
 479   </para>
 480
 481   <para>
 482     At this point there is not a standard alpha channel extension for
 483     the X Window System, so it is not possible to use full opacity
 484     information when painting images to arbitrary drawables.  The
 485     &gdk-pixbuf; convenience functions will threshold the opacity
 486     information to create a bi-level clipping mask (black and white),
 487     and use that to draw the image onto a drawable.
 488   </para>
 489
 490   <important>
 491     <para>
 492       Since these functions use GdkRGB for rendering, you must
 493       initialize GdkRGB before using any of them.  You can do this by
 494       calling gdk_rgb_init() near the beginning of your program.
 495     </para>
 496   </important>
 497
 498
 499 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
 500 Getting parts of a drawable's image data into a pixbuf.
 501
 502
 503 <!-- ##### FUNCTION gdk_pixbuf_render_threshold_alpha ##### -->
 504 <para>
 505
 506 </para>
 507
 508 @pixbuf:
 509 @bitmap:
 510 @src_x:
 511 @src_y:
 512 @dest_x:
 513 @dest_y:
 514 @width:
 515 @height:
 516 @alpha_threshold:
 517
 518 <!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
 519 <para>
 520
 521 </para>
 522
 523
 524 <!-- ##### STRUCT GdkPixbufClass ##### -->
 525 <para>
 526
 527 </para>
 528
 529
 530 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
 531   <para>
 532     This canvas item displays #GdkPixbuf images.  It handles full
 533     affine transformations in both GDK and antialiased modes, and also
 534     supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
 535     url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
 536     translation semantics for absolute pixel values.
 537   </para>
 538
 539   <para>
 540     #GdkPixbuf structures may be shared among different pixbuf canvas
 541     items; the pixbuf item uses #GdkPixbuf's reference counting
 542     functions for this.
 543   </para>
 544
 545   <refsect2>
 546     <title>Custom Scaling and Translation</title>
 547
 548     <para>
 549       In addition to the normal affine transformations supported by
 550       canvas items, the #GnomeCanvasPixbuf item supports independent
 551       object arguments for scaling and translation.  This is useful
 552       for explicitly setting a size to which the pixbuf's image will
 553       be scaled, and for specifying translation offsets that take
 554       place in the item's local coordinate system.
 555     </para>
 556
 557     <para>
 558       By default, the pixbuf canvas item will attain the size in units
 559       of the #GdkPixbuf it contains.  If a #GnomeCanvasPixbuf is
 560       configured to use a #GdkPixbuf that has a size of 300 by 200
 561       pixels, then the pixbuf item will automatically obtain a size of
 562       300 by 200 units in the item's local coordinate system.  If the
 563       item is transformed with a scaling transformation of (0.5, 2.0),
 564       then the final image size will be of 150 by 400 pixels.
 565     </para>
 566
 567     <para>
 568       To set custom width and height values, you must set the <link
 569       linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
 570       linkend="GnomeCanvasPixbuf--height-set">height_set</link>
 571       arguments to %TRUE, and then set the <link
 572       linkend="GnomeCanvasPixbuf--width">width</link> or <link
 573       linkend="GnomeCanvasPixbuf--height">height</link> arguments to
 574       the desired values.  The former two arguments control whether
 575       the latter two are used when computing the final image's size;
 576       they are both %FALSE by default so that the pixbuf item will
 577       attain a size in units equal to the size in pixels of the
 578       #GdkPixbuf that the item contains.
 579     </para>
 580
 581     <para>
 582       The custom translation offsets are controlled by the <link
 583       linkend="GnomeCanvasPixbuf--x">x</link> and <link
 584       linkend="GnomeCanvasPixbuf--y">y</link> arguments.  The logical
 585       upper-left vertex of the image will be translated by the
 586       specified distance, aligned with the item's local coordinate
 587       system.
 588     </para>
 589   </refsect2>
 590
 591   <refsect2>
 592     <title>Absolute Pixel Scaling and Translation</title>
 593
 594     <para>
 595       The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
 596       Graphics</ulink> specification (SVG) of the <ulink
 597       url="http://www.w3.org">World Wide Web Consortium</ulink> also
 598       allows images to be translated and scaled by absolute pixel
 599       values that are independent of an item's normal affine
 600       transformation.
 601     </para>
 602
 603     <para>
 604       Normally, the pixbuf item's translation and scaling arguments
 605       are interpreted in units, so they will be modified by the item's
 606       affine transformation.  The <link
 607       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
 608       <link
 609       linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
 610       <link
 611       linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
 612       <link
 613       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 614       object arguments can be used to modify this behavior.  If one of
 615       these arguments is %TRUE, then the corresponding scaling or
 616       translation value will not be affected lengthwise by the pixbuf
 617       item's affine transformation.
 618     </para>
 619
 620     <para>
 621       For example, consider a pixbuf item whose size is (300, 200).
 622       If the item is modified with a scaling transformation of (0.5,
 623       2.0) but the <link
 624       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 625       is set to %TRUE, then the item will appear to be (300, 400)
 626       pixels in size.  This means that in this case the item's affine
 627       transformation only applies to the height value, while the width
 628       value is kept in absolute pixels.
 629     </para>
 630
 631     <para>
 632       Likewise, consider a pixbuf item whose (<link
 633       linkend="GnomeCanvasPixbuf--x">x</link>, <link
 634       linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
 635       (30, 40).  If the item is then modified by the same scaling
 636       transformation of (0.5, 2.0) but the <link
 637       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 638       argument is set to %TRUE, then the image's upper-left corner
 639       will appear to be at position (15, 40).  In this case, the
 640       affine transformation is applied only to the x offset, while the
 641       y offset is kept in absolute pixels.
 642     </para>
 643
 644     <para>
 645       In short, these arguments control whether a particular dimension
 646       of a pixbuf item is scaled or not in the normal way by the
 647       item's affine transformation.
 648     </para>
 649   </refsect2>
 650
 651   <refsect2>
 652     <title>Resource Management</title>
 653
 654     <para>
 655       When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
 656       item will use by setting the <link
 657       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
 658       reference count will be added to that #GdkPixbuf structure.
 659       When the pixbuf item no longer needs the #GdkPixbuf structure,
 660       such as when the item is destroyed or when a new pixbuf
 661       structure is passed to it, then the old #GdkPixbuf structure
 662       will be automatically unreferenced.
 663     </para>
 664
 665     <para>
 666       This means that if an application just needs to load a pixbuf
 667       image and set it into a pixbuf canvas item, it can do the
 668       following to &lsquo;forget&rsquo; about the pixbuf structure:
 669
 670       <programlisting>
 671         GdkPixbuf *pixbuf;
 672         GnomeCanvasItem *item;
 673
 674         pixbuf = gdk_pixbuf_new_from_file ("foo.png");
 675         g_assert (pixbuf != NULL);
 676
 677         item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
 678                                       gnome_canvas_pixbuf_get_type (),
 679                                       "pixbuf", pixbuf,
 680                                       NULL);
 681         gdk_pixbuf_unref (pixbuf);
 682       </programlisting>
 683     </para>
 684
 685     <para>
 686       After this happens, the reference count of the pixbuf structure
 687       will be 1:  the gdk_pixbuf_new_from_file() function creates it
 688       with a reference count of 1, then setting the <link
 689       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
 690       the #GnomeCanvasPixbuf item increases it to 2, and then it is
 691       decremented to 1 by the call to gdk_pixbuf_unref().  When the
 692       canvas item is destroyed, it will automatically unreference the
 693       pixbuf structure again, causing its reference count to drop to
 694       zero and thus be freed.
 695     </para>
 696   </refsect2>
 697
 698
 699 <!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Long_Description ##### -->
 700 <para>
 701
 702 </para>
 703
 704
 705 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
 706 Xlib Rendering
 707
 708
 709 <!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
 710   <para>
 711     Determines whether the <link
 712     linkend="GnomeCanvasPixbuf--height">height</link> argument is
 713     taken into account when scaling the pixbuf item.  Works in the
 714     same way as the <link
 715     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
 716     The default is %FALSE.
 717   </para>
 718
 719
 720 <!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:Title ##### -->
 721 gdk-pixbuf-io
 722
 723