Pileus Git - ~andy/gtk/blob - gtk/gtkimage.c

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  21  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GTK+ Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include <math.h>
  30 #include <string.h>
  31
  32 #include "gtkcontainer.h"
  33 #include "gtkiconhelperprivate.h"
  34 #include "gtkimageprivate.h"
  35 #include "gtkiconfactory.h"
  36 #include "gtkstock.h"
  37 #include "gtkicontheme.h"
  38 #include "gtksizerequest.h"
  39 #include "gtkintl.h"
  40 #include "gtkprivate.h"
  41 #include "gtktypebuiltins.h"
  42
  43 #include "a11y/gtkimageaccessible.h"
  44
  45 /**
  46  * SECTION:gtkimage
  47  * @Short_description: A widget displaying an image
  48  * @Title: GtkImage
  49  * @See_also:#GdkPixbuf
  50  *
  51  * The #GtkImage widget displays an image. Various kinds of object
  52  * can be displayed as an image; most typically, you would load a
  53  * #GdkPixbuf ("pixel buffer") from a file, and then display that.
  54  * There's a convenience function to do this, gtk_image_new_from_file(),
  55  * used as follows:
  56  * <informalexample><programlisting>
  57  *   GtkWidget *image;
  58  *   image = gtk_image_new_from_file ("myfile.png");
  59  * </programlisting></informalexample>
  60  * If the file isn't loaded successfully, the image will contain a
  61  * "broken image" icon similar to that used in many web browsers.
  62  * If you want to handle errors in loading the file yourself,
  63  * for example by displaying an error message, then load the image with
  64  * gdk_pixbuf_new_from_file(), then create the #GtkImage with
  65  * gtk_image_new_from_pixbuf().
  66  *
  67  * The image file may contain an animation, if so the #GtkImage will
  68  * display an animation (#GdkPixbufAnimation) instead of a static image.
  69  *
  70  * #GtkImage is a subclass of #GtkMisc, which implies that you can
  71  * align it (center, left, right) and add padding to it, using
  72  * #GtkMisc methods.
  73  *
  74  * #GtkImage is a "no window" widget (has no #GdkWindow of its own),
  75  * so by default does not receive events. If you want to receive events
  76  * on the image, such as button clicks, place the image inside a
  77  * #GtkEventBox, then connect to the event signals on the event box.
  78  * <example>
  79  * <title>Handling button press events on a
  80  * <structname>GtkImage</structname>.</title>
  81  * <programlisting>
  82  *   static gboolean
  83  *   button_press_callback (GtkWidget      *event_box,
  84  *                          GdkEventButton *event,
  85  *                          gpointer        data)
  86  *   {
  87  *     g_print ("Event box clicked at coordinates &percnt;f,&percnt;f\n",
  88  *              event->x, event->y);
  89  *
  90  *     /<!---->* Returning TRUE means we handled the event, so the signal
  91  *      * emission should be stopped (don't call any further
  92  *      * callbacks that may be connected). Return FALSE
  93  *      * to continue invoking callbacks.
  94  *      *<!---->/
  95  *     return TRUE;
  96  *   }
  97  *
  98  *   static GtkWidget*
  99  *   create_image (void)
 100  *   {
 101  *     GtkWidget *image;
 102  *     GtkWidget *event_box;
 103  *
 104  *     image = gtk_image_new_from_file ("myfile.png");
 105  *
 106  *     event_box = gtk_event_box_new (<!-- -->);
 107  *
 108  *     gtk_container_add (GTK_CONTAINER (event_box), image);
 109  *
 110  *     g_signal_connect (G_OBJECT (event_box),
 111  *                       "button_press_event",
 112  *                       G_CALLBACK (button_press_callback),
 113  *                       image);
 114  *
 115  *     return image;
 116  *   }
 117  * </programlisting>
 118  * </example>
 119  *
 120  * When handling events on the event box, keep in mind that coordinates
 121  * in the image may be different from event box coordinates due to
 122  * the alignment and padding settings on the image (see #GtkMisc).
 123  * The simplest way to solve this is to set the alignment to 0.0
 124  * (left/top), and set the padding to zero. Then the origin of
 125  * the image will be the same as the origin of the event box.
 126  *
 127  * Sometimes an application will want to avoid depending on external data
 128  * files, such as image files. GTK+ comes with a program to avoid this,
 129  * called <application>gdk-pixbuf-csource</application>. This program
 130  * allows you to convert an image into a C variable declaration, which
 131  * can then be loaded into a #GdkPixbuf using
 132  * gdk_pixbuf_new_from_inline().
 133  */
 134
 135
 136 struct _GtkImagePrivate
 137 {
 138   GtkIconHelper *icon_helper;
 139
 140   gint animation_timeout;
 141   GdkPixbufAnimationIter *animation_iter;
 142
 143   gchar                *filename;       /* Only used with GTK_IMAGE_ANIMATION, GTK_IMAGE_PIXBUF */
 144 };
 145
 146
 147 #define DEFAULT_ICON_SIZE GTK_ICON_SIZE_BUTTON
 148 static gint gtk_image_draw                 (GtkWidget    *widget,
 149                                             cairo_t      *cr);
 150 static void gtk_image_unmap                (GtkWidget    *widget);
 151 static void gtk_image_unrealize            (GtkWidget    *widget);
 152 static void gtk_image_get_preferred_width  (GtkWidget    *widget,
 153                                             gint         *minimum,
 154                                             gint         *natural);
 155 static void gtk_image_get_preferred_height (GtkWidget    *widget,
 156                                             gint         *minimum,
 157                                             gint         *natural);
 158
 159 static void gtk_image_style_updated        (GtkWidget    *widget);
 160 static void gtk_image_screen_changed       (GtkWidget    *widget,
 161                                             GdkScreen    *prev_screen);
 162 static void gtk_image_destroy              (GtkWidget    *widget);
 163 static void gtk_image_reset                (GtkImage     *image);
 164
 165 static void gtk_image_set_property         (GObject      *object,
 166                                             guint         prop_id,
 167                                             const GValue *value,
 168                                             GParamSpec   *pspec);
 169 static void gtk_image_get_property         (GObject      *object,
 170                                             guint         prop_id,
 171                                             GValue       *value,
 172                                             GParamSpec   *pspec);
 173
 174 static void icon_theme_changed             (GtkImage     *image);
 175
 176 enum
 177 {
 178   PROP_0,
 179   PROP_PIXBUF,
 180   PROP_FILE,
 181   PROP_STOCK,
 182   PROP_ICON_SET,
 183   PROP_ICON_SIZE,
 184   PROP_PIXEL_SIZE,
 185   PROP_PIXBUF_ANIMATION,
 186   PROP_ICON_NAME,
 187   PROP_STORAGE_TYPE,
 188   PROP_GICON,
 189   PROP_USE_FALLBACK
 190 };
 191
 192 G_DEFINE_TYPE (GtkImage, gtk_image, GTK_TYPE_MISC)
 193
 194 static void
 195 gtk_image_class_init (GtkImageClass *class)
 196 {
 197   GObjectClass *gobject_class;
 198   GtkWidgetClass *widget_class;
 199
 200   gobject_class = G_OBJECT_CLASS (class);
 201
 202   gobject_class->set_property = gtk_image_set_property;
 203   gobject_class->get_property = gtk_image_get_property;
 204
 205   widget_class = GTK_WIDGET_CLASS (class);
 206   widget_class->draw = gtk_image_draw;
 207   widget_class->destroy = gtk_image_destroy;
 208   widget_class->get_preferred_width = gtk_image_get_preferred_width;
 209   widget_class->get_preferred_height = gtk_image_get_preferred_height;
 210   widget_class->unmap = gtk_image_unmap;
 211   widget_class->unrealize = gtk_image_unrealize;
 212   widget_class->style_updated = gtk_image_style_updated;
 213   widget_class->screen_changed = gtk_image_screen_changed;
 214
 215   g_object_class_install_property (gobject_class,
 216                                    PROP_PIXBUF,
 217                                    g_param_spec_object ("pixbuf",
 218                                                         P_("Pixbuf"),
 219                                                         P_("A GdkPixbuf to display"),
 220                                                         GDK_TYPE_PIXBUF,
 221                                                         GTK_PARAM_READWRITE));
 222
 223   g_object_class_install_property (gobject_class,
 224                                    PROP_FILE,
 225                                    g_param_spec_string ("file",
 226                                                         P_("Filename"),
 227                                                         P_("Filename to load and display"),
 228                                                         NULL,
 229                                                         GTK_PARAM_READWRITE));
 230
 231
 232   g_object_class_install_property (gobject_class,
 233                                    PROP_STOCK,
 234                                    g_param_spec_string ("stock",
 235                                                         P_("Stock ID"),
 236                                                         P_("Stock ID for a stock image to display"),
 237                                                         NULL,
 238                                                         GTK_PARAM_READWRITE));
 239
 240   g_object_class_install_property (gobject_class,
 241                                    PROP_ICON_SET,
 242                                    g_param_spec_boxed ("icon-set",
 243                                                        P_("Icon set"),
 244                                                        P_("Icon set to display"),
 245                                                        GTK_TYPE_ICON_SET,
 246                                                        GTK_PARAM_READWRITE));
 247
 248   g_object_class_install_property (gobject_class,
 249                                    PROP_ICON_SIZE,
 250                                    g_param_spec_int ("icon-size",
 251                                                      P_("Icon size"),
 252                                                      P_("Symbolic size to use for stock icon, icon set or named icon"),
 253                                                      0, G_MAXINT,
 254                                                      DEFAULT_ICON_SIZE,
 255                                                      GTK_PARAM_READWRITE));
 256   /**
 257    * GtkImage:pixel-size:
 258    *
 259    * The "pixel-size" property can be used to specify a fixed size
 260    * overriding the #GtkImage:icon-size property for images of type
 261    * %GTK_IMAGE_ICON_NAME.
 262    *
 263    * Since: 2.6
 264    */
 265   g_object_class_install_property (gobject_class,
 266                                    PROP_PIXEL_SIZE,
 267                                    g_param_spec_int ("pixel-size",
 268                                                      P_("Pixel size"),
 269                                                      P_("Pixel size to use for named icon"),
 270                                                      -1, G_MAXINT,
 271                                                      -1,
 272                                                      GTK_PARAM_READWRITE));
 273
 274   g_object_class_install_property (gobject_class,
 275                                    PROP_PIXBUF_ANIMATION,
 276                                    g_param_spec_object ("pixbuf-animation",
 277                                                         P_("Animation"),
 278                                                         P_("GdkPixbufAnimation to display"),
 279                                                         GDK_TYPE_PIXBUF_ANIMATION,
 280                                                         GTK_PARAM_READWRITE));
 281
 282   /**
 283    * GtkImage:icon-name:
 284    *
 285    * The name of the icon in the icon theme. If the icon theme is
 286    * changed, the image will be updated automatically.
 287    *
 288    * Since: 2.6
 289    */
 290   g_object_class_install_property (gobject_class,
 291                                    PROP_ICON_NAME,
 292                                    g_param_spec_string ("icon-name",
 293                                                         P_("Icon Name"),
 294                                                         P_("The name of the icon from the icon theme"),
 295                                                         NULL,
 296                                                         GTK_PARAM_READWRITE));
 297
 298   /**
 299    * GtkImage:gicon:
 300    *
 301    * The GIcon displayed in the GtkImage. For themed icons,
 302    * If the icon theme is changed, the image will be updated
 303    * automatically.
 304    *
 305    * Since: 2.14
 306    */
 307   g_object_class_install_property (gobject_class,
 308                                    PROP_GICON,
 309                                    g_param_spec_object ("gicon",
 310                                                         P_("Icon"),
 311                                                         P_("The GIcon being displayed"),
 312                                                         G_TYPE_ICON,
 313                                                         GTK_PARAM_READWRITE));
 314
 315   g_object_class_install_property (gobject_class,
 316                                    PROP_STORAGE_TYPE,
 317                                    g_param_spec_enum ("storage-type",
 318                                                       P_("Storage type"),
 319                                                       P_("The representation being used for image data"),
 320                                                       GTK_TYPE_IMAGE_TYPE,
 321                                                       GTK_IMAGE_EMPTY,
 322                                                       GTK_PARAM_READABLE));
 323
 324   /**
 325    * GtkImage:use-fallback:
 326    *
 327    * Whether the icon displayed in the GtkImage will use
 328    * standard icon names fallback. The value of this property
 329    * is only relevant for images of type %GTK_IMAGE_ICON_NAME
 330    * and %GTK_IMAGE_GICON.
 331    *
 332    * Since: 3.0
 333    */
 334   g_object_class_install_property (gobject_class,
 335                                    PROP_USE_FALLBACK,
 336                                    g_param_spec_boolean ("use-fallback",
 337                                                          P_("Use Fallback"),
 338                                                          P_("Whether to use icon names fallback"),
 339                                                          FALSE,
 340                                                          GTK_PARAM_READWRITE));
 341
 342   g_type_class_add_private (class, sizeof (GtkImagePrivate));
 343
 344   gtk_widget_class_set_accessible_type (widget_class, GTK_TYPE_IMAGE_ACCESSIBLE);
 345 }
 346
 347 static void
 348 gtk_image_init (GtkImage *image)
 349 {
 350   GtkImagePrivate *priv;
 351
 352   image->priv = G_TYPE_INSTANCE_GET_PRIVATE (image,
 353                                              GTK_TYPE_IMAGE,
 354                                              GtkImagePrivate);
 355   priv = image->priv;
 356
 357   gtk_widget_set_has_window (GTK_WIDGET (image), FALSE);
 358   priv->icon_helper = _gtk_icon_helper_new ();
 359
 360   priv->filename = NULL;
 361 }
 362
 363 static void
 364 gtk_image_destroy (GtkWidget *widget)
 365 {
 366   GtkImage *image = GTK_IMAGE (widget);
 367
 368   g_clear_object (&image->priv->icon_helper);
 369
 370   GTK_WIDGET_CLASS (gtk_image_parent_class)->destroy (widget);
 371 }
 372
 373 static void
 374 gtk_image_set_property (GObject      *object,
 375                         guint         prop_id,
 376                         const GValue *value,
 377                         GParamSpec   *pspec)
 378 {
 379   GtkImage *image = GTK_IMAGE (object);
 380   GtkImagePrivate *priv = image->priv;
 381   GtkIconSize icon_size = _gtk_icon_helper_get_icon_size (priv->icon_helper);
 382
 383   switch (prop_id)
 384     {
 385     case PROP_PIXBUF:
 386       gtk_image_set_from_pixbuf (image,
 387                                  g_value_get_object (value));
 388       break;
 389     case PROP_FILE:
 390       gtk_image_set_from_file (image, g_value_get_string (value));
 391       break;
 392     case PROP_STOCK:
 393       gtk_image_set_from_stock (image, g_value_get_string (value),
 394                                 icon_size);
 395       break;
 396     case PROP_ICON_SET:
 397       gtk_image_set_from_icon_set (image, g_value_get_boxed (value),
 398                                    icon_size);
 399       break;
 400     case PROP_ICON_SIZE:
 401       _gtk_icon_helper_set_icon_size (priv->icon_helper, g_value_get_int (value));
 402       break;
 403     case PROP_PIXEL_SIZE:
 404       gtk_image_set_pixel_size (image, g_value_get_int (value));
 405       break;
 406     case PROP_PIXBUF_ANIMATION:
 407       gtk_image_set_from_animation (image,
 408                                     g_value_get_object (value));
 409       break;
 410     case PROP_ICON_NAME:
 411       gtk_image_set_from_icon_name (image, g_value_get_string (value),
 412                                     icon_size);
 413       break;
 414     case PROP_GICON:
 415       gtk_image_set_from_gicon (image, g_value_get_object (value),
 416                                 icon_size);
 417       break;
 418
 419     case PROP_USE_FALLBACK:
 420       _gtk_icon_helper_set_use_fallback (priv->icon_helper, g_value_get_boolean (value));
 421       break;
 422
 423     default:
 424       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 425       break;
 426     }
 427 }
 428
 429 static void
 430 gtk_image_get_property (GObject     *object,
 431                         guint        prop_id,
 432                         GValue      *value,
 433                         GParamSpec  *pspec)
 434 {
 435   GtkImage *image = GTK_IMAGE (object);
 436   GtkImagePrivate *priv = image->priv;
 437
 438   switch (prop_id)
 439     {
 440     case PROP_PIXBUF:
 441       g_value_set_object (value, _gtk_icon_helper_peek_pixbuf (priv->icon_helper));
 442       break;
 443     case PROP_FILE:
 444       g_value_set_string (value, priv->filename);
 445       break;
 446     case PROP_STOCK:
 447       g_value_set_string (value, _gtk_icon_helper_get_icon_name (priv->icon_helper));
 448       break;
 449     case PROP_ICON_SET:
 450       g_value_set_boxed (value, _gtk_icon_helper_peek_icon_set (priv->icon_helper));
 451       break;
 452     case PROP_ICON_SIZE:
 453       g_value_set_int (value, _gtk_icon_helper_get_icon_size (priv->icon_helper));
 454       break;
 455     case PROP_PIXEL_SIZE:
 456       g_value_set_int (value, _gtk_icon_helper_get_pixel_size (priv->icon_helper));
 457       break;
 458     case PROP_PIXBUF_ANIMATION:
 459       g_value_set_object (value, _gtk_icon_helper_peek_animation (priv->icon_helper));
 460       break;
 461     case PROP_ICON_NAME:
 462       g_value_set_string (value, _gtk_icon_helper_get_icon_name (priv->icon_helper));
 463       break;
 464     case PROP_GICON:
 465       g_value_set_object (value, _gtk_icon_helper_peek_gicon (priv->icon_helper));
 466       break;
 467     case PROP_USE_FALLBACK:
 468       g_value_set_boolean (value, _gtk_icon_helper_get_use_fallback (priv->icon_helper));
 469       break;
 470     default:
 471       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 472       break;
 473     }
 474 }
 475
 476
 477 /**
 478  * gtk_image_new_from_file:
 479  * @filename: (type filename): a filename
 480  *
 481  * Creates a new #GtkImage displaying the file @filename. If the file
 482  * isn't found or can't be loaded, the resulting #GtkImage will
 483  * display a "broken image" icon. This function never returns %NULL,
 484  * it always returns a valid #GtkImage widget.
 485  *
 486  * If the file contains an animation, the image will contain an
 487  * animation.
 488  *
 489  * If you need to detect failures to load the file, use
 490  * gdk_pixbuf_new_from_file() to load the file yourself, then create
 491  * the #GtkImage from the pixbuf. (Or for animations, use
 492  * gdk_pixbuf_animation_new_from_file()).
 493  *
 494  * The storage type (gtk_image_get_storage_type()) of the returned
 495  * image is not defined, it will be whatever is appropriate for
 496  * displaying the file.
 497  *
 498  * Return value: a new #GtkImage
 499  **/
 500 GtkWidget*
 501 gtk_image_new_from_file   (const gchar *filename)
 502 {
 503   GtkImage *image;
 504
 505   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 506
 507   gtk_image_set_from_file (image, filename);
 508
 509   return GTK_WIDGET (image);
 510 }
 511
 512 /**
 513  * gtk_image_new_from_pixbuf:
 514  * @pixbuf: (allow-none): a #GdkPixbuf, or %NULL
 515  *
 516  * Creates a new #GtkImage displaying @pixbuf.
 517  * The #GtkImage does not assume a reference to the
 518  * pixbuf; you still need to unref it if you own references.
 519  * #GtkImage will add its own reference rather than adopting yours.
 520  *
 521  * Note that this function just creates an #GtkImage from the pixbuf. The
 522  * #GtkImage created will not react to state changes. Should you want that,
 523  * you should use gtk_image_new_from_icon_set().
 524  *
 525  * Return value: a new #GtkImage
 526  **/
 527 GtkWidget*
 528 gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf)
 529 {
 530   GtkImage *image;
 531
 532   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 533
 534   gtk_image_set_from_pixbuf (image, pixbuf);
 535
 536   return GTK_WIDGET (image);
 537 }
 538
 539 /**
 540  * gtk_image_new_from_stock:
 541  * @stock_id: a stock icon name
 542  * @size: (type int): a stock icon size
 543  *
 544  * Creates a #GtkImage displaying a stock icon. Sample stock icon
 545  * names are #GTK_STOCK_OPEN, #GTK_STOCK_QUIT. Sample stock sizes
 546  * are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. If the stock
 547  * icon name isn't known, the image will be empty.
 548  * You can register your own stock icon names, see
 549  * gtk_icon_factory_add_default() and gtk_icon_factory_add().
 550  *
 551  * Return value: a new #GtkImage displaying the stock icon
 552  **/
 553 GtkWidget*
 554 gtk_image_new_from_stock (const gchar    *stock_id,
 555                           GtkIconSize     size)
 556 {
 557   GtkImage *image;
 558
 559   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 560
 561   gtk_image_set_from_stock (image, stock_id, size);
 562
 563   return GTK_WIDGET (image);
 564 }
 565
 566 /**
 567  * gtk_image_new_from_icon_set:
 568  * @icon_set: a #GtkIconSet
 569  * @size: (type int): a stock icon size
 570  *
 571  * Creates a #GtkImage displaying an icon set. Sample stock sizes are
 572  * #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of using
 573  * this function, usually it's better to create a #GtkIconFactory, put
 574  * your icon sets in the icon factory, add the icon factory to the
 575  * list of default factories with gtk_icon_factory_add_default(), and
 576  * then use gtk_image_new_from_stock(). This will allow themes to
 577  * override the icon you ship with your application.
 578  *
 579  * The #GtkImage does not assume a reference to the
 580  * icon set; you still need to unref it if you own references.
 581  * #GtkImage will add its own reference rather than adopting yours.
 582  *
 583  * Return value: a new #GtkImage
 584  **/
 585 GtkWidget*
 586 gtk_image_new_from_icon_set (GtkIconSet     *icon_set,
 587                              GtkIconSize     size)
 588 {
 589   GtkImage *image;
 590
 591   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 592
 593   gtk_image_set_from_icon_set (image, icon_set, size);
 594
 595   return GTK_WIDGET (image);
 596 }
 597
 598 /**
 599  * gtk_image_new_from_animation:
 600  * @animation: an animation
 601  *
 602  * Creates a #GtkImage displaying the given animation.
 603  * The #GtkImage does not assume a reference to the
 604  * animation; you still need to unref it if you own references.
 605  * #GtkImage will add its own reference rather than adopting yours.
 606  *
 607  * Note that the animation frames are shown using a timeout with
 608  * #G_PRIORITY_DEFAULT. When using animations to indicate busyness,
 609  * keep in mind that the animation will only be shown if the main loop
 610  * is not busy with something that has a higher priority.
 611  *
 612  * Return value: a new #GtkImage widget
 613  **/
 614 GtkWidget*
 615 gtk_image_new_from_animation (GdkPixbufAnimation *animation)
 616 {
 617   GtkImage *image;
 618
 619   g_return_val_if_fail (GDK_IS_PIXBUF_ANIMATION (animation), NULL);
 620
 621   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 622
 623   gtk_image_set_from_animation (image, animation);
 624
 625   return GTK_WIDGET (image);
 626 }
 627
 628 /**
 629  * gtk_image_new_from_icon_name:
 630  * @icon_name: an icon name
 631  * @size: (type int): a stock icon size
 632  *
 633  * Creates a #GtkImage displaying an icon from the current icon theme.
 634  * If the icon name isn't known, a "broken image" icon will be
 635  * displayed instead.  If the current icon theme is changed, the icon
 636  * will be updated appropriately.
 637  *
 638  * Return value: a new #GtkImage displaying the themed icon
 639  *
 640  * Since: 2.6
 641  **/
 642 GtkWidget*
 643 gtk_image_new_from_icon_name (const gchar    *icon_name,
 644                               GtkIconSize     size)
 645 {
 646   GtkImage *image;
 647
 648   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 649
 650   gtk_image_set_from_icon_name (image, icon_name, size);
 651
 652   return GTK_WIDGET (image);
 653 }
 654
 655 /**
 656  * gtk_image_new_from_gicon:
 657  * @icon: an icon
 658  * @size: (type int): a stock icon size
 659  *
 660  * Creates a #GtkImage displaying an icon from the current icon theme.
 661  * If the icon name isn't known, a "broken image" icon will be
 662  * displayed instead.  If the current icon theme is changed, the icon
 663  * will be updated appropriately.
 664  *
 665  * Return value: a new #GtkImage displaying the themed icon
 666  *
 667  * Since: 2.14
 668  **/
 669 GtkWidget*
 670 gtk_image_new_from_gicon (GIcon *icon,
 671                           GtkIconSize     size)
 672 {
 673   GtkImage *image;
 674
 675   image = g_object_new (GTK_TYPE_IMAGE, NULL);
 676
 677   gtk_image_set_from_gicon (image, icon, size);
 678
 679   return GTK_WIDGET (image);
 680 }
 681
 682 /**
 683  * gtk_image_set_from_file:
 684  * @image: a #GtkImage
 685  * @filename: (type filename) (allow-none): a filename or %NULL
 686  *
 687  * See gtk_image_new_from_file() for details.
 688  **/
 689 void
 690 gtk_image_set_from_file   (GtkImage    *image,
 691                            const gchar *filename)
 692 {
 693   GtkImagePrivate *priv;
 694   GdkPixbufAnimation *anim;
 695
 696   g_return_if_fail (GTK_IS_IMAGE (image));
 697
 698   priv = image->priv;
 699
 700   g_object_freeze_notify (G_OBJECT (image));
 701
 702   gtk_image_clear (image);
 703
 704   if (filename == NULL)
 705     {
 706       priv->filename = NULL;
 707       g_object_thaw_notify (G_OBJECT (image));
 708       return;
 709     }
 710
 711   anim = gdk_pixbuf_animation_new_from_file (filename, NULL);
 712
 713   if (anim == NULL)
 714     {
 715       gtk_image_set_from_stock (image,
 716                                 GTK_STOCK_MISSING_IMAGE,
 717                                 DEFAULT_ICON_SIZE);
 718       g_object_thaw_notify (G_OBJECT (image));
 719       return;
 720     }
 721
 722   /* We could just unconditionally set_from_animation,
 723    * but it's nicer for memory if we toss the animation
 724    * if it's just a single pixbuf
 725    */
 726
 727   if (gdk_pixbuf_animation_is_static_image (anim))
 728     gtk_image_set_from_pixbuf (image,
 729                                gdk_pixbuf_animation_get_static_image (anim));
 730   else
 731     gtk_image_set_from_animation (image, anim);
 732
 733   g_object_unref (anim);
 734
 735   priv->filename = g_strdup (filename);
 736
 737   g_object_thaw_notify (G_OBJECT (image));
 738 }
 739
 740 /**
 741  * gtk_image_set_from_pixbuf:
 742  * @image: a #GtkImage
 743  * @pixbuf: (allow-none): a #GdkPixbuf or %NULL
 744  *
 745  * See gtk_image_new_from_pixbuf() for details.
 746  **/
 747 void
 748 gtk_image_set_from_pixbuf (GtkImage  *image,
 749                            GdkPixbuf *pixbuf)
 750 {
 751   GtkImagePrivate *priv;
 752
 753   g_return_if_fail (GTK_IS_IMAGE (image));
 754   g_return_if_fail (pixbuf == NULL ||
 755                     GDK_IS_PIXBUF (pixbuf));
 756
 757   priv = image->priv;
 758
 759   g_object_freeze_notify (G_OBJECT (image));
 760
 761   gtk_image_clear (image);
 762
 763   if (pixbuf != NULL)
 764     _gtk_icon_helper_set_pixbuf (priv->icon_helper, pixbuf);
 765
 766   g_object_notify (G_OBJECT (image), "pixbuf");
 767
 768   g_object_thaw_notify (G_OBJECT (image));
 769 }
 770
 771 /**
 772  * gtk_image_set_from_stock:
 773  * @image: a #GtkImage
 774  * @stock_id: a stock icon name
 775  * @size: (type int): a stock icon size
 776  *
 777  * See gtk_image_new_from_stock() for details.
 778  **/
 779 void
 780 gtk_image_set_from_stock  (GtkImage       *image,
 781                            const gchar    *stock_id,
 782                            GtkIconSize     size)
 783 {
 784   GtkImagePrivate *priv;
 785   gchar *new_id;
 786
 787   g_return_if_fail (GTK_IS_IMAGE (image));
 788
 789   priv = image->priv;
 790
 791   g_object_freeze_notify (G_OBJECT (image));
 792
 793   new_id = g_strdup (stock_id);
 794   gtk_image_clear (image);
 795
 796   if (new_id)
 797     {
 798       _gtk_icon_helper_set_stock_id (priv->icon_helper, new_id, size);
 799       g_free (new_id);
 800     }
 801
 802   g_object_notify (G_OBJECT (image), "stock");
 803   g_object_notify (G_OBJECT (image), "icon-size");
 804
 805   g_object_thaw_notify (G_OBJECT (image));
 806 }
 807
 808 /**
 809  * gtk_image_set_from_icon_set:
 810  * @image: a #GtkImage
 811  * @icon_set: a #GtkIconSet
 812  * @size: (type int): a stock icon size
 813  *
 814  * See gtk_image_new_from_icon_set() for details.
 815  **/
 816 void
 817 gtk_image_set_from_icon_set  (GtkImage       *image,
 818                               GtkIconSet     *icon_set,
 819                               GtkIconSize     size)
 820 {
 821   GtkImagePrivate *priv;
 822
 823   g_return_if_fail (GTK_IS_IMAGE (image));
 824
 825   priv = image->priv;
 826
 827   g_object_freeze_notify (G_OBJECT (image));
 828
 829   if (icon_set)
 830     gtk_icon_set_ref (icon_set);
 831
 832   gtk_image_clear (image);
 833
 834   if (icon_set)
 835     {
 836       _gtk_icon_helper_set_icon_set (priv->icon_helper, icon_set, size);
 837       gtk_icon_set_unref (icon_set);
 838     }
 839
 840   g_object_notify (G_OBJECT (image), "icon-set");
 841   g_object_notify (G_OBJECT (image), "icon-size");
 842
 843   g_object_thaw_notify (G_OBJECT (image));
 844 }
 845
 846 /**
 847  * gtk_image_set_from_animation:
 848  * @image: a #GtkImage
 849  * @animation: the #GdkPixbufAnimation
 850  *
 851  * Causes the #GtkImage to display the given animation (or display
 852  * nothing, if you set the animation to %NULL).
 853  **/
 854 void
 855 gtk_image_set_from_animation (GtkImage           *image,
 856                               GdkPixbufAnimation *animation)
 857 {
 858   GtkImagePrivate *priv;
 859
 860   g_return_if_fail (GTK_IS_IMAGE (image));
 861   g_return_if_fail (animation == NULL ||
 862                     GDK_IS_PIXBUF_ANIMATION (animation));
 863
 864   priv = image->priv;
 865
 866   g_object_freeze_notify (G_OBJECT (image));
 867
 868   if (animation)
 869     g_object_ref (animation);
 870
 871   gtk_image_clear (image);
 872
 873   if (animation != NULL)
 874     {
 875       _gtk_icon_helper_set_animation (priv->icon_helper, animation);
 876       g_object_unref (animation);
 877     }
 878
 879   g_object_notify (G_OBJECT (image), "pixbuf-animation");
 880
 881   g_object_thaw_notify (G_OBJECT (image));
 882 }
 883
 884 /**
 885  * gtk_image_set_from_icon_name:
 886  * @image: a #GtkImage
 887  * @icon_name: an icon name
 888  * @size: (type int): an icon size
 889  *
 890  * See gtk_image_new_from_icon_name() for details.
 891  *
 892  * Since: 2.6
 893  **/
 894 void
 895 gtk_image_set_from_icon_name  (GtkImage       *image,
 896                                const gchar    *icon_name,
 897                                GtkIconSize     size)
 898 {
 899   GtkImagePrivate *priv;
 900   gchar *new_name;
 901
 902   g_return_if_fail (GTK_IS_IMAGE (image));
 903
 904   priv = image->priv;
 905
 906   g_object_freeze_notify (G_OBJECT (image));
 907
 908   new_name = g_strdup (icon_name);
 909   gtk_image_clear (image);
 910
 911   if (new_name)
 912     {
 913       _gtk_icon_helper_set_icon_name (priv->icon_helper, new_name, size);
 914       g_free (new_name);
 915     }
 916
 917   g_object_notify (G_OBJECT (image), "icon-name");
 918   g_object_notify (G_OBJECT (image), "icon-size");
 919
 920   g_object_thaw_notify (G_OBJECT (image));
 921 }
 922
 923 /**
 924  * gtk_image_set_from_gicon:
 925  * @image: a #GtkImage
 926  * @icon: an icon
 927  * @size: (type int): an icon size
 928  *
 929  * See gtk_image_new_from_gicon() for details.
 930  *
 931  * Since: 2.14
 932  **/
 933 void
 934 gtk_image_set_from_gicon  (GtkImage       *image,
 935                            GIcon          *icon,
 936                            GtkIconSize     size)
 937 {
 938   GtkImagePrivate *priv;
 939
 940   g_return_if_fail (GTK_IS_IMAGE (image));
 941
 942   priv = image->priv;
 943
 944   g_object_freeze_notify (G_OBJECT (image));
 945
 946   if (icon)
 947     g_object_ref (icon);
 948
 949   gtk_image_clear (image);
 950
 951   if (icon)
 952     {
 953       _gtk_icon_helper_set_gicon (priv->icon_helper, icon, size);
 954       g_object_unref (icon);
 955     }
 956
 957   g_object_notify (G_OBJECT (image), "gicon");
 958   g_object_notify (G_OBJECT (image), "icon-size");
 959
 960   g_object_thaw_notify (G_OBJECT (image));
 961 }
 962
 963 /**
 964  * gtk_image_get_storage_type:
 965  * @image: a #GtkImage
 966  *
 967  * Gets the type of representation being used by the #GtkImage
 968  * to store image data. If the #GtkImage has no image data,
 969  * the return value will be %GTK_IMAGE_EMPTY.
 970  *
 971  * Return value: image representation being used
 972  **/
 973 GtkImageType
 974 gtk_image_get_storage_type (GtkImage *image)
 975 {
 976   g_return_val_if_fail (GTK_IS_IMAGE (image), GTK_IMAGE_EMPTY);
 977
 978   return _gtk_icon_helper_get_storage_type (image->priv->icon_helper);
 979 }
 980
 981 /**
 982  * gtk_image_get_pixbuf:
 983  * @image: a #GtkImage
 984  *
 985  * Gets the #GdkPixbuf being displayed by the #GtkImage.
 986  * The storage type of the image must be %GTK_IMAGE_EMPTY or
 987  * %GTK_IMAGE_PIXBUF (see gtk_image_get_storage_type()).
 988  * The caller of this function does not own a reference to the
 989  * returned pixbuf.
 990  *
 991  * Return value: (transfer none): the displayed pixbuf, or %NULL if
 992  * the image is empty
 993  **/
 994 GdkPixbuf*
 995 gtk_image_get_pixbuf (GtkImage *image)
 996 {
 997   g_return_val_if_fail (GTK_IS_IMAGE (image), NULL);
 998
 999   return _gtk_icon_helper_peek_pixbuf (image->priv->icon_helper);
1000 }
1001
1002 /**
1003  * gtk_image_get_stock:
1004  * @image: a #GtkImage
1005  * @stock_id: (out) (transfer none) (allow-none): place to store a
1006  *     stock icon name, or %NULL
1007  * @size: (out) (allow-none) (type int): place to store a stock icon
1008  *     size, or %NULL
1009  *
1010  * Gets the stock icon name and size being displayed by the #GtkImage.
1011  * The storage type of the image must be %GTK_IMAGE_EMPTY or
1012  * %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()).
1013  * The returned string is owned by the #GtkImage and should not
1014  * be freed.
1015  **/
1016 void
1017 gtk_image_get_stock  (GtkImage        *image,
1018                       gchar          **stock_id,
1019                       GtkIconSize     *size)
1020 {
1021   GtkImagePrivate *priv;
1022
1023   g_return_if_fail (GTK_IS_IMAGE (image));
1024
1025   priv = image->priv;
1026
1027   if (stock_id)
1028     *stock_id = (gchar *) _gtk_icon_helper_get_stock_id (priv->icon_helper);
1029
1030   if (size)
1031     *size = _gtk_icon_helper_get_icon_size (priv->icon_helper);
1032 }
1033
1034 /**
1035  * gtk_image_get_icon_set:
1036  * @image: a #GtkImage
1037  * @icon_set: (out) (transfer none) (allow-none): location to store a
1038  *     #GtkIconSet, or %NULL
1039  * @size: (out) (allow-none) (type int): location to store a stock
1040  *     icon size, or %NULL
1041  *
1042  * Gets the icon set and size being displayed by the #GtkImage.
1043  * The storage type of the image must be %GTK_IMAGE_EMPTY or
1044  * %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()).
1045  **/
1046 void
1047 gtk_image_get_icon_set  (GtkImage        *image,
1048                          GtkIconSet     **icon_set,
1049                          GtkIconSize     *size)
1050 {
1051   GtkImagePrivate *priv;
1052
1053   g_return_if_fail (GTK_IS_IMAGE (image));
1054
1055   priv = image->priv;
1056
1057   if (icon_set)
1058     *icon_set = _gtk_icon_helper_peek_icon_set (priv->icon_helper);
1059
1060   if (size)
1061     *size = _gtk_icon_helper_get_icon_size (priv->icon_helper);
1062 }
1063
1064 /**
1065  * gtk_image_get_animation:
1066  * @image: a #GtkImage
1067  *
1068  * Gets the #GdkPixbufAnimation being displayed by the #GtkImage.
1069  * The storage type of the image must be %GTK_IMAGE_EMPTY or
1070  * %GTK_IMAGE_ANIMATION (see gtk_image_get_storage_type()).
1071  * The caller of this function does not own a reference to the
1072  * returned animation.
1073  *
1074  * Return value: (transfer none): the displayed animation, or %NULL if
1075  * the image is empty
1076  **/
1077 GdkPixbufAnimation*
1078 gtk_image_get_animation (GtkImage *image)
1079 {
1080   GtkImagePrivate *priv;
1081
1082   g_return_val_if_fail (GTK_IS_IMAGE (image), NULL);
1083
1084   priv = image->priv;
1085
1086   return _gtk_icon_helper_peek_animation (priv->icon_helper);
1087 }
1088
1089 /**
1090  * gtk_image_get_icon_name:
1091  * @image: a #GtkImage
1092  * @icon_name: (out) (transfer none) (allow-none): place to store an
1093  *     icon name, or %NULL
1094  * @size: (out) (allow-none) (type int): place to store an icon size,
1095  *     or %NULL
1096  *
1097  * Gets the icon name and size being displayed by the #GtkImage.
1098  * The storage type of the image must be %GTK_IMAGE_EMPTY or
1099  * %GTK_IMAGE_ICON_NAME (see gtk_image_get_storage_type()).
1100  * The returned string is owned by the #GtkImage and should not
1101  * be freed.
1102  *
1103  * Since: 2.6
1104  **/
1105 void
1106 gtk_image_get_icon_name  (GtkImage     *image,
1107                           const gchar **icon_name,
1108                           GtkIconSize  *size)
1109 {
1110   GtkImagePrivate *priv;
1111
1112   g_return_if_fail (GTK_IS_IMAGE (image));
1113
1114   priv = image->priv;
1115
1116   if (icon_name)
1117     *icon_name = _gtk_icon_helper_get_icon_name (priv->icon_helper);
1118
1119   if (size)
1120     *size = _gtk_icon_helper_get_icon_size (priv->icon_helper);
1121 }
1122
1123 /**
1124  * gtk_image_get_gicon:
1125  * @image: a #GtkImage
1126  * @gicon: (out) (transfer none) (allow-none): place to store a
1127  *     #GIcon, or %NULL
1128  * @size: (out) (allow-none) (type int): place to store an icon size,
1129  *     or %NULL
1130  *
1131  * Gets the #GIcon and size being displayed by the #GtkImage.
1132  * The storage type of the image must be %GTK_IMAGE_EMPTY or
1133  * %GTK_IMAGE_GICON (see gtk_image_get_storage_type()).
1134  * The caller of this function does not own a reference to the
1135  * returned #GIcon.
1136  *
1137  * Since: 2.14
1138  **/
1139 void
1140 gtk_image_get_gicon (GtkImage     *image,
1141                      GIcon       **gicon,
1142                      GtkIconSize  *size)
1143 {
1144   GtkImagePrivate *priv;
1145
1146   g_return_if_fail (GTK_IS_IMAGE (image));
1147
1148   priv = image->priv;
1149
1150   if (gicon)
1151     *gicon = _gtk_icon_helper_peek_gicon (priv->icon_helper);
1152
1153   if (size)
1154     *size = _gtk_icon_helper_get_icon_size (priv->icon_helper);
1155 }
1156
1157 /**
1158  * gtk_image_new:
1159  *
1160  * Creates a new empty #GtkImage widget.
1161  *
1162  * Return value: a newly created #GtkImage widget.
1163  **/
1164 GtkWidget*
1165 gtk_image_new (void)
1166 {
1167   return g_object_new (GTK_TYPE_IMAGE, NULL);
1168 }
1169
1170 static void
1171 gtk_image_reset_anim_iter (GtkImage *image)
1172 {
1173   GtkImagePrivate *priv = image->priv;
1174
1175   if (gtk_image_get_storage_type (image) == GTK_IMAGE_ANIMATION)
1176     {
1177       /* Reset the animation */
1178       if (priv->animation_timeout)
1179         {
1180           g_source_remove (priv->animation_timeout);
1181           priv->animation_timeout = 0;
1182         }
1183
1184       g_clear_object (&priv->animation_iter);
1185     }
1186 }
1187
1188 static void
1189 gtk_image_unmap (GtkWidget *widget)
1190 {
1191   gtk_image_reset_anim_iter (GTK_IMAGE (widget));
1192
1193   GTK_WIDGET_CLASS (gtk_image_parent_class)->unmap (widget);
1194 }
1195
1196 static void
1197 gtk_image_unrealize (GtkWidget *widget)
1198 {
1199   gtk_image_reset_anim_iter (GTK_IMAGE (widget));
1200
1201   GTK_WIDGET_CLASS (gtk_image_parent_class)->unrealize (widget);
1202 }
1203
1204 static gint
1205 animation_timeout (gpointer data)
1206 {
1207   GtkImage *image = GTK_IMAGE (data);
1208   GtkImagePrivate *priv = image->priv;
1209   int delay;
1210
1211   priv->animation_timeout = 0;
1212
1213   gdk_pixbuf_animation_iter_advance (priv->animation_iter, NULL);
1214
1215   delay = gdk_pixbuf_animation_iter_get_delay_time (priv->animation_iter);
1216   if (delay >= 0)
1217     {
1218       GtkWidget *widget = GTK_WIDGET (image);
1219
1220       priv->animation_timeout =
1221         gdk_threads_add_timeout (delay, animation_timeout, image);
1222
1223       gtk_widget_queue_draw (widget);
1224
1225       if (gtk_widget_is_drawable (widget))
1226         gdk_window_process_updates (gtk_widget_get_window (widget), TRUE);
1227     }
1228
1229   return FALSE;
1230 }
1231
1232 static GdkPixbuf *
1233 get_animation_frame (GtkImage *image)
1234 {
1235   GtkImagePrivate *priv = image->priv;
1236
1237   if (priv->animation_iter == NULL)
1238     {
1239       int delay;
1240
1241       priv->animation_iter =
1242         gdk_pixbuf_animation_get_iter (_gtk_icon_helper_peek_animation (priv->icon_helper), NULL);
1243
1244       delay = gdk_pixbuf_animation_iter_get_delay_time (priv->animation_iter);
1245       if (delay >= 0)
1246         priv->animation_timeout =
1247           gdk_threads_add_timeout (delay, animation_timeout, image);
1248     }
1249
1250   /* don't advance the anim iter here, or we could get frame changes between two
1251    * exposes of different areas.
1252    */
1253   return g_object_ref (gdk_pixbuf_animation_iter_get_pixbuf (priv->animation_iter));
1254 }
1255
1256 static gint
1257 gtk_image_draw (GtkWidget *widget,
1258                 cairo_t   *cr)
1259 {
1260   GtkImage *image;
1261   GtkImagePrivate *priv;
1262   GtkMisc *misc;
1263   GtkStateFlags state;
1264   GtkStyleContext *context;
1265   gint x, y, width, height;
1266   gint xpad, ypad;
1267   gfloat xalign, yalign;
1268
1269   g_return_val_if_fail (GTK_IS_IMAGE (widget), FALSE);
1270
1271   image = GTK_IMAGE (widget);
1272   misc = GTK_MISC (image);
1273   priv = image->priv;
1274
1275   context = gtk_widget_get_style_context (widget);
1276   state = gtk_widget_get_state_flags (widget);
1277
1278   gtk_style_context_save (context);
1279   gtk_style_context_set_state (context, state);
1280
1281   gtk_misc_get_alignment (misc, &xalign, &yalign);
1282   gtk_misc_get_padding (misc, &xpad, &ypad);
1283   _gtk_icon_helper_get_size (priv->icon_helper, context, &width, &height);
1284
1285   if (gtk_widget_get_direction (widget) != GTK_TEXT_DIR_LTR)
1286     xalign = 1.0 - xalign;
1287
1288   x = floor (xpad + ((gtk_widget_get_allocated_width (widget) - width) * xalign));
1289   y = floor (ypad + ((gtk_widget_get_allocated_height (widget) - height) * yalign));
1290
1291   if (gtk_image_get_storage_type (image) == GTK_IMAGE_ANIMATION)
1292     {
1293       GdkPixbuf *pixbuf = get_animation_frame (image);
1294       gtk_render_icon (context, cr,
1295                        pixbuf,
1296                        x, y);
1297       g_object_unref (pixbuf);
1298     }
1299   else
1300     {
1301       _gtk_icon_helper_draw (priv->icon_helper,
1302                              context, cr,
1303                              x, y);
1304     }
1305
1306   gtk_style_context_restore (context);
1307
1308   return FALSE;
1309 }
1310
1311 static void
1312 gtk_image_reset (GtkImage *image)
1313 {
1314   GtkImagePrivate *priv = image->priv;
1315   GtkImageType storage_type;
1316
1317   g_object_freeze_notify (G_OBJECT (image));
1318   storage_type = gtk_image_get_storage_type (image);
1319
1320   if (storage_type != GTK_IMAGE_EMPTY)
1321     g_object_notify (G_OBJECT (image), "storage-type");
1322
1323   g_object_notify (G_OBJECT (image), "icon-size");
1324
1325   switch (storage_type)
1326     {
1327     case GTK_IMAGE_PIXBUF:
1328       g_object_notify (G_OBJECT (image), "pixbuf");
1329       break;
1330     case GTK_IMAGE_STOCK:
1331       g_object_notify (G_OBJECT (image), "stock");
1332       break;
1333     case GTK_IMAGE_ICON_SET:
1334       g_object_notify (G_OBJECT (image), "icon-set");
1335       break;
1336     case GTK_IMAGE_ANIMATION:
1337       gtk_image_reset_anim_iter (image);
1338       g_object_notify (G_OBJECT (image), "pixbuf-animation");
1339       break;
1340     case GTK_IMAGE_ICON_NAME:
1341       g_object_notify (G_OBJECT (image), "icon-name");
1342       break;
1343     case GTK_IMAGE_GICON:
1344       g_object_notify (G_OBJECT (image), "gicon");
1345       break;
1346     case GTK_IMAGE_EMPTY:
1347     default:
1348       break;
1349     }
1350
1351   if (priv->filename)
1352     {
1353       g_free (priv->filename);
1354       priv->filename = NULL;
1355       g_object_notify (G_OBJECT (image), "file");
1356     }
1357
1358   _gtk_icon_helper_clear (priv->icon_helper);
1359
1360   g_object_thaw_notify (G_OBJECT (image));
1361 }
1362
1363 /**
1364  * gtk_image_clear:
1365  * @image: a #GtkImage
1366  *
1367  * Resets the image to be empty.
1368  *
1369  * Since: 2.8
1370  */
1371 void
1372 gtk_image_clear (GtkImage *image)
1373 {
1374   gtk_image_reset (image);
1375
1376   if (gtk_widget_get_visible (GTK_WIDGET (image)))
1377       gtk_widget_queue_resize (GTK_WIDGET (image));
1378 }
1379
1380 static void
1381 gtk_image_get_preferred_width (GtkWidget *widget,
1382                                gint      *minimum,
1383                                gint      *natural)
1384 {
1385   GtkImage *image = GTK_IMAGE (widget);
1386   GtkImagePrivate *priv = image->priv;
1387   gint xpad, width;
1388   GtkStyleContext *context;
1389
1390   context = gtk_widget_get_style_context (widget);
1391   gtk_misc_get_padding (GTK_MISC (image), &xpad, NULL);
1392   _gtk_icon_helper_get_size (priv->icon_helper, context, &width, NULL);
1393
1394   *minimum = *natural = width + 2 * xpad;
1395 }
1396
1397 static void
1398 gtk_image_get_preferred_height (GtkWidget *widget,
1399                                 gint      *minimum,
1400                                 gint      *natural)
1401 {
1402   GtkImage *image = GTK_IMAGE (widget);
1403   GtkImagePrivate *priv = image->priv;
1404   gint ypad, height;
1405   GtkStyleContext *context;
1406
1407   context = gtk_widget_get_style_context (widget);
1408   gtk_misc_get_padding (GTK_MISC (image), NULL, &ypad);
1409   _gtk_icon_helper_get_size (priv->icon_helper, context, NULL, &height);
1410
1411   *minimum = *natural = height + 2 * ypad;
1412 }
1413
1414 static void
1415 icon_theme_changed (GtkImage *image)
1416 {
1417   GtkImagePrivate *priv = image->priv;
1418
1419   _gtk_icon_helper_invalidate (priv->icon_helper);
1420   gtk_widget_queue_draw (GTK_WIDGET (image));
1421 }
1422
1423 static void
1424 gtk_image_style_updated (GtkWidget *widget)
1425 {
1426   GTK_WIDGET_CLASS (gtk_image_parent_class)->style_updated (widget);
1427
1428   icon_theme_changed (GTK_IMAGE (widget));
1429 }
1430
1431 static void
1432 gtk_image_screen_changed (GtkWidget *widget,
1433                           GdkScreen *prev_screen)
1434 {
1435   GtkImage *image;
1436
1437   image = GTK_IMAGE (widget);
1438
1439   if (GTK_WIDGET_CLASS (gtk_image_parent_class)->screen_changed)
1440     GTK_WIDGET_CLASS (gtk_image_parent_class)->screen_changed (widget, prev_screen);
1441
1442   icon_theme_changed (image);
1443 }
1444
1445 void
1446 _gtk_image_gicon_data_clear (GtkImageGIconData *data)
1447 {
1448   if (data->pixbuf)
1449     {
1450       g_object_unref (data->pixbuf);
1451       data->pixbuf = NULL;
1452     }
1453   if (data->icon)
1454     {
1455       g_object_unref (data->icon);
1456       data->icon = NULL;
1457     }
1458 }
1459
1460 /**
1461  * gtk_image_set_pixel_size:
1462  * @image: a #GtkImage
1463  * @pixel_size: the new pixel size
1464  *
1465  * Sets the pixel size to use for named icons. If the pixel size is set
1466  * to a value != -1, it is used instead of the icon size set by
1467  * gtk_image_set_from_icon_name().
1468  *
1469  * Since: 2.6
1470  */
1471 void
1472 gtk_image_set_pixel_size (GtkImage *image,
1473                           gint      pixel_size)
1474 {
1475   GtkImagePrivate *priv;
1476   gint old_pixel_size;
1477
1478   g_return_if_fail (GTK_IS_IMAGE (image));
1479
1480   priv = image->priv;
1481   old_pixel_size = gtk_image_get_pixel_size (image);
1482
1483   if (pixel_size != old_pixel_size)
1484     {
1485       _gtk_icon_helper_set_pixel_size (priv->icon_helper, pixel_size);
1486
1487       if (gtk_widget_get_visible (GTK_WIDGET (image)))
1488         gtk_widget_queue_resize (GTK_WIDGET (image));
1489
1490       g_object_notify (G_OBJECT (image), "pixel-size");
1491     }
1492 }
1493
1494 /**
1495  * gtk_image_get_pixel_size:
1496  * @image: a #GtkImage
1497  *
1498  * Gets the pixel size used for named icons.
1499  *
1500  * Returns: the pixel size used for named icons.
1501  *
1502  * Since: 2.6
1503  */
1504 gint
1505 gtk_image_get_pixel_size (GtkImage *image)
1506 {
1507   g_return_val_if_fail (GTK_IS_IMAGE (image), -1);
1508
1509   return _gtk_icon_helper_get_pixel_size (image->priv->icon_helper);
1510 }