Top |
Functions
GtkWidget * | gtk_image_new () |
GtkWidget * | gtk_image_new_from_file () |
GtkWidget * | gtk_image_new_from_resource () |
GtkWidget * | gtk_image_new_from_pixbuf () |
GtkWidget * | gtk_image_new_from_paintable () |
GtkWidget * | gtk_image_new_from_icon_name () |
GtkWidget * | gtk_image_new_from_gicon () |
void | gtk_image_clear () |
void | gtk_image_set_from_file () |
void | gtk_image_set_from_resource () |
void | gtk_image_set_from_pixbuf () |
void | gtk_image_set_from_paintable () |
void | gtk_image_set_from_icon_name () |
void | gtk_image_set_from_gicon () |
GtkImageType | gtk_image_get_storage_type () |
GdkPaintable * | gtk_image_get_paintable () |
const char * | gtk_image_get_icon_name () |
GIcon * | gtk_image_get_gicon () |
void | gtk_image_set_pixel_size () |
int | gtk_image_get_pixel_size () |
void | gtk_image_set_icon_size () |
GtkIconSize | gtk_image_get_icon_size () |
Properties
char * | file | Read / Write |
GIcon * | gicon | Read / Write |
char * | icon-name | Read / Write |
GtkIconSize | icon-size | Read / Write |
GdkPaintable * | paintable | Read / Write |
int | pixel-size | Read / Write |
char * | resource | Read / Write |
GtkImageType | storage-type | Read |
gboolean | use-fallback | Read / Write |
Description
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, and then display that.
There’s a convenience function to do this, gtk_image_new_from_file()
,
used as follows:
1 2 |
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
gdk_texture_new_from_file()
, then create the GtkImage with
gtk_image_new_from_paintable()
.
Sometimes an application will want to avoid depending on external data
files, such as image files. See the documentation of GResource for details.
In this case, the “resource”, gtk_image_new_from_resource()
and
gtk_image_set_from_resource()
should be used.
GtkImage displays its image as an icon, with a size that is determined by the application. See GtkPicture 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 “icon-size” property.
Functions
gtk_image_new_from_file ()
GtkWidget *
gtk_image_new_from_file (const char *filename
);
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 NULL
,
it always returns a valid GtkImage widget.
If you need to detect failures to load the file, use
gdk_texture_new_from_file()
to load the file yourself, then create
the GtkImage from the texture.
The storage type (gtk_image_get_storage_type()
) of the returned
image is not defined, it will be whatever is appropriate for
displaying the file.
gtk_image_new_from_resource ()
GtkWidget *
gtk_image_new_from_resource (const char *resource_path
);
Creates a new GtkImage displaying the resource file resource_path
. If the file
isn’t found or can’t be loaded, the resulting GtkImage will
display a “broken image” icon. This function never returns NULL
,
it always returns a valid GtkImage widget.
If you need to detect failures to load the file, use
gdk_pixbuf_new_from_file()
to load the file yourself, then create
the GtkImage from the pixbuf.
The storage type (gtk_image_get_storage_type()
) of the returned
image is not defined, it will be whatever is appropriate for
displaying the file.
gtk_image_new_from_pixbuf ()
GtkWidget *
gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf
);
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 gtk_image_new_from_paintable()
, 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 gtk_image_new_from_icon_name()
.
gtk_image_new_from_paintable ()
GtkWidget *
gtk_image_new_from_paintable (GdkPaintable *paintable
);
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.
gtk_image_new_from_icon_name ()
GtkWidget *
gtk_image_new_from_icon_name (const char *icon_name
);
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.
Note: Before 3.94, this function was taking an extra icon size
argument. See gtk_image_set_icon_size()
for another way to set
the icon size.
gtk_image_new_from_gicon ()
GtkWidget *
gtk_image_new_from_gicon (GIcon *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.
Note: Before 3.94, this function was taking an extra icon size
argument. See gtk_image_set_icon_size()
for another way to set
the icon size.
gtk_image_set_from_file ()
void gtk_image_set_from_file (GtkImage *image
,const char *filename
);
See gtk_image_new_from_file()
for details.
gtk_image_set_from_resource ()
void gtk_image_set_from_resource (GtkImage *image
,const char *resource_path
);
See gtk_image_new_from_resource()
for details.
gtk_image_set_from_pixbuf ()
void gtk_image_set_from_pixbuf (GtkImage *image
,GdkPixbuf *pixbuf
);
See gtk_image_new_from_pixbuf()
for details.
Note: This is a helper for gtk_image_set_from_paintable()
, and you can't
get back the exact pixbuf once this is called, only a paintable.
gtk_image_set_from_paintable ()
void gtk_image_set_from_paintable (GtkImage *image
,GdkPaintable *paintable
);
See gtk_image_new_from_paintable()
for details.
gtk_image_set_from_icon_name ()
void gtk_image_set_from_icon_name (GtkImage *image
,const char *icon_name
);
See gtk_image_new_from_icon_name()
for details.
Note: Before 3.94, this function was taking an extra icon size
argument. See gtk_image_set_icon_size()
for another way to set
the icon size.
gtk_image_set_from_gicon ()
void gtk_image_set_from_gicon (GtkImage *image
,GIcon *icon
);
See gtk_image_new_from_gicon()
for details.
Note: Before 3.94, this function was taking an extra icon size
argument. See gtk_image_set_icon_size()
for another way to set
the icon size.
gtk_image_get_storage_type ()
GtkImageType
gtk_image_get_storage_type (GtkImage *image
);
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 GTK_IMAGE_EMPTY
.
gtk_image_get_paintable ()
GdkPaintable *
gtk_image_get_paintable (GtkImage *image
);
Gets the image GdkPaintable being displayed by the GtkImage.
The storage type of the image must be GTK_IMAGE_EMPTY
or
GTK_IMAGE_PAINTABLE
(see gtk_image_get_storage_type()
).
The caller of this function does not own a reference to the
returned paintable.
gtk_image_get_icon_name ()
const char *
gtk_image_get_icon_name (GtkImage *image
);
Gets the icon name and size being displayed by the GtkImage.
The storage type of the image must be GTK_IMAGE_EMPTY
or
GTK_IMAGE_ICON_NAME
(see gtk_image_get_storage_type()
).
The returned string is owned by the GtkImage 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 gtk_image_get_icon_size()
for a way to get the icon size.
gtk_image_get_gicon ()
GIcon *
gtk_image_get_gicon (GtkImage *image
);
Gets the GIcon and size being displayed by the GtkImage.
The storage type of the image must be GTK_IMAGE_EMPTY
or
GTK_IMAGE_GICON
(see gtk_image_get_storage_type()
).
The caller of this function does not own a reference to the
returned GIcon.
Note: This function was changed in 3.94 not to use out parameters
anymore, but return the GIcon directly. See gtk_image_get_icon_size()
for a way to get the icon size.
gtk_image_set_pixel_size ()
void gtk_image_set_pixel_size (GtkImage *image
,int pixel_size
);
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
gtk_image_set_from_icon_name()
.
gtk_image_get_pixel_size ()
int
gtk_image_get_pixel_size (GtkImage *image
);
Gets the pixel size used for named icons.
gtk_image_set_icon_size ()
void gtk_image_set_icon_size (GtkImage *image
,GtkIconSize icon_size
);
Suggests an icon size to the theme for named icons.
gtk_image_get_icon_size ()
GtkIconSize
gtk_image_get_icon_size (GtkImage *image
);
Gets the icon size used by the image
when rendering icons.
Types and Values
enum GtkImageType
Describes the image data representation used by a GtkImage. If you
want to get the image from the widget, you can only get the
currently-stored representation. e.g. if the
gtk_image_get_storage_type()
returns GTK_IMAGE_PAINTABLE, then you can
call gtk_image_get_paintable()
. For empty images, you can request any
storage type (call any of the "get" functions), but they will all
return NULL
values.
Members
there is no image displayed by the widget |
||
the widget contains a named icon |
||
the widget contains a GIcon |
||
the widget contains a GdkPaintable |
Property Details
The “file”
property
“file” char *
Filename to load and display.
Owner: GtkImage
Flags: Read / Write
Default value: NULL
The “gicon”
property
“gicon” GIcon *
The GIcon displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically.
Owner: GtkImage
Flags: Read / Write
The “icon-name”
property
“icon-name” char *
The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically.
Owner: GtkImage
Flags: Read / Write
Default value: NULL
The “icon-size”
property
“icon-size” GtkIconSize
Symbolic size to use for icon set or named icon.
Owner: GtkImage
Flags: Read / Write
Default value: GTK_ICON_SIZE_INHERIT
The “paintable”
property
“paintable” GdkPaintable *
A GdkPaintable to display.
Owner: GtkImage
Flags: Read / Write
The “pixel-size”
property
“pixel-size” int
The "pixel-size" property can be used to specify a fixed size
overriding the “icon-size” property for images of type
GTK_IMAGE_ICON_NAME
.
Owner: GtkImage
Flags: Read / Write
Allowed values: >= -1
Default value: -1
The “resource”
property
“resource” char *
A path to a resource file to display.
Owner: GtkImage
Flags: Read / Write
Default value: NULL
The “storage-type”
property
“storage-type” GtkImageType
The representation being used for image data.
Owner: GtkImage
Flags: Read
Default value: GTK_IMAGE_EMPTY
The “use-fallback”
property
“use-fallback” gboolean
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 GTK_IMAGE_ICON_NAME
and GTK_IMAGE_GICON
.
Owner: GtkImage
Flags: Read / Write
Default value: FALSE