Next: , Previous: GtkAccelLabel, Up: Top

10 GtkImage

A widget displaying an image

10.1 Overview

The <gtk-image> widget displays an image. Various kinds of object can be displayed as an image; most typically, you would load a <gdk-pixbuf> ("pixel buffer") from a file, and then display that. There's a convenience function to do this, gtk-image-new-from-file, used as follows: If the file isn't loaded successfully, the image will contain a "broken image" icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with gdk-pixbuf-new-from-file, then create the <gtk-image> with gtk-image-new-from-pixbuf. 

     
       GtkWidget *image;
       image = gtk_image_new_from_file ("myfile.png");

The image file may contain an animation, if so the <gtk-image> will display an animation (<gdk-pixbuf-animation>) instead of a static image.

<gtk-image> is a subclass of <gtk-misc>, which implies that you can align it (center, left, right) and add padding to it, using <gtk-misc> methods.

<gtk-image> is a "no window" widget (has no <gdk-window> of its own), so by default does not receive events. If you want to receive events on the image, such as button clicks, place the image inside a <gtk-event-box>, then connect to the event signals on the event box. 

     
       static gboolean
       button_press_callback (GtkWidget      *event_box,
                              GdkEventButton *event,
                              gpointer        data)
       {
         g_print ("Event box clicked at coordinates %f,%f\n",
                  event->x, event->y);
     
         /* Returning TRUE means we handled the event, so the signal
          * emission should be stopped (don't call any further
          * callbacks that may be connected). Return FALSE
          * to continue invoking callbacks.
          */
         return TRUE;
       }
     
       static GtkWidget*
       create_image (void)
       {
         GtkWidget *image;
         GtkWidget *event_box;
     
         image = gtk_image_new_from_file ("myfile.png");
     
         event_box = gtk_event_box_new ();
     
         gtk_container_add (GTK_CONTAINER (event_box), image);
     
         g_signal_connect (G_OBJECT (event_box),
                           "button_press_event",
                           G_CALLBACK (button_press_callback),
                           image);
     
         return image;
       }

When handling events on the event box, keep in mind that coordinates in the image may be different from event box coordinates due to the alignment and padding settings on the image (see <gtk-misc>). The simplest way to solve this is to set the alignment to 0.0 (left/top), and set the padding to zero. Then the origin of the image will be the same as the origin of the event box.

Sometimes an application will want to avoid depending on external data files, such as image files. GTK+ comes with a program to avoid this, called . This program allows you to convert an image into a C variable declaration, which can then be loaded into a <gdk-pixbuf> using gdk-pixbuf-new-from-inline.

10.2 Usage

— Class: <gtk-image>

Derives from <gtk-misc>.

This class defines the following slots:

pixbuf
A GdkPixbuf to display
pixmap
A GdkPixmap to display
image
A GdkImage to display
mask
Mask bitmap to use with GdkImage or GdkPixmap
file
Filename to load and display
stock
Stock ID for a stock image to display
icon-set
Icon set to display
icon-size
Symbolic size to use for stock icon, icon set or named icon
pixel-size
Pixel size to use for named icon
pixbuf-animation
GdkPixbufAnimation to display
icon-name
The name of the icon from the icon theme
storage-type
The representation being used for image data
— Function: gtk-image-get-pixbuf (self <gtk-image>) ⇒  (ret <gdk-pixbuf>)
— Method: get-pixbuf

Gets the <gdk-pixbuf> being displayed by the <gtk-image>. The storage type of the image must be ‘GTK_IMAGE_EMPTY’ or ‘GTK_IMAGE_PIXBUF’ (see gtk-image-get-storage-type). The caller of this function does not own a reference to the returned pixbuf.

image
a <gtk-image>
ret
the displayed pixbuf, or ‘#f’ if the image is empty
— Function: gtk-image-get-animation (self <gtk-image>) ⇒  (ret <gdk-pixbuf-animation>)
— Method: get-animation

Gets the <gdk-pixbuf-animation> being displayed by the <gtk-image>. The storage type of the image must be ‘GTK_IMAGE_EMPTY’ or ‘GTK_IMAGE_ANIMATION’ (see gtk-image-get-storage-type). The caller of this function does not own a reference to the returned animation.

