Struct gtk4::Image

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, 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 icon-size property.

Accessibility

Image uses the GTK_ACCESSIBLE_ROLE_IMG role.

Properties

file

A path to the file to display.

Readable | Writeable

gicon

The GIcon displayed in the GtkImage.

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

Readable | Writeable

icon-name

The name of the icon in the icon theme.

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

Readable | Writeable

icon-size

The symbolic size to display icons at.

Readable | Writeable

paintable

The gdk::Paintable to display.

Readable | Writeable

pixel-size

The size in pixels to display icons at.

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

Readable | Writeable

resource

A path to a resource file to display.

Readable | Writeable

storage-type

The representation being used for image data.

Readable

use-fallback

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.

Readable | Writeable

Widget

can-focus

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

can-target

Whether the widget can receive pointer events.

Readable | Writeable

css-classes

A list of css classes applied to this widget.

Readable | Writeable

css-name

The name of this widget in the CSS tree.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable | Construct Only

cursor

The cursor used by @widget.

Readable | Writeable

focus-on-click

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Readable | Writeable

focusable

Whether this widget itself will accept the input focus.

Readable | Writeable

halign

How to distribute horizontal space if widget gets extra space.

Readable | Writeable

has-default

Whether the widget is the default widget.

Readable

has-focus

Whether the widget has the input focus.

Readable

has-tooltip

Enables or disables the emission of the ::query-tooltip signal on @widget.

A value of true indicates that @widget can have a tooltip, in this case the widget will be queried using query-tooltip to determine whether it will provide a tooltip or not.

Readable | Writeable

height-request

Override for height request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

hexpand

Whether to expand horizontally.

Readable | Writeable

hexpand-set

Whether to use the hexpand property.

Readable | Writeable

layout-manager

The LayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

margin-bottom

Margin on bottom side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

margin-end

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

margin-start

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

margin-top

Margin on top side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from WidgetExt::set_size_request() for example.

Readable | Writeable

name

The name of the widget.

Readable | Writeable

opacity

The requested opacity of the widget.

Readable | Writeable

overflow

How content outside the widget’s content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

parent

The parent widget of this widget.

Readable

receives-default

Whether the widget will receive the default action when it is focused.

Readable | Writeable

root

The Root widget of the widget tree containing this widget.

This will be None if the widget is not contained in a root widget.

Readable

scale-factor

The scale factor of the widget.

Readable

sensitive

Whether the widget responds to input.

Readable | Writeable

tooltip-markup

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see Tooltip::set_markup().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

tooltip-text

Sets the text of tooltip to be the given string.

Also see Tooltip::set_text().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

valign

How to distribute vertical space if widget gets extra space.

Readable | Writeable

vexpand

Whether to expand vertically.

Readable | Writeable

vexpand-set

Whether to use the vexpand property.

Readable | Writeable

visible

Whether the widget is visible.

Readable | Writeable

width-request

Override for width request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

Accessible

accessible-role

The accessible role of the given Accessible implementation.

The accessible role cannot be changed once set.

Readable | Writeable

Implements

WidgetExt, [trait@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

👎Deprecated: Since 4.12

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

Deprecated since 4.12

Use from_paintable() and gdk::Texture::for_pixbuf() instead

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

👎Deprecated: Since 4.12

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.

Deprecated since 4.12

Use set_from_paintable() instead

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>

A path to the file to display.

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

A path to the file 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 HasParamSpec for Image

type ParamSpec = ParamSpecObject

type SetValue = Image

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Image>

fn param_spec_builder() -> Self::BuilderFn

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, Self: Sized,

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized + PartialOrd,

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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