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 Texture 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 textureNewFromFile, then create the Image with imageNewFromPaintable.

Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of Resource for details. In this case, the Image:resource, imageNewFromResource and imageSetFromResource should be used.

CSS nodes

GtkImage has a single CSS node with the name image. The style classes .normal-icons or .large-icons may appear, depending on the Image:icon-size property.

Exported types

newtype Image

Memory-managed wrapper type.

Constructors

Image (ManagedPtr Image)

Instances

Eq Image

Defined in GI.Gtk.Objects.Image

Methods

(==) :: Image -> Image -> Bool

(/=) :: Image -> Image -> Bool

IsGValue Image

Convert Image to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Objects.Image

Methods

toGValue :: Image -> IO GValue

fromGValue :: GValue -> IO Image

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 = '[Widget, Object, ImplementorIface, Buildable]

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

Overloaded methods

clear

imageClear

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m ()

Resets the image to be empty.

getGicon

imageGetGicon

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Maybe Icon)

Returns: a Icon, or Nothing

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.

Note: This function was changed in 3.94 not to use out parameters anymore, but return the GIcon directly. See imageGetIconSize for a way to get the icon size.

getIconName

imageGetIconName

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Maybe Text)

Returns: the icon name, or Nothing

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.

Note: This function was changed in 3.94 not to use out parameters anymore, but return the icon name directly. See imageGetIconSize for a way to get the icon size.

getIconSize

imageGetIconSize

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m IconSize

Returns: the image size used by icons

Gets the icon size used by the image when rendering icons.

getPaintable

imageGetPaintable

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> m (Maybe Paintable)

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

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

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.

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.

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 you need to detect failures to load the file, use textureNewFromFile to load the file yourself, then create the Image from the texture.

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

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

Note: Before 3.94, this function was taking an extra icon size argument. See imageSetIconSize for another way to set the icon size.

newFromIconName

imageNewFromIconName

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

iconName: an icon name or Nothing

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

Note: Before 3.94, this function was taking an extra icon size argument. See imageSetIconSize for another way to set the icon size.

newFromPaintable

imageNewFromPaintable

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> Maybe a

paintable: a Paintable, or Nothing

-> m Image

Returns: a new Image

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

The Image will track changes to the paintable and update its size and contents in response to it.

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.

This is a helper for gtk_image_new_from_texture(), and you can't get back the exact pixbuf once this is called, only a texture.

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 you need to detect failures to load the file, use pixbufNewFromFile to load the file yourself, then create the Image from the pixbuf.

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

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

-> m ()

See imageNewFromGicon for details.

Note: Before 3.94, this function was taking an extra icon size argument. See imageSetIconSize for another way to set the icon size.

setFromIconName

imageSetFromIconName

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> Maybe Text

iconName: an icon name or Nothing

-> m ()

See imageNewFromIconName for details.

Note: Before 3.94, this function was taking an extra icon size argument. See imageSetIconSize for another way to set the icon size.

setFromPaintable

imageSetFromPaintable

Arguments

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

=> a

image: a Image

-> Maybe b

paintable: a Paintable or Nothing

-> m ()

See imageNewFromPaintable 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.

Note: This is a helper for imageSetFromPaintable, and you can't get back the exact pixbuf once this is called, only a paintable.

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.

setIconSize

imageSetIconSize

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a Image

-> IconSize

iconSize: the new icon size

-> m ()

Suggests an icon size to the theme for named icons.

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.

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.

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.

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 ]

iconSize

No description available in the introspection data.

constructImageIconSize :: IsImage o => IconSize -> 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 IconSize

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 -> IconSize -> m ()

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

set image [ #iconSize := value ]

paintable

No description available in the introspection data.

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

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

clear #paintable

constructImagePaintable :: (IsImage o, IsPaintable a) => a -> IO (GValueConstruct o)

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

getImagePaintable :: (MonadIO m, IsImage o) => o -> m (Maybe Paintable)

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

get image #paintable

setImagePaintable :: (MonadIO m, IsImage o, IsPaintable a) => o -> a -> m ()

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

set image [ #paintable := 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.

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.

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 ]

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

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.

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 ]