Image

The #GtkImage widget displays an image. Various kinds of object can be displayed as an image; most typically, you would load a #GdkPixbuf ("pixel buffer") from a file, and then display that. There’s a convenience function to do this, gtk.image.Image.newFromFile, used as follows:

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

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 gdkpixbuf.pixbuf.Pixbuf.newFromFile, then create the #GtkImage with gtk.image.Image.newFromPixbuf.

The image file may contain an animation, if so the #GtkImage will display an animation (#GdkPixbufAnimation) instead of a static image.

#GtkImage is a subclass of #GtkMisc, which implies that you can align it (center, left, right) and add padding to it, using #GtkMisc methods.

#GtkImage is a “no window” widget (has no #GdkWindow 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 #GtkEventBox, then connect to the event signals on the event box.

Handling button press events on a #GtkImage.

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 #GtkMisc). 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 “gdk-pixbuf-csource”. This library allows you to convert an image into a C variable declaration, which can then be loaded into a #GdkPixbuf using gdkpixbuf.pixbuf.Pixbuf.newFromInline.

CSS nodes

GtkImage has a single CSS node with the name image. The style classes may appear on image CSS nodes: .icon-dropshadow, .lowres-icon.

class Image : Misc {

this(void* ptr, Flag!"Take" take);

static GType _getGType();

GType _gType [@property getter];

Image self();

static ImageGidBuilder builder();

string file [@property getter];

string file [@property setter];

gio.icon.Icon gicon [@property getter];

gio.icon.Icon gicon [@property setter];

string iconName [@property getter];

string iconName [@property setter];

gtk.icon_set.IconSet iconSet [@property getter];

gtk.icon_set.IconSet iconSet [@property setter];

int iconSize [@property getter];

int iconSize [@property setter];

gdkpixbuf.pixbuf.Pixbuf pixbuf [@property getter];

gdkpixbuf.pixbuf.Pixbuf pixbuf [@property setter];

gdkpixbuf.pixbuf_animation.PixbufAnimation pixbufAnimation [@property getter];

gdkpixbuf.pixbuf_animation.PixbufAnimation pixbufAnimation [@property setter];

int pixelSize [@property getter];

int pixelSize [@property setter];

string resource [@property getter];

string resource [@property setter];

string stock [@property getter];

string stock [@property setter];

gtk.types.ImageType storageType [@property getter];

cairo.surface.Surface surface [@property getter];

cairo.surface.Surface surface [@property setter];

bool useFallback [@property getter];

bool useFallback [@property setter];

static gtk.image.Image newFromAnimation(gdkpixbuf.pixbuf_animation.PixbufAnimation animation);

static gtk.image.Image newFromFile(string filename);

static gtk.image.Image newFromGicon(gio.icon.Icon icon, gtk.types.IconSize size);

static gtk.image.Image newFromIconName(string iconName, gtk.types.IconSize size);

static gtk.image.Image newFromIconSet(gtk.icon_set.IconSet iconSet, gtk.types.IconSize size);

static gtk.image.Image newFromPixbuf(gdkpixbuf.pixbuf.Pixbuf pixbuf);

static gtk.image.Image newFromResource(string resourcePath);

static gtk.image.Image newFromStock(string stockId, gtk.types.IconSize size);

static gtk.image.Image newFromSurface(cairo.surface.Surface surface);

void clear();

gdkpixbuf.pixbuf_animation.PixbufAnimation getAnimation();

void getGicon(gio.icon.Icon gicon, gtk.types.IconSize size);

void getIconName(string iconName, gtk.types.IconSize size);

void getIconSet(gtk.icon_set.IconSet iconSet, gtk.types.IconSize size);

gdkpixbuf.pixbuf.Pixbuf getPixbuf();

int getPixelSize();

void getStock(string stockId, gtk.types.IconSize size);

gtk.types.ImageType getStorageType();

void setFromAnimation(gdkpixbuf.pixbuf_animation.PixbufAnimation animation);

void setFromFile(string filename);

void setFromGicon(gio.icon.Icon icon, gtk.types.IconSize size);

void setFromIconName(string iconName, gtk.types.IconSize size);

void setFromIconSet(gtk.icon_set.IconSet iconSet, gtk.types.IconSize size);

void setFromPixbuf(gdkpixbuf.pixbuf.Pixbuf pixbuf);

void setFromResource(string resourcePath);

void setFromStock(string stockId, gtk.types.IconSize size);

void setFromSurface(cairo.surface.Surface surface);

void setPixelSize(int pixelSize);

}

Constructors

this this(void* ptr, Flag!"Take" take)
this this(): Creates a new empty #GtkImage widget.

Members

Functions

clear void clear(): Resets the image to be empty.
getAnimation gdkpixbuf.pixbuf_animation.PixbufAnimation getAnimation(): Gets the #GdkPixbufAnimation being displayed by the #GtkImage. The storage type of the image must be gtk.types.ImageType.Empty or gtk.types.ImageType.Animation (see gtk.image.Image.getStorageType). The caller of this function does not own a reference to the returned animation.
getGicon void getGicon(gio.icon.Icon gicon, gtk.types.IconSize size): Gets the #GIcon and size being displayed by the #GtkImage. The storage type of the image must be gtk.types.ImageType.Empty or gtk.types.ImageType.Gicon (see gtk.image.Image.getStorageType). The caller of this function does not own a reference to the returned #GIcon.
getIconName void getIconName(string iconName, gtk.types.IconSize size): Gets the icon name and size being displayed by the #GtkImage. The storage type of the image must be gtk.types.ImageType.Empty or gtk.types.ImageType.IconName (see gtk.image.Image.getStorageType). The returned string is owned by the #GtkImage and should not be freed.
getIconSet void getIconSet(gtk.icon_set.IconSet iconSet, gtk.types.IconSize size): Gets the icon set and size being displayed by the #GtkImage. The storage type of the image must be gtk.types.ImageType.Empty or gtk.types.ImageType.IconSet (see gtk.image.Image.getStorageType).
getPixbuf gdkpixbuf.pixbuf.Pixbuf getPixbuf(): Gets the #GdkPixbuf being displayed by the #GtkImage. The storage type of the image must be gtk.types.ImageType.Empty or gtk.types.ImageType.Pixbuf (see gtk.image.Image.getStorageType). The caller of this function does not own a reference to the returned pixbuf.
getPixelSize int getPixelSize(): Gets the pixel size used for named icons.
getStock void getStock(string stockId, gtk.types.IconSize size): Gets the stock icon name and size being displayed by the #GtkImage. The storage type of the image must be gtk.types.ImageType.Empty or gtk.types.ImageType.Stock (see gtk.image.Image.getStorageType). The returned string is owned by the #GtkImage and should not be freed.
getStorageType gtk.types.ImageType getStorageType(): Gets the type of representation being used by the #GtkImage to store image data. If the #GtkImage has no image data, the return value will be gtk.types.ImageType.Empty.
self Image self(): Returns this, for use in with statements.
setFromAnimation void setFromAnimation(gdkpixbuf.pixbuf_animation.PixbufAnimation animation): Causes the #GtkImage to display the given animation (or display nothing, if you set the animation to null).
setFromFile void setFromFile(string filename): See gtk.image.Image.newFromFile for details.
setFromGicon void setFromGicon(gio.icon.Icon icon, gtk.types.IconSize size): See gtk.image.Image.newFromGicon for details.
setFromIconName void setFromIconName(string iconName, gtk.types.IconSize size): See gtk.image.Image.newFromIconName for details.
setFromIconSet void setFromIconSet(gtk.icon_set.IconSet iconSet, gtk.types.IconSize size): See gtk.image.Image.newFromIconSet for details.
setFromPixbuf void setFromPixbuf(gdkpixbuf.pixbuf.Pixbuf pixbuf): See gtk.image.Image.newFromPixbuf for details.
setFromResource void setFromResource(string resourcePath): See gtk.image.Image.newFromResource for details.
setFromStock void setFromStock(string stockId, gtk.types.IconSize size): See gtk.image.Image.newFromStock for details.
setFromSurface void setFromSurface(cairo.surface.Surface surface): See gtk.image.Image.newFromSurface for details.
setPixelSize void setPixelSize(int pixelSize): 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.Image.setFromIconName.

Properties

_gType GType _gType [@property getter]
file string file [@property getter]
file string file [@property setter]
gicon gio.icon.Icon gicon [@property getter]: Get gicon property.
gicon gio.icon.Icon gicon [@property setter]: Set gicon property.
iconName string iconName [@property getter]: Get iconName property.
iconName string iconName [@property setter]: Set iconName property.
iconSet gtk.icon_set.IconSet iconSet [@property getter]
iconSet gtk.icon_set.IconSet iconSet [@property setter]
iconSize int iconSize [@property getter]
iconSize int iconSize [@property setter]
pixbuf gdkpixbuf.pixbuf.Pixbuf pixbuf [@property getter]
pixbuf gdkpixbuf.pixbuf.Pixbuf pixbuf [@property setter]
pixbufAnimation gdkpixbuf.pixbuf_animation.PixbufAnimation pixbufAnimation [@property getter]
pixbufAnimation gdkpixbuf.pixbuf_animation.PixbufAnimation pixbufAnimation [@property setter]
pixelSize int pixelSize [@property getter]: Get pixelSize property.
pixelSize int pixelSize [@property setter]: Set pixelSize property.
resource string resource [@property getter]: Get resource property.
resource string resource [@property setter]: Set resource property.
stock string stock [@property getter]
stock string stock [@property setter]
storageType gtk.types.ImageType storageType [@property getter]
surface cairo.surface.Surface surface [@property getter]
surface cairo.surface.Surface surface [@property setter]
useFallback bool useFallback [@property getter]: Get useFallback property.
useFallback bool useFallback [@property setter]: Set useFallback property.

Static functions

_getGType GType _getGType()
builder ImageGidBuilder builder(): Get builder for gtk.image.Image
newFromAnimation gtk.image.Image newFromAnimation(gdkpixbuf.pixbuf_animation.PixbufAnimation animation): Creates a #GtkImage displaying the given animation. The #GtkImage does not assume a reference to the animation; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours.
newFromFile gtk.image.Image newFromFile(string filename): Creates a new #GtkImage displaying the file filename. If the file isn’t found or can’t be loaded, the resulting #GtkImage will display a “broken image” icon. This function never returns null, it always returns a valid #GtkImage widget.
newFromGicon gtk.image.Image newFromGicon(gio.icon.Icon icon, gtk.types.IconSize size): Creates a #GtkImage 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.
newFromIconName gtk.image.Image newFromIconName(string iconName, gtk.types.IconSize size): Creates a #GtkImage 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.
newFromIconSet gtk.image.Image newFromIconSet(gtk.icon_set.IconSet iconSet, gtk.types.IconSize size): Creates a #GtkImage 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 #GtkIconFactory, put your icon sets in the icon factory, add the icon factory to the list of default factories with gtk.icon_factory.IconFactory.addDefault, and then use gtk.image.Image.newFromStock. This will allow themes to override the icon you ship with your application.
newFromPixbuf gtk.image.Image newFromPixbuf(gdkpixbuf.pixbuf.Pixbuf pixbuf): Creates a new #GtkImage displaying pixbuf. The #GtkImage does not assume a reference to the pixbuf; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours.
newFromResource gtk.image.Image newFromResource(string resourcePath): Creates a new #GtkImage displaying the resource file resource_path. If the file isn’t found or can’t be loaded, the resulting #GtkImage will display a “broken image” icon. This function never returns null, it always returns a valid #GtkImage widget.
newFromStock gtk.image.Image newFromStock(string stockId, gtk.types.IconSize size): Creates a #GtkImage 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.IconFactory.addDefault and gtk.icon_factory.IconFactory.add.
newFromSurface gtk.image.Image newFromSurface(cairo.surface.Surface surface): Creates a new #GtkImage displaying surface. The #GtkImage does not assume a reference to the surface; you still need to unref it if you own references. #GtkImage will add its own reference rather than adopting yours.

Inherited Members

From Misc

_getGType GType _getGType()
_gType GType _gType [@property getter]
self Misc self(): Returns this, for use in with statements.
builder MiscGidBuilder builder(): Get builder for gtk.misc.Misc
xalign float xalign [@property getter]: Get xalign property.
xalign float xalign [@property setter]: Set xalign property.
xpad int xpad [@property getter]: Get xpad property.
xpad int xpad [@property setter]: Set xpad property.
yalign float yalign [@property getter]: Get yalign property.
yalign float yalign [@property setter]: Set yalign property.
ypad int ypad [@property getter]: Get ypad property.
ypad int ypad [@property setter]: Set ypad property.
getAlignment void getAlignment(float xalign, float yalign): Gets the X and Y alignment of the widget within its allocation. See gtk.misc.Misc.setAlignment.
getPadding void getPadding(int xpad, int ypad): Gets the padding in the X and Y directions of the widget. See gtk.misc.Misc.setPadding.
setAlignment void setAlignment(float xalign, float yalign): Sets the alignment of the widget.
setPadding void setPadding(int xpad, int ypad): Sets the amount of space to add around the widget.

gtk image classes