image
a <gtk-image>
ret
the displayed animation, or ‘#f’ if the image is empty
— Function: gtk-image-get-storage-type (self <gtk-image>) ⇒  (ret <gtk-image-type>)
— Method: get-storage-type

Gets the type of representation being used by the <gtk-image> to store image data. If the <gtk-image> has no image data, the return value will be ‘GTK_IMAGE_EMPTY’.

image
a <gtk-image>
ret
image representation being used
— Function: gtk-image-new-from-file (filename mchars) ⇒  (ret <gtk-widget>)

Creates a new <gtk-image> displaying the file filename. If the file isn't found or can't be loaded, the resulting <gtk-image> will display a "broken image" icon. This function never returns ‘#f’, it always returns a valid <gtk-image> widget.

If the file contains an animation, the image will contain an animation.

If you need to detect failures to load the file, use gdk-pixbuf-new-from-file to load the file yourself, then create the <gtk-image> from the pixbuf. (Or for animations, use gdk-pixbuf-animation-new-from-file).

The storage type (gtk-image-get-storage-type) of the returned image is not defined, it will be whatever is appropriate for displaying the file.

filename
a filename
ret
a new <gtk-image>
— Function: gtk-image-new-from-icon-set (icon_set <gtk-icon-set>) (size <gtk-icon-size>) ⇒  (ret <gtk-widget>)

Creates a <gtk-image> displaying an icon set. Sample stock sizes are <gtk-icon-size-menu>, <gtk-icon-size-small-toolbar>. Instead of using this function, usually it's better to create a <gtk-icon-factory>, put your icon sets in the icon factory, add the icon factory to the list of default factories with gtk-icon-factory-add-default, and then use gtk-image-new-from-stock. This will allow themes to override the icon you ship with your application.

The <gtk-image> does not assume a reference to the icon set; you still need to unref it if you own references. <gtk-image> will add its own reference rather than adopting yours.

icon-set
a <gtk-icon-set>
size
a stock icon size
ret
a new <gtk-image>
— Function: gtk-image-new-from-image (image <gdk-image>) (mask <gdk-drawable>) ⇒  (ret <gtk-widget>)

Creates a <gtk-image> widget displaying a image with a mask. A <gdk-image> is a client-side image buffer in the pixel format of the current display. The <gtk-image> does not assume a reference to the image or mask; you still need to unref them if you own references. <gtk-image> will add its own reference rather than adopting yours.

image
a <gdk-image>, or ‘#f’
mask
a <gdk-bitmap>, or ‘#f’
ret
a new <gtk-image>
— Function: gtk-image-new-from-pixbuf (pixbuf <gdk-pixbuf>) ⇒  (ret <gtk-widget>)

Creates a new <gtk-image> displaying pixbuf. The <gtk-image> does not assume a reference to the pixbuf; you still need to unref it if you own references. <gtk-image> will add its own reference rather than adopting yours.

Note that this function just creates an <gtk-image> from the pixbuf. The <gtk-image> created will not react to state changes. Should you want that, you should use gtk-image-new-from-icon-set.

pixbuf
a <gdk-pixbuf>, or ‘#f’
ret
a new <gtk-image>
— Function: gtk-image-new-from-pixmap (pixmap <gdk-pixmap>) (mask <gdk-drawable>) ⇒  (ret <gtk-widget>)

Creates a <gtk-image> widget displaying pixmap with a mask. A <gdk-pixmap> is a server-side image buffer in the pixel format of the current display. The <gtk-image> does not assume a reference to the pixmap or mask; you still need to unref them if you own references. <gtk-image> will add its own reference rather than adopting yours.

pixmap
a <gdk-pixmap>, or ‘#f’
mask
a <gdk-bitmap>, or ‘#f’
ret
a new <gtk-image>
— Function: gtk-image-new-from-stock (stock_id mchars) (size <gtk-icon-size>) ⇒  (ret <gtk-widget>)

Creates a <gtk-image> displaying a stock icon. Sample stock icon names are <gtk-stock-open>, <gtk-stock-quit>. Sample stock sizes are <gtk-icon-size-menu>, <gtk-icon-size-small-toolbar>. If the stock icon name isn't known, the image will be empty. You can register your own stock icon names, see gtk-icon-factory-add-default and gtk-icon-factory-add.

stock-id
a stock icon name
size
a stock icon size
ret
a new <gtk-image> displaying the stock icon
— Function: gtk-image-new-from-animation (animation <gdk-pixbuf-animation>) ⇒  (ret <gtk-widget>)

Creates a <gtk-image> displaying the given animation. The <gtk-image> does not assume a reference to the animation; you still need to unref it if you own references. <gtk-image> will add its own reference rather than adopting yours.

Note that the animation frames are shown using a timeout with <g-priority-default>. When using animations to indicate busyness, keep in mind that the animation will only be shown if the main loop is not busy with something that has a higher priority.

animation
an animation
ret
a new <gtk-image> widget
— Function: gtk-image-new-from-icon-name (icon_name mchars) (size <gtk-icon-size>) ⇒  (ret <gtk-widget>)

Creates a <gtk-image> displaying an icon from the current icon theme. If the icon name isn't known, a "broken image" icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

icon-name
an icon name
size
a stock icon size
ret
a new <gtk-image> displaying the themed icon

Since 2.6

— Function: gtk-image-set-from-file (self <gtk-image>) (filename mchars)
— Method: set-from-file

See gtk-image-new-from-file for details.

image
a <gtk-image>
filename
a filename or ‘#f’
— Function: gtk-image-set-from-icon-set (self <gtk-image>) (icon_set <gtk-icon-set>) (size <gtk-icon-size>)
— Method: set-from-icon-set

See gtk-image-new-from-icon-set for details.

image
a <gtk-image>
icon-set
a <gtk-icon-set>
size
a stock icon size
— Function: gtk-image-set-from-image (self <gtk-image>) (gdk_image <gdk-image>) (mask <gdk-drawable>)
— Method: set-from-image

See gtk-image-new-from-image for details.

image
a <gtk-image>
gdk-image
a <gdk-image> or ‘#f’
mask
a <gdk-bitmap> or ‘#f’
— Function: gtk-image-set-from-pixbuf (self <gtk-image>) (pixbuf <gdk-pixbuf>)
— Method: set-from-pixbuf

See gtk-image-new-from-pixbuf for details.

image
a <gtk-image>
pixbuf
a <gdk-pixbuf> or ‘#f’
— Function: gtk-image-set-from-pixmap (self <gtk-image>) (pixmap <gdk-pixmap>) (mask <gdk-drawable>)
— Method: set-from-pixmap

See gtk-image-new-from-pixmap for details.

image
a <gtk-image>
pixmap
a <gdk-pixmap> or ‘#f’
mask
a <gdk-bitmap> or ‘#f’
— Function: gtk-image-set-from-stock (self <gtk-image>) (stock_id mchars) (size <gtk-icon-size>)
— Method: set-from-stock

See gtk-image-new-from-stock for details.

image
a <gtk-image>
stock-id
a stock icon name
size
a stock icon size
— Function: gtk-image-set-from-animation (self <gtk-image>) (animation <gdk-pixbuf-animation>)
— Method: set-from-animation

Causes the <gtk-image> to display the given animation (or display nothing, if you set the animation to ‘#f’).

image
a <gtk-image>
animation
the <gdk-pixbuf-animation>
— Function: gtk-image-set-from-icon-name (self <gtk-image>) (icon_name mchars) (size <gtk-icon-size>)
— Method: set-from-icon-name

See gtk-image-new-from-icon-name for details.

image
a <gtk-image>
icon-name
an icon name
size
an icon size

Since 2.6

— Function: gtk-image-clear (self <gtk-image>)
— Method: clear

Resets the image to be empty.

image
a <gtk-image>

Since 2.8

— Function: gtk-image-new ⇒  (ret <gtk-widget>)

Creates a new empty <gtk-image> widget.

ret
a newly created <gtk-image> widget.
— Function: gtk-image-set-pixel-size (self <gtk-image>) (pixel_size int)
— Method: set-pixel-size

Sets the pixel size to use for named icons. If the pixel size is set to a value != -1, it is used instead of the icon size set by gtk-image-set-from-icon-name.

image
a <gtk-image>
pixel-size
the new pixel size

Since 2.6

— Function: gtk-image-get-pixel-size (self <gtk-image>) ⇒  (ret int)
— Method: get-pixel-size

Gets the pixel size used for named icons.

image
a <gtk-image>
ret
the pixel size used for named icons.

Since 2.6