GI.Gtk.Objects.Picture

The Picture widget displays a Paintable. Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display that, there’s a convenience function to do this:

C code

 GtkWidget *widget;
 widget = gtk_picture_new_for_filename ("myfile.png");

If the file isn’t loaded successfully, the picture 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 Picture with pictureNewForPaintable.

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, pictureNewForResource and pictureSetResource should be used.

GtkPicture displays an image at its natural size. See Image if you want to display a fixed-size image, such as an icon.

Sizing the paintable

You can influence how the paintable is displayed inside the Picture. By turning off Picture:keep-aspect-ratio you can allow the paintable to get stretched. Picture:can-shrink can be unset to make sure that paintables are never made smaller than their ideal size - but be careful if you do not know the size of the paintable in use (like when displaying user-loaded images). This can easily cause the picture to grow larger than the screen. And Widget:halign and Widget:valign can be used to make sure the paintable doesn't fill all available space but is instead displayed at its original size.

CSS nodes

GtkPicture has a single CSS node with the name picture.

Accessibility

GtkPicture uses the GTK_ACCESSIBLE_ROLE_IMG role.

Exported types

newtype Picture

Memory-managed wrapper type.

Constructors

Picture (ManagedPtr Picture)

Instances

Eq Picture

Defined in GI.Gtk.Objects.Picture

Methods

(==) :: Picture -> Picture -> Bool

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

GObject Picture

Defined in GI.Gtk.Objects.Picture

ManagedPtrNewtype Picture

Defined in GI.Gtk.Objects.Picture

Methods

toManagedPtr :: Picture -> ManagedPtr Picture

TypedObject Picture

Defined in GI.Gtk.Objects.Picture

Methods

glibType :: IO GType

HasParentTypes Picture

Defined in GI.Gtk.Objects.Picture

IsGValue (Maybe Picture)

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

Defined in GI.Gtk.Objects.Picture

Methods

gvalueGType_ :: IO GType

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

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

type ParentTypes Picture

Defined in GI.Gtk.Objects.Picture

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

class (GObject o, IsDescendantOf Picture o) => IsPicture o

Type class for types which can be safely cast to Picture, for instance with toPicture.

Instances

(GObject o, IsDescendantOf Picture o) => IsPicture o

Defined in GI.Gtk.Objects.Picture

toPicture :: (MonadIO m, IsPicture o) => o -> m Picture

Cast to Picture, 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, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, 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, updateProperty, updateRelation, updateState, watchClosure.

Getters

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

Setters

setAlternativeText, setCanFocus, setCanShrink, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setFile, setFilename, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setKeepAspectRatio, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setPaintable, setParent, setPixbuf, setProperty, setReceivesDefault, setResource, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

getAlternativeText

pictureGetAlternativeText

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> m (Maybe Text)

Returns: the alternative textual description of self.

Gets the alternative textual description of the picture or returns Nothing if the picture cannot be described textually.

getCanShrink

pictureGetCanShrink

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> m Bool

Returns: True if the picture can be made smaller than its contents

Gets the value set via pictureSetCanShrink.

getFile

pictureGetFile

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> m (Maybe File)

Returns: The File displayed by self.

Gets the File currently displayed if self is displaying a file. If self is not displaying a file, for example when pictureSetPaintable was used, then Nothing is returned.

getKeepAspectRatio

pictureGetKeepAspectRatio

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> m Bool

Returns: True if the self tries to keep the contents' aspect ratio

Gets the value set via pictureSetKeepAspectRatio.

getPaintable

pictureGetPaintable

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> m (Maybe Paintable)

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

Gets the Paintable being displayed by the Picture.

new

pictureNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Picture

Returns: a newly created Picture widget.

Creates a new empty Picture widget.

newForFile

pictureNewForFile

Arguments

:: (HasCallStack, MonadIO m, IsFile a)

=> Maybe a

file: a File

-> m Picture

Returns: a new Picture

Creates a new Picture displaying the given file. If the file isn’t found or can’t be loaded, the resulting Picture be empty.

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

newForFilename

pictureNewForFilename

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe [Char]

filename: a filename

-> m Picture

Returns: a new Picture

Creates a new Picture displaying the file filename.

This is a utility function that calls pictureNewForFile. See that function for details.

newForPaintable

pictureNewForPaintable

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> Maybe a

paintable: a Paintable, or Nothing

-> m Picture

Returns: a new Picture

Creates a new Picture displaying paintable.

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

newForPixbuf

pictureNewForPixbuf

Arguments

:: (HasCallStack, MonadIO m, IsPixbuf a)

=> Maybe a

pixbuf: a Pixbuf, or Nothing

-> m Picture

Returns: a new Picture

Creates a new Picture displaying pixbuf.

This is a utility function that calls pictureNewForPaintable, See that function for details.

The pixbuf must not be modified after passing it to this function.

newForResource

pictureNewForResource

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

resourcePath: resource path to play back

-> m Picture

Returns: a new Picture

Creates a new Picture displaying the resource at resourcePath.

This is a utility function that calls pictureNewForFile. See that function for details.

setAlternativeText

pictureSetAlternativeText

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> Maybe Text

alternativeText: a textual description of the contents

-> m ()

Sets an alternative textual description for the picture contents. It is equivalent to the "alt" attribute for images on websites.

This text will be made available to accessibility tools.

If the picture cannot be described textually, set this property to Nothing.

setCanShrink

pictureSetCanShrink

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> Bool

canShrink: if self can be made smaller than its contents

-> m ()

If set to True, the self can be made smaller than its contents. The contents will then be scaled down when rendering.

If you want to still force a minimum size manually, consider using widgetSetSizeRequest.

Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via widgetSetHalign and widgetSetValign.

setFile

pictureSetFile

Arguments

:: (HasCallStack, MonadIO m, IsPicture a, IsFile b)

=> a

self: a Picture

-> Maybe b

file: a GFile or Nothing

-> m ()

Makes self load and display file.

See pictureNewForFile for details.

setFilename

pictureSetFilename

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> Maybe Text

filename: the filename to play

-> m ()

Makes self load and display the given filename.

This is a utility function that calls pictureSetFile.

setKeepAspectRatio

pictureSetKeepAspectRatio

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> Bool

keepAspectRatio: whether to keep aspect ratio

-> m ()

If set to True, the self will render its contents according to their aspect ratio. That means that empty space may show up at the top/bottom or left/right of self.

If set to False or if the contents provide no aspect ratio, the contents will be stretched over the picture's whole area.

setPaintable

pictureSetPaintable

Arguments

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

=> a

self: a Picture

-> Maybe b

paintable: a Paintable or Nothing

-> m ()

Makes self display the given paintable. If paintable is Nothing, nothing will be displayed.

See pictureNewForPaintable for details.

setPixbuf

pictureSetPixbuf

Arguments

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

=> a

self: a Picture

-> Maybe b

pixbuf: a Pixbuf or Nothing

-> m ()

See pictureNewForPixbuf for details.

This is a utility function that calls pictureSetPaintable,

setResource

pictureSetResource

Arguments

:: (HasCallStack, MonadIO m, IsPicture a)

=> a

self: a Picture

-> Maybe Text

resourcePath: the resource to set

-> m ()

Makes self load and display the resource at the given resourcePath.

This is a utility function that calls pictureSetFile,

Properties

alternativeText

The alternative textual description for the picture.

clearPictureAlternativeText :: (MonadIO m, IsPicture o) => o -> m ()

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

clear #alternativeText

constructPictureAlternativeText :: (IsPicture o, MonadIO m) => Text -> m (GValueConstruct o)

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

getPictureAlternativeText :: (MonadIO m, IsPicture o) => o -> m (Maybe Text)

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

get picture #alternativeText

setPictureAlternativeText :: (MonadIO m, IsPicture o) => o -> Text -> m ()

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

set picture [ #alternativeText := value ]

canShrink

If the Picture can be made smaller than the self it contains.

constructPictureCanShrink :: (IsPicture o, MonadIO m) => Bool -> m (GValueConstruct o)

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

getPictureCanShrink :: (MonadIO m, IsPicture o) => o -> m Bool

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

get picture #canShrink

setPictureCanShrink :: (MonadIO m, IsPicture o) => o -> Bool -> m ()

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

set picture [ #canShrink := value ]

file

The File that is displayed or Nothing if none.

clearPictureFile :: (MonadIO m, IsPicture o) => o -> m ()

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

clear #file

constructPictureFile :: (IsPicture o, MonadIO m, IsFile a) => a -> m (GValueConstruct o)

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

getPictureFile :: (MonadIO m, IsPicture o) => o -> m (Maybe File)

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

get picture #file

setPictureFile :: (MonadIO m, IsPicture o, IsFile a) => o -> a -> m ()

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

set picture [ #file := value ]

keepAspectRatio

Whether the GtkPicture will render its contents trying to preserve the aspect ratio of the contents.

constructPictureKeepAspectRatio :: (IsPicture o, MonadIO m) => Bool -> m (GValueConstruct o)

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

getPictureKeepAspectRatio :: (MonadIO m, IsPicture o) => o -> m Bool

Get the value of the “keep-aspect-ratio” property. When overloading is enabled, this is equivalent to

get picture #keepAspectRatio

setPictureKeepAspectRatio :: (MonadIO m, IsPicture o) => o -> Bool -> m ()

Set the value of the “keep-aspect-ratio” property. When overloading is enabled, this is equivalent to

set picture [ #keepAspectRatio := value ]

paintable

The Paintable to be displayed by this Picture.

clearPicturePaintable :: (MonadIO m, IsPicture o) => o -> m ()

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

clear #paintable

constructPicturePaintable :: (IsPicture 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.

getPicturePaintable :: (MonadIO m, IsPicture o) => o -> m (Maybe Paintable)

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

get picture #paintable

setPicturePaintable :: (MonadIO m, IsPicture o, IsPaintable a) => o -> a -> m ()

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

set picture [ #paintable := value ]