GI.Gtk.Objects.Image

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

C code

 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 pixbufNewFromFile, then create the Image with imageNewFromPixbuf.

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

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

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

## Handling button press events on a Image.

C code

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

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.

Exported types

newtype Image

Memory-managed wrapper type.

Constructors

Image (ManagedPtr Image)

Instances

GObject Image

Defined in GI.Gtk.Objects.Image

Methods

gobjectType :: IO GType

HasParentTypes Image

Defined in GI.Gtk.Objects.Image

type ParentTypes Image

Defined in GI.Gtk.Objects.Image

type ParentTypes Image = Misc ': (Widget ': (Object ': (ImplementorIface ': (Buildable ': ([] :: [Type])))))

class (GObject o, IsDescendantOf Image o) => IsImage o

Type class for types which can be safely cast to Image, for instance with toImage.

Instances

(GObject o, IsDescendantOf Image o) => IsImage o

Defined in GI.Gtk.Objects.Image

toImage :: (MonadIO m, IsImage o) => o -> m Image

Cast to Image, for types for which this is known to be safe. For general casts, use castTo.

noImage :: Maybe Image

A convenience alias for Nothing :: Maybe Image.

Methods

clear

imageClear

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m ()

Resets the image to be empty.

Since: 2.8

getAnimation

imageGetAnimation

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Maybe PixbufAnimation)

Returns: the displayed animation, or Nothing if the image is empty

Gets the PixbufAnimation being displayed by the Image. The storage type of the image must be ImageTypeEmpty or ImageTypeAnimation (see imageGetStorageType). The caller of this function does not own a reference to the returned animation.

getGicon

imageGetGicon

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Icon, Int32)

Gets the Icon and size being displayed by the Image. The storage type of the image must be ImageTypeEmpty or ImageTypeGicon (see imageGetStorageType). The caller of this function does not own a reference to the returned Icon.

Since: 2.14

getIconName

imageGetIconName

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Text, Int32)

Gets the icon name and size being displayed by the Image. The storage type of the image must be ImageTypeEmpty or ImageTypeIconName (see imageGetStorageType). The returned string is owned by the Image and should not be freed.

Since: 2.6

getIconSet

imageGetIconSet

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (IconSet, Int32)

Deprecated: (Since version 3.10)Use imageGetIconName instead.

Gets the icon set and size being displayed by the Image. The storage type of the image must be ImageTypeEmpty or ImageTypeIconSet (see imageGetStorageType).

getPixbuf

imageGetPixbuf

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Maybe Pixbuf)

Returns: the displayed pixbuf, or Nothing if the image is empty

Gets the Pixbuf being displayed by the Image. The storage type of the image must be ImageTypeEmpty or ImageTypePixbuf (see imageGetStorageType). The caller of this function does not own a reference to the returned pixbuf.

getPixelSize

imageGetPixelSize

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m Int32

Returns: the pixel size used for named icons.

Gets the pixel size used for named icons.

Since: 2.6

getStock

imageGetStock

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Text, Int32)

Deprecated: (Since version 3.10)Use imageGetIconName instead.

Gets the stock icon name and size being displayed by the Image. The storage type of the image must be ImageTypeEmpty or ImageTypeStock (see imageGetStorageType). The returned string is owned by the Image and should not be freed.

getStorageType

imageGetStorageType

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m ImageType

Returns: image representation being used

Gets the type of representation being used by the Image to store image data. If the Image has no image data, the return value will be ImageTypeEmpty.

new

imageNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Image

Returns: a newly created Image widget.

Creates a new empty Image widget.

newFromAnimation

imageNewFromAnimation

Arguments

:: (HasCallStack, MonadIO m, IsPixbufAnimation a)

=> a

animation: an animation

-> m Image

Returns: a new Image widget

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

Note that the animation frames are shown using a timeout with 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.

newFromFile

imageNewFromFile

Arguments

:: (HasCallStack, MonadIO m)

=> [Char]

filename: a filename

-> m Image

Returns: a new Image

Creates a new Image displaying the file filename. If the file isn’t found or can’t be loaded, the resulting Image will display a “broken image” icon. This function never returns Nothing, it always returns a valid 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 pixbufNewFromFile to load the file yourself, then create the Image from the pixbuf. (Or for animations, use pixbufAnimationNewFromFile).

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

newFromGicon

imageNewFromGicon

Arguments

:: (HasCallStack, MonadIO m, IsIcon a)

=> a

icon: an icon

-> Int32

size: a stock icon size (IconSize)

-> m Image

Returns: a new Image displaying the themed icon

Creates a 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.

Since: 2.14

newFromIconName

imageNewFromIconName

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

iconName: an icon name or Nothing

-> Int32

size: a stock icon size (IconSize)

-> m Image

Returns: a new Image displaying the themed icon

Creates a 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.

Since: 2.6

newFromIconSet

imageNewFromIconSet

Arguments

:: (HasCallStack, MonadIO m)

=> IconSet

iconSet: a IconSet

-> Int32

size: a stock icon size (IconSize)

-> m Image

Returns: a new Image

Deprecated: (Since version 3.10)Use imageNewFromIconName instead.

Creates a 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 IconFactory, put your icon sets in the icon factory, add the icon factory to the list of default factories with iconFactoryAddDefault, and then use imageNewFromStock. This will allow themes to override the icon you ship with your application.

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

newFromPixbuf

imageNewFromPixbuf

Arguments

:: (HasCallStack, MonadIO m, IsPixbuf a)

=> Maybe a

pixbuf: a Pixbuf, or Nothing

-> m Image

Returns: a new Image

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

Note that this function just creates an Image from the pixbuf. The Image created will not react to state changes. Should you want that, you should use imageNewFromIconName.

newFromResource

imageNewFromResource

Arguments

:: (HasCallStack, MonadIO m)

=> Text

resourcePath: a resource path

-> m Image

Returns: a new Image

Creates a new Image displaying the resource file resourcePath. If the file isn’t found or can’t be loaded, the resulting Image will display a “broken image” icon. This function never returns Nothing, it always returns a valid 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 pixbufNewFromFile to load the file yourself, then create the Image from the pixbuf. (Or for animations, use pixbufAnimationNewFromFile).

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

Since: 3.4

newFromStock

imageNewFromStock

Arguments

:: (HasCallStack, MonadIO m)

=> Text

stockId: a stock icon name

-> Int32

size: a stock icon size (IconSize)

-> m Image

Returns: a new Image displaying the stock icon

Deprecated: (Since version 3.10)Use imageNewFromIconName instead.

Creates a Image displaying a stock icon. Sample stock icon names are STOCK_OPEN, 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 iconFactoryAddDefault and iconFactoryAdd.

newFromSurface

imageNewFromSurface

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Surface

surface: a Surface, or Nothing

-> m Image

Returns: a new Image

Creates a new Image displaying surface. The Image does not assume a reference to the surface; you still need to unref it if you own references. Image will add its own reference rather than adopting yours.

Since: 3.10

setFromAnimation

imageSetFromAnimation

Arguments

:: (HasCallStack, MonadIO m, IsImage a, IsPixbufAnimation b)

=> a

image: a Image

-> b

animation: the PixbufAnimation

-> m ()

Causes the Image to display the given animation (or display nothing, if you set the animation to Nothing).

setFromFile

imageSetFromFile

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Maybe [Char]

filename: a filename or Nothing

-> m ()

See imageNewFromFile for details.

setFromGicon

imageSetFromGicon

Arguments

:: (HasCallStack, MonadIO m, IsImage a, IsIcon b)

=> a

image: a Image

-> b

icon: an icon

-> Int32

size: an icon size (IconSize)

-> m ()

See imageNewFromGicon for details.

Since: 2.14

setFromIconName

imageSetFromIconName

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Maybe Text

iconName: an icon name or Nothing

-> Int32

size: an icon size (IconSize)

-> m ()

See imageNewFromIconName for details.

Since: 2.6

setFromIconSet

imageSetFromIconSet

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> IconSet

iconSet: a IconSet

-> Int32

size: a stock icon size (IconSize)

-> m ()

Deprecated: (Since version 3.10)Use imageSetFromIconName instead.

See imageNewFromIconSet for details.

setFromPixbuf

imageSetFromPixbuf

Arguments

:: (HasCallStack, MonadIO m, IsImage a, IsPixbuf b)

=> a

image: a Image

-> Maybe b

pixbuf: a Pixbuf or Nothing

-> m ()

See imageNewFromPixbuf for details.

setFromResource

imageSetFromResource

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Maybe Text

resourcePath: a resource path or Nothing

-> m ()

See imageNewFromResource for details.

setFromStock

imageSetFromStock

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Text

stockId: a stock icon name

-> Int32

size: a stock icon size (IconSize)

-> m ()

Deprecated: (Since version 3.10)Use imageSetFromIconName instead.

See imageNewFromStock for details.

setFromSurface

imageSetFromSurface

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Maybe Surface

surface: a cairo_surface_t or Nothing

-> m ()

See imageNewFromSurface for details.

Since: 3.10

setPixelSize

imageSetPixelSize

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Int32

pixelSize: the new pixel size

-> m ()

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 imageSetFromIconName.

Since: 2.6

Properties

file

No description available in the introspection data.

clearImageFile :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “file” property to Nothing. When overloading is enabled, this is equivalent to

clear #file

constructImageFile :: IsImage o => Text -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “file” property. This is rarely needed directly, but it is used by new.

getImageFile :: (MonadIO m, IsImage o) => o -> m (Maybe Text)

Get the value of the “file” property. When overloading is enabled, this is equivalent to

get image #file

setImageFile :: (MonadIO m, IsImage o) => o -> Text -> m ()

Set the value of the “file” property. When overloading is enabled, this is equivalent to

set image [ #file := value ]

gicon

The GIcon displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically.

Since: 2.14

clearImageGicon :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “gicon” property to Nothing. When overloading is enabled, this is equivalent to

clear #gicon

constructImageGicon :: (IsImage o, IsIcon a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “gicon” property. This is rarely needed directly, but it is used by new.

getImageGicon :: (MonadIO m, IsImage o) => o -> m (Maybe Icon)

Get the value of the “gicon” property. When overloading is enabled, this is equivalent to

get image #gicon

setImageGicon :: (MonadIO m, IsImage o, IsIcon a) => o -> a -> m ()

Set the value of the “gicon” property. When overloading is enabled, this is equivalent to

set image [ #gicon := value ]

iconName

The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically.

Since: 2.6

clearImageIconName :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “icon-name” property to Nothing. When overloading is enabled, this is equivalent to

clear #iconName

constructImageIconName :: IsImage o => Text -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “icon-name” property. This is rarely needed directly, but it is used by new.

getImageIconName :: (MonadIO m, IsImage o) => o -> m (Maybe Text)

Get the value of the “icon-name” property. When overloading is enabled, this is equivalent to

get image #iconName

setImageIconName :: (MonadIO m, IsImage o) => o -> Text -> m ()

Set the value of the “icon-name” property. When overloading is enabled, this is equivalent to

set image [ #iconName := value ]

iconSet

No description available in the introspection data.

clearImageIconSet :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “icon-set” property to Nothing. When overloading is enabled, this is equivalent to

clear #iconSet

constructImageIconSet :: IsImage o => IconSet -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “icon-set” property. This is rarely needed directly, but it is used by new.

getImageIconSet :: (MonadIO m, IsImage o) => o -> m (Maybe IconSet)

Get the value of the “icon-set” property. When overloading is enabled, this is equivalent to

get image #iconSet

setImageIconSet :: (MonadIO m, IsImage o) => o -> IconSet -> m ()

Set the value of the “icon-set” property. When overloading is enabled, this is equivalent to

set image [ #iconSet := value ]

iconSize

No description available in the introspection data.

constructImageIconSize :: IsImage o => Int32 -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “icon-size” property. This is rarely needed directly, but it is used by new.

getImageIconSize :: (MonadIO m, IsImage o) => o -> m Int32

Get the value of the “icon-size” property. When overloading is enabled, this is equivalent to

get image #iconSize

setImageIconSize :: (MonadIO m, IsImage o) => o -> Int32 -> m ()

Set the value of the “icon-size” property. When overloading is enabled, this is equivalent to

set image [ #iconSize := value ]

pixbuf

No description available in the introspection data.

clearImagePixbuf :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “pixbuf” property to Nothing. When overloading is enabled, this is equivalent to

clear #pixbuf

constructImagePixbuf :: (IsImage o, IsPixbuf a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “pixbuf” property. This is rarely needed directly, but it is used by new.

getImagePixbuf :: (MonadIO m, IsImage o) => o -> m (Maybe Pixbuf)

Get the value of the “pixbuf” property. When overloading is enabled, this is equivalent to

get image #pixbuf

setImagePixbuf :: (MonadIO m, IsImage o, IsPixbuf a) => o -> a -> m ()

Set the value of the “pixbuf” property. When overloading is enabled, this is equivalent to

set image [ #pixbuf := value ]

pixbufAnimation

No description available in the introspection data.

clearImagePixbufAnimation :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “pixbuf-animation” property to Nothing. When overloading is enabled, this is equivalent to

clear #pixbufAnimation

constructImagePixbufAnimation :: (IsImage o, IsPixbufAnimation a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “pixbuf-animation” property. This is rarely needed directly, but it is used by new.

getImagePixbufAnimation :: (MonadIO m, IsImage o) => o -> m (Maybe PixbufAnimation)

Get the value of the “pixbuf-animation” property. When overloading is enabled, this is equivalent to

get image #pixbufAnimation

setImagePixbufAnimation :: (MonadIO m, IsImage o, IsPixbufAnimation a) => o -> a -> m ()

Set the value of the “pixbuf-animation” property. When overloading is enabled, this is equivalent to

set image [ #pixbufAnimation := value ]

pixelSize

The "pixel-size" property can be used to specify a fixed size overriding the Image:icon-size property for images of type ImageTypeIconName.

Since: 2.6

constructImagePixelSize :: IsImage o => Int32 -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “pixel-size” property. This is rarely needed directly, but it is used by new.

getImagePixelSize :: (MonadIO m, IsImage o) => o -> m Int32

Get the value of the “pixel-size” property. When overloading is enabled, this is equivalent to

get image #pixelSize

setImagePixelSize :: (MonadIO m, IsImage o) => o -> Int32 -> m ()

Set the value of the “pixel-size” property. When overloading is enabled, this is equivalent to

set image [ #pixelSize := value ]

resource

A path to a resource file to display.

Since: 3.8

clearImageResource :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “resource” property to Nothing. When overloading is enabled, this is equivalent to

clear #resource

constructImageResource :: IsImage o => Text -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “resource” property. This is rarely needed directly, but it is used by new.

getImageResource :: (MonadIO m, IsImage o) => o -> m (Maybe Text)

Get the value of the “resource” property. When overloading is enabled, this is equivalent to

get image #resource

setImageResource :: (MonadIO m, IsImage o) => o -> Text -> m ()

Set the value of the “resource” property. When overloading is enabled, this is equivalent to

set image [ #resource := value ]

stock

No description available in the introspection data.

clearImageStock :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “stock” property to Nothing. When overloading is enabled, this is equivalent to

clear #stock

constructImageStock :: IsImage o => Text -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “stock” property. This is rarely needed directly, but it is used by new.

getImageStock :: (MonadIO m, IsImage o) => o -> m (Maybe Text)

Get the value of the “stock” property. When overloading is enabled, this is equivalent to

get image #stock

setImageStock :: (MonadIO m, IsImage o) => o -> Text -> m ()

Set the value of the “stock” property. When overloading is enabled, this is equivalent to

set image [ #stock := value ]

storageType

No description available in the introspection data.

getImageStorageType :: (MonadIO m, IsImage o) => o -> m ImageType

Get the value of the “storage-type” property. When overloading is enabled, this is equivalent to

get image #storageType

surface

No description available in the introspection data.

clearImageSurface :: (MonadIO m, IsImage o) => o -> m ()

Set the value of the “surface” property to Nothing. When overloading is enabled, this is equivalent to

clear #surface

constructImageSurface :: IsImage o => Surface -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “surface” property. This is rarely needed directly, but it is used by new.

getImageSurface :: (MonadIO m, IsImage o) => o -> m (Maybe Surface)

Get the value of the “surface” property. When overloading is enabled, this is equivalent to

get image #surface

setImageSurface :: (MonadIO m, IsImage o) => o -> Surface -> m ()

Set the value of the “surface” property. When overloading is enabled, this is equivalent to

set image [ #surface := value ]

useFallback

Whether the icon displayed in the GtkImage will use standard icon names fallback. The value of this property is only relevant for images of type ImageTypeIconName and ImageTypeGicon.

Since: 3.0

constructImageUseFallback :: IsImage o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “use-fallback” property. This is rarely needed directly, but it is used by new.

getImageUseFallback :: (MonadIO m, IsImage o) => o -> m Bool

Get the value of the “use-fallback” property. When overloading is enabled, this is equivalent to

get image #useFallback

setImageUseFallback :: (MonadIO m, IsImage o) => o -> Bool -> m ()

Set the value of the “use-fallback” property. When overloading is enabled, this is equivalent to

set image [ #useFallback := value ]