gi-gtk-3.0.26: Gtk bindings

Copyright Will Thompson Iñaki García Etxebarria and Jonas Platte LGPL-2.1 Iñaki García Etxebarria (garetxe@gmail.com) None Haskell2010

GI.Gtk.Objects.Image

Description

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 ();

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.

Synopsis

# Exported types

newtype Image Source #

Memory-managed wrapper type.

Constructors

 Image (ManagedPtr Image)
Instances
 Source # Instance detailsDefined in GI.Gtk.Objects.Image Methods Source # Instance detailsDefined in GI.Gtk.Objects.Image Source # Instance detailsDefined in GI.Gtk.Objects.Image Source # Instance detailsDefined in GI.Gtk.Objects.Image Source # Instance detailsDefined in GI.Gtk.Objects.Image Source # Instance detailsDefined in GI.Gtk.Objects.Image Source # Instance detailsDefined in GI.Gtk.Objects.Image

class GObject o => IsImage o Source #

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

Instances
 (GObject a, (UnknownAncestorError Image a :: Constraint)) => IsImage a Source # Instance detailsDefined in GI.Gtk.Objects.Image Source # Instance detailsDefined in GI.Gtk.Objects.Image

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

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

A convenience alias for Nothing :: Maybe Image.

# Methods

## clear

Arguments

 :: (HasCallStack, MonadIO m, IsImage a) => a image: a Image -> m ()

Resets the image to be empty.

Since: 2.8

## getAnimation

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

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

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

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

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

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

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

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

Arguments

 :: (HasCallStack, MonadIO m) => m Image Returns: a newly created Image widget.

Creates a new empty Image widget.

## newFromAnimation

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

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

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

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

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

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

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

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

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

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

Arguments

 :: (HasCallStack, MonadIO m, IsImage a) => a image: a Image -> Maybe [Char] filename: a filename or Nothing -> m ()

See imageNewFromFile for details.

## setFromGicon

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

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

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

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

Arguments

 :: (HasCallStack, MonadIO m, IsImage a) => a image: a Image -> Maybe Text resourcePath: a resource path or Nothing -> m ()

See imageNewFromResource for details.

## setFromStock

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

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

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 () Source #

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

clear #file


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) Source #

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 () Source #

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 () Source #

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) Source #

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) Source #

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 () Source #

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 () Source #

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

clear #iconName


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) Source #

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 () Source #

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 () Source #

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

clear #iconSet


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) Source #

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 () Source #

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.

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

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 () Source #

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 () Source #

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) Source #

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) Source #

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 () Source #

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 () Source #

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

clear #pixbufAnimation


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) Source #

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 () Source #

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

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

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 () Source #

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 () Source #

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

clear #resource


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) Source #

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 () Source #

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 () Source #

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

clear #stock


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) Source #

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 () Source #

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

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 () Source #

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

clear #surface


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) Source #

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 () Source #

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

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

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 () Source #

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

set image [ #useFallback := value ]