GI.Gtk.Objects.Image

The GtkImage widget displays an image.

Various kinds of object can be displayed as an image; most typically, you would load a GdkTexture from a file, using the convenience function imageNewFromFile, for instance:

c code

GtkWidget *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 GtkImage with imageNewFromPaintable.

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

GtkImage displays its image as an icon, with a size that is determined by the application. See Picture if you want to show an image at is actual size.

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:iconSize property.

Accessibility

GtkImage uses the GTK_ACCESSIBLE_ROLE_IMG role.

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

GObject Image

Defined in GI.Gtk.Objects.Image

ManagedPtrNewtype Image

Defined in GI.Gtk.Objects.Image

Methods

toManagedPtr :: Image -> ManagedPtr Image

TypedObject Image

Defined in GI.Gtk.Objects.Image

Methods

glibType :: IO GType

HasParentTypes Image

Defined in GI.Gtk.Objects.Image

IsGValue (Maybe Image)

Convert Image to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.Image

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Image -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Image)

type ParentTypes Image

Defined in GI.Gtk.Objects.Image

type ParentTypes Image = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

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.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, clear, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanTarget, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getGicon, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getIconName, getIconSize, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPaintable, getPangoContext, getParent, getPixelSize, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStorageType, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

Setters

setAccessibleParent, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setFromFile, setFromGicon, setFromIconName, setFromPaintable, setFromPixbuf, setFromResource, setHalign, setHasTooltip, setHexpand, setHexpandSet, setIconSize, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setPixelSize, setProperty, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

clear

imageClear

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a GtkImage

-> m ()

Resets the image to be empty.

getGicon

imageGetGicon

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a GtkImage

-> m (Maybe Icon)

Returns: a GIcon

Gets the GIcon being displayed by the GtkImage.

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

getIconName

imageGetIconName

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a GtkImage

-> m (Maybe Text)

Returns: the icon name

Gets the icon name and size being displayed by the GtkImage.

The storage type of the image must be ImageTypeEmpty or ImageTypeIconName (see imageGetStorageType). The returned string is owned by the GtkImage and should not be freed.

getIconSize

imageGetIconSize

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a GtkImage

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

-> m (Maybe Paintable)

Returns: the displayed paintable

Gets the image GdkPaintable being displayed by the GtkImage.

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 GtkImage

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

-> m ImageType

Returns: image representation being used

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

new

imageNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Image

Returns: a newly created GtkImage widget.

Creates a new empty GtkImage widget.

newFromFile

imageNewFromFile

Arguments

:: (HasCallStack, MonadIO m)

=> [Char]

filename: a filename

-> m Image

Returns: a new GtkImage

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 Nothing, it always returns a valid GtkImage widget.

If you need to detect failures to load the file, use textureNewFromFile to load the file yourself, then create the GtkImage from the texture.

The storage type (see 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 GtkImage displaying the themed icon

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

imageNewFromIconName

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

iconName: an icon name

-> m Image

Returns: a new GtkImage displaying the themed icon

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.

newFromPaintable

imageNewFromPaintable

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> Maybe a

paintable: a GdkPaintable

-> m Image

Returns: a new GtkImage

Creates a new GtkImage displaying paintable.

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

The GtkImage 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 GdkPixbuf

-> m Image

Returns: a new GtkImage

Deprecated: (Since version 4.12)Use imageNewFromPaintable andtextureNewForPixbuf instead

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.

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

Note that this function just creates an GtkImage from the pixbuf. The GtkImage 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 GtkImage

Creates a new GtkImage displaying the resource file resourcePath.

If the file isn’t found or can’t be loaded, the resulting GtkImage will display a “broken image” icon. This function never returns Nothing, it always returns a valid GtkImage widget.

If you need to detect failures to load the file, use pixbufNewFromFile to load the file yourself, then create the GtkImage from the pixbuf.

The storage type (see 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 GtkImage

-> Maybe [Char]

filename: a filename

-> m ()

Sets a GtkImage to show a file.

See imageNewFromFile for details.

setFromGicon

imageSetFromGicon

Arguments

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

=> a

image: a GtkImage

-> b

icon: an icon

-> m ()

Sets a GtkImage to show a GIcon.

See imageNewFromGicon for details.

setFromIconName

imageSetFromIconName

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a GtkImage

-> Maybe Text

iconName: an icon name

-> m ()

Sets a GtkImage to show a named icon.

See imageNewFromIconName for details.

setFromPaintable

imageSetFromPaintable

Arguments

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

=> a

image: a GtkImage

-> Maybe b

paintable: a GdkPaintable

-> m ()

Sets a GtkImage to show a GdkPaintable.

See imageNewFromPaintable for details.

setFromPixbuf

imageSetFromPixbuf

Arguments

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

=> a

image: a GtkImage

-> Maybe b

pixbuf: a GdkPixbuf or NULL

-> m ()

Deprecated: (Since version 4.12)Use imageSetFromPaintable instead

Sets a GtkImage to show a GdkPixbuf.

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 GtkImage

-> Maybe Text

resourcePath: a resource path

-> m ()

Sets a GtkImage to show a resource.

See imageNewFromResource for details.

setIconSize

imageSetIconSize

Arguments

:: (HasCallStack, MonadIO m, IsImage a)

=> a

image: a GtkImage

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

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

A path to the file to display.

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, MonadIO m) => Text -> m (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, MonadIO m, IsIcon a) => a -> m (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, MonadIO m) => Text -> m (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

The symbolic size to display icons at.

constructImageIconSize :: (IsImage o, MonadIO m) => IconSize -> m (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

The GdkPaintable to display.

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, MonadIO m, IsPaintable a) => a -> m (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 size in pixels to display icons at.

If set to a value != -1, this property overrides the Image:iconSize property for images of type GTK_IMAGE_ICON_NAME.

constructImagePixelSize :: (IsImage o, MonadIO m) => Int32 -> m (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, MonadIO m) => Text -> m (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

The representation being used for image 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, MonadIO m) => Bool -> m (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 ]