:right-sidebar: True Image =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Image(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` The ``GtkImage`` widget displays an image. .. image:: https://docs.gtk.org/gtk4/image.png Various kinds of object can be displayed as an image; most typically, you would load a ``GdkTexture`` from a file, using the convenience function :obj:`~gi.repository.Gtk.Image.new_from_file`, for instance: .. code-block:: :dedent: 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 :obj:`~gi.repository.Gdk.Texture.new_from_file`, then create the ``GtkImage`` with :obj:`~gi.repository.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`` inside GIO, for details. In this case, :obj:`~gi.repository.Gtk.Image.props.resource`, :obj:`~gi.repository.Gtk.Image.new_from_resource`, and :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.Picture` 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 :obj:`~gi.repository.Gtk.Image.props.icon_size` property. Accessibility ------------- ``GtkImage`` uses the ``GTK_ACCESSIBLE_ROLE_IMG`` role. Constructors ------------ .. rst-class:: interim-class .. class:: Image :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new empty ``GtkImage`` widget. .. classmethod:: new_from_file(filename: str) -> ~gi.repository.Gtk.Widget 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 :const:`None`, it always returns a valid ``GtkImage`` widget. If you need to detect failures to load the file, use :obj:`~gi.repository.Gdk.Texture.new_from_file` to load the file yourself, then create the ``GtkImage`` from the texture. The storage type (see :obj:`~gi.repository.Gtk.Image.get_storage_type`) of the returned image is not defined, it will be whatever is appropriate for displaying the file. :param filename: a filename .. classmethod:: new_from_gicon(icon: ~gi.repository.Gio.Icon) -> ~gi.repository.Gtk.Widget 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. :param icon: an icon .. classmethod:: new_from_icon_name(icon_name: str | None = None) -> ~gi.repository.Gtk.Widget 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. :param icon_name: an icon name .. classmethod:: new_from_paintable(paintable: ~gi.repository.Gdk.Paintable | None = None) -> ~gi.repository.Gtk.Widget 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. :param paintable: a ``GdkPaintable`` .. classmethod:: new_from_pixbuf(pixbuf: ~gi.repository.GdkPixbuf.Pixbuf | None = None) -> ~gi.repository.Gtk.Widget 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 :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.Image.new_from_icon_name`. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gtk.Image.new_from_paintable` and :obj:`~gi.repository.Gdk.Texture.new_for_pixbuf` instead :param pixbuf: a ``GdkPixbuf`` .. classmethod:: new_from_resource(resource_path: str) -> ~gi.repository.Gtk.Widget 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 :const:`None`, it always returns a valid ``GtkImage`` widget. If you need to detect failures to load the file, use :obj:`~gi.repository.GdkPixbuf.Pixbuf.new_from_file` to load the file yourself, then create the ``GtkImage`` from the pixbuf. The storage type (see :obj:`~gi.repository.Gtk.Image.get_storage_type`) of the returned image is not defined, it will be whatever is appropriate for displaying the file. :param resource_path: a resource path Methods ------- .. rst-class:: interim-class .. class:: Image :no-index: .. method:: clear() -> None Resets the image to be empty. .. method:: get_gicon() -> ~gi.repository.Gio.Icon | None Gets the ``GIcon`` being displayed by the ``GtkImage``. The storage type of the image must be :const:`~gi.repository.Gtk.ImageType.EMPTY` or :const:`~gi.repository.Gtk.ImageType.GICON` (see :obj:`~gi.repository.Gtk.Image.get_storage_type`). The caller of this function does not own a reference to the returned ``GIcon``. .. method:: get_icon_name() -> str | None Gets the icon name and size being displayed by the ``GtkImage``. The storage type of the image must be :const:`~gi.repository.Gtk.ImageType.EMPTY` or :const:`~gi.repository.Gtk.ImageType.ICON_NAME` (see :obj:`~gi.repository.Gtk.Image.get_storage_type`). The returned string is owned by the ``GtkImage`` and should not be freed. .. method:: get_icon_size() -> ~gi.repository.Gtk.IconSize Gets the icon size used by the ``image`` when rendering icons. .. method:: get_paintable() -> ~gi.repository.Gdk.Paintable | None Gets the image ``GdkPaintable`` being displayed by the ``GtkImage``. The storage type of the image must be :const:`~gi.repository.Gtk.ImageType.EMPTY` or :const:`~gi.repository.Gtk.ImageType.PAINTABLE` (see :obj:`~gi.repository.Gtk.Image.get_storage_type`). The caller of this function does not own a reference to the returned paintable. .. method:: get_pixel_size() -> int Gets the pixel size used for named icons. .. method:: get_storage_type() -> ~gi.repository.Gtk.ImageType 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 :const:`~gi.repository.Gtk.ImageType.EMPTY`. .. method:: set_from_file(filename: str | None = None) -> None Sets a ``GtkImage`` to show a file. See :obj:`~gi.repository.Gtk.Image.new_from_file` for details. :param filename: a filename .. method:: set_from_gicon(icon: ~gi.repository.Gio.Icon) -> None Sets a ``GtkImage`` to show a ``GIcon``. See :obj:`~gi.repository.Gtk.Image.new_from_gicon` for details. :param icon: an icon .. method:: set_from_icon_name(icon_name: str | None = None) -> None Sets a ``GtkImage`` to show a named icon. See :obj:`~gi.repository.Gtk.Image.new_from_icon_name` for details. :param icon_name: an icon name .. method:: set_from_paintable(paintable: ~gi.repository.Gdk.Paintable | None = None) -> None Sets a ``GtkImage`` to show a ``GdkPaintable``. See :obj:`~gi.repository.Gtk.Image.new_from_paintable` for details. :param paintable: a ``GdkPaintable`` .. method:: set_from_pixbuf(pixbuf: ~gi.repository.GdkPixbuf.Pixbuf | None = None) -> None Sets a ``GtkImage`` to show a ``GdkPixbuf``. See :obj:`~gi.repository.Gtk.Image.new_from_pixbuf` for details. Note: This is a helper for :obj:`~gi.repository.Gtk.Image.set_from_paintable`, and you can't get back the exact pixbuf once this is called, only a paintable. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gtk.Image.set_from_paintable` instead :param pixbuf: a ``GdkPixbuf`` or ``NULL`` .. method:: set_from_resource(resource_path: str | None = None) -> None Sets a ``GtkImage`` to show a resource. See :obj:`~gi.repository.Gtk.Image.new_from_resource` for details. :param resource_path: a resource path .. method:: set_icon_size(icon_size: ~gi.repository.Gtk.IconSize) -> None Suggests an icon size to the theme for named icons. :param icon_size: the new icon size .. method:: set_pixel_size(pixel_size: int) -> None 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 :obj:`~gi.repository.Gtk.Image.set_from_icon_name`. :param pixel_size: the new pixel size Properties ---------- .. rst-class:: interim-class .. class:: Image :no-index: .. attribute:: props.file :type: str A path to the file to display. .. attribute:: props.gicon :type: ~gi.repository.Gio.Icon The ``GIcon`` displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. .. attribute:: props.icon_name :type: str The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. .. attribute:: props.icon_size :type: ~gi.repository.Gtk.IconSize The symbolic size to display icons at. .. attribute:: props.paintable :type: ~gi.repository.Gdk.Paintable The ``GdkPaintable`` to display. .. attribute:: props.pixel_size :type: int The size in pixels to display icons at. If set to a value != -1, this property overrides the :obj:`~gi.repository.Gtk.Image.props.icon_size` property for images of type ``GTK_IMAGE_ICON_NAME``. .. attribute:: props.resource :type: str A path to a resource file to display. .. attribute:: props.storage_type :type: ~gi.repository.Gtk.ImageType The representation being used for image data. .. attribute:: props.use_fallback :type: bool 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 :const:`~gi.repository.Gtk.ImageType.ICON_NAME` and :const:`~gi.repository.Gtk.ImageType.GICON`.