: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` :Constructors: :: Image(**properties) new() -> Gtk.Widget new_from_file(filename:str) -> Gtk.Widget new_from_gicon(icon:Gio.Icon) -> Gtk.Widget new_from_icon_name(icon_name:str=None) -> Gtk.Widget new_from_paintable(paintable:Gdk.Paintable=None) -> Gtk.Widget new_from_pixbuf(pixbuf:GdkPixbuf.Pixbuf=None) -> Gtk.Widget new_from_resource(resource_path:str) -> Gtk.Widget 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`.