Struct gtk4::Image

#[repr(transparent)]
pub struct Image { /* private fields */ }

The Image widget displays an image.

Various kinds of object can be displayed as an image; most typically, you would load a gdk::Texture from a file, using the convenience function from_file(), for instance:

⚠️ The following code is in c ⚠️

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 gdk::Texture::from_file(), then create the Image with from_paintable().

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, property::Image::resource, from_resource(), and set_from_resource() should be used.

Image 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

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

Accessibility

Image uses the GTK_ACCESSIBLE_ROLE_IMG role.

Implements

WidgetExt, glib::ObjectExt, AccessibleExt, BuildableExt, ConstraintTargetExt, WidgetExtManual, AccessibleExtManual

Implementations

impl Image

pub fn new() -> Image

Creates a new empty Image widget.

Returns

a newly created Image widget.

pub fn from_file(filename: impl AsRef<Path>) -> 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 None, it always returns a valid Image widget.

If you need to detect failures to load the file, use gdk::Texture::from_file() to load the file yourself, then create the Image from the texture.

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

filename

a filename

Returns

a new Image

pub fn from_gicon(icon: &impl IsA<Icon>) -> Image

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.

icon

an icon

Returns

a new Image displaying the themed icon

pub fn from_icon_name(icon_name: &str) -> Image

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.

icon_name

an icon name

Returns

a new Image displaying the themed icon

pub fn from_paintable(paintable: Option<&impl IsA<Paintable>>) -> 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.

paintable

a gdk::Paintable

Returns

a new Image

pub fn from_pixbuf(pixbuf: Option<&Pixbuf>) -> 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 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 Image from the pixbuf. The Image created will not react to state changes. Should you want that, you should use from_icon_name().

pixbuf

a gdk_pixbuf::Pixbuf

Returns

a new Image

pub fn from_resource(resource_path: &str) -> Image

Creates a new Image displaying the resource file @resource_path.

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

If you need to detect failures to load the file, use gdk_pixbuf::Pixbuf::from_file() to load the file yourself, then create the Image from the pixbuf.

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

resource_path

a resource path

Returns

a new Image

pub fn builder() -> ImageBuilder

Creates a new builder-pattern struct instance to construct Image objects.

This method returns an instance of ImageBuilder which can be used to create Image objects.

pub fn clear(&self)

Resets the image to be empty.

pub fn gicon(&self) -> Option<Icon>

Gets the GIcon being displayed by the Image.

The storage type of the image must be ImageType::Empty or ImageType::Gicon (see storage_type()). The caller of this function does not own a reference to the returned GIcon.

Returns

a GIcon

pub fn icon_name(&self) -> Option<GString>

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

The storage type of the image must be ImageType::Empty or ImageType::IconName (see storage_type()). The returned string is owned by the Image and should not be freed.

Returns

the icon name

pub fn icon_size(&self) -> IconSize

Gets the icon size used by the @self when rendering icons.

Returns

the image size used by icons

pub fn paintable(&self) -> Option<Paintable>

Gets the image gdk::Paintable being displayed by the Image.

The storage type of the image must be ImageType::Empty or ImageType::Paintable (see storage_type()). The caller of this function does not own a reference to the returned paintable.

Returns

the displayed paintable

pub fn pixel_size(&self) -> i32

Gets the pixel size used for named icons.

Returns

the pixel size used for named icons.

pub fn storage_type(&self) -> ImageType

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 ImageType::Empty.

Returns

image representation being used

pub fn set_from_file(&self, filename: Option<impl AsRef<Path>>)

Sets a Image to show a file.

See from_file() for details.

filename

a filename

pub fn set_from_gicon(&self, icon: &impl IsA<Icon>)

Sets a Image to show a GIcon.

See from_gicon() for details.

icon

an icon

pub fn set_from_icon_name(&self, icon_name: Option<&str>)

Sets a Image to show a named icon.

See from_icon_name() for details.

icon_name

an icon name

pub fn set_from_paintable(&self, paintable: Option<&impl IsA<Paintable>>)

Sets a Image to show a gdk::Paintable.

See from_paintable() for details.

paintable

a gdk::Paintable

pub fn set_from_pixbuf(&self, pixbuf: Option<&Pixbuf>)

Sets a Image to show a gdk_pixbuf::Pixbuf.

See from_pixbuf() for details.

Note: This is a helper for set_from_paintable(), and you can’t get back the exact pixbuf once this is called, only a paintable.

pixbuf

a gdk_pixbuf::Pixbuf or NULL

pub fn set_from_resource(&self, resource_path: Option<&str>)

Sets a Image to show a resource.

See from_resource() for details.

resource_path

a resource path

pub fn set_icon_size(&self, icon_size: IconSize)

Suggests an icon size to the theme for named icons.

icon_size

the new icon size

pub fn set_pixel_size(&self, pixel_size: i32)

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 set_from_icon_name().

pixel_size

the new pixel size

pub fn file(&self) -> Option<GString>

The `GFile to display.

pub fn set_file(&self, file: Option<&str>)

The `GFile to display.

pub fn set_gicon<P: IsA<Icon>>(&self, gicon: Option<&P>)

The GIcon displayed in the GtkImage.

For themed icons, If the icon theme is changed, the image will be updated automatically.

pub fn set_icon_name(&self, icon_name: Option<&str>)

The name of the icon in the icon theme.

If the icon theme is changed, the image will be updated automatically.

pub fn set_paintable<P: IsA<Paintable>>(&self, paintable: Option<&P>)

The gdk::Paintable to display.

pub fn resource(&self) -> Option<GString>

A path to a resource file to display.

pub fn set_resource(&self, resource: Option<&str>)

A path to a resource file to display.

pub fn uses_fallback(&self) -> bool

Whether the icon displayed in the Image will use standard icon names fallback.

The value of this property is only relevant for images of type ImageType::IconName and ImageType::Gicon.

pub fn set_use_fallback(&self, use_fallback: bool)

Whether the icon displayed in the Image will use standard icon names fallback.

The value of this property is only relevant for images of type ImageType::IconName and ImageType::Gicon.

pub fn connect_file_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_gicon_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_icon_name_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_icon_size_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_paintable_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_pixel_size_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_resource_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_storage_type_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

pub fn connect_use_fallback_notify<F: Fn(&Self) + 'static>(
    &self,
    f: F
) -> SignalHandlerId

Trait Implementations

impl Clone for Image

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Image

fn default() -> Self

Returns the “default value” for a type.

impl Display for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Image

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for Image

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl ParentClassIs for Image

type Parent = Widget

impl<OT: ObjectType> PartialEq<OT> for Image

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<OT: ObjectType> PartialOrd<OT> for Image

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Image

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Image

impl IsA<Accessible> for Image

impl IsA<Buildable> for Image

impl IsA<ConstraintTarget> for Image

impl IsA<Widget> for Image