:right-sidebar: True Picture =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Picture(**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: :: Picture(**properties) new() -> Gtk.Widget new_for_file(file:Gio.File=None) -> Gtk.Widget new_for_filename(filename:str=None) -> Gtk.Widget new_for_paintable(paintable:Gdk.Paintable=None) -> Gtk.Widget new_for_pixbuf(pixbuf:GdkPixbuf.Pixbuf=None) -> Gtk.Widget new_for_resource(resource_path:str=None) -> Gtk.Widget Constructors ------------ .. rst-class:: interim-class .. class:: Picture :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new empty ``GtkPicture`` widget. .. classmethod:: new_for_file(file: ~gi.repository.Gio.File | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkPicture`` displaying the given ``file``. If the file isn’t found or can’t be loaded, the resulting ``GtkPicture`` is empty. 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 ``GtkPicture`` from the texture. :param file: a ``GFile`` .. classmethod:: new_for_filename(filename: str | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkPicture`` displaying the file ``filename``. This is a utility function that calls :obj:`~gi.repository.Gtk.Picture.new_for_file`. See that function for details. :param filename: a filename .. classmethod:: new_for_paintable(paintable: ~gi.repository.Gdk.Paintable | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkPicture`` displaying ``paintable``. The ``GtkPicture`` will track changes to the ``paintable`` and update its size and contents in response to it. :param paintable: a ``GdkPaintable`` .. classmethod:: new_for_pixbuf(pixbuf: ~gi.repository.GdkPixbuf.Pixbuf | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkPicture`` displaying ``pixbuf``. This is a utility function that calls :obj:`~gi.repository.Gtk.Picture.new_for_paintable`, See that function for details. The pixbuf must not be modified after passing it to this function. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gtk.Picture.new_for_paintable` and :obj:`~gi.repository.Gdk.Texture.new_for_pixbuf` instead :param pixbuf: a ``GdkPixbuf`` .. classmethod:: new_for_resource(resource_path: str | None = None) -> ~gi.repository.Gtk.Widget Creates a new ``GtkPicture`` displaying the resource at ``resource_path``. This is a utility function that calls :obj:`~gi.repository.Gtk.Picture.new_for_file`. See that function for details. :param resource_path: resource path to play back Methods ------- .. rst-class:: interim-class .. class:: Picture :no-index: .. method:: get_alternative_text() -> str | None Gets the alternative textual description of the picture. The returned string will be :const:`None` if the picture cannot be described textually. .. method:: get_can_shrink() -> bool Returns whether the ``GtkPicture`` respects its contents size. .. method:: get_content_fit() -> ~gi.repository.Gtk.ContentFit Returns the fit mode for the content of the ``GtkPicture``. See :obj:`~gi.repository.Gtk.ContentFit` for details. .. versionadded:: 4.8 .. method:: get_file() -> ~gi.repository.Gio.File | None Gets the ``GFile`` currently displayed if ``self`` is displaying a file. If ``self`` is not displaying a file, for example when :obj:`~gi.repository.Gtk.Picture.set_paintable` was used, then :const:`None` is returned. .. method:: get_keep_aspect_ratio() -> bool Returns whether the ``GtkPicture`` preserves its contents aspect ratio. .. deprecated:: 4.8 Use :obj:`~gi.repository.Gtk.Picture.get_content_fit` instead. This will now return ``FALSE`` only if :obj:`~gi.repository.Gtk.Picture.props.content_fit` is ``GTK_CONTENT_FIT_FILL``. Returns ``TRUE`` otherwise. .. method:: get_paintable() -> ~gi.repository.Gdk.Paintable | None Gets the ``GdkPaintable`` being displayed by the ``GtkPicture``. .. method:: set_alternative_text(alternative_text: str | None = None) -> None Sets an alternative textual description for the picture contents. It is equivalent to the "alt" attribute for images on websites. This text will be made available to accessibility tools. If the picture cannot be described textually, set this property to :const:`None`. :param alternative_text: a textual description of the contents .. method:: set_can_shrink(can_shrink: bool) -> None If set to :const:`True`, the ``self`` can be made smaller than its contents. The contents will then be scaled down when rendering. If you want to still force a minimum size manually, consider using :obj:`~gi.repository.Gtk.Widget.set_size_request`. Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via :obj:`~gi.repository.Gtk.Widget.set_halign` and :obj:`~gi.repository.Gtk.Widget.set_valign`. :param can_shrink: if ``self`` can be made smaller than its contents .. method:: set_content_fit(content_fit: ~gi.repository.Gtk.ContentFit) -> None Sets how the content should be resized to fit the ``GtkPicture``. See :obj:`~gi.repository.Gtk.ContentFit` for details. .. versionadded:: 4.8 :param content_fit: the content fit mode .. method:: set_file(file: ~gi.repository.Gio.File | None = None) -> None Makes ``self`` load and display ``file``. See :obj:`~gi.repository.Gtk.Picture.new_for_file` for details. :param file: a ``GFile`` .. method:: set_filename(filename: str | None = None) -> None Makes ``self`` load and display the given ``filename``. This is a utility function that calls :obj:`~gi.repository.Gtk.Picture.set_file`. :param filename: the filename to play .. method:: set_keep_aspect_ratio(keep_aspect_ratio: bool) -> None If set to :const:`True`, the ``self`` will render its contents according to their aspect ratio. That means that empty space may show up at the top/bottom or left/right of ``self``. If set to :const:`False` or if the contents provide no aspect ratio, the contents will be stretched over the picture's whole area. .. deprecated:: 4.8 Use :obj:`~gi.repository.Gtk.Picture.set_content_fit` instead. If still used, this method will always set the :obj:`~gi.repository.Gtk.Picture.props.content_fit` property to ``GTK_CONTENT_FIT_CONTAIN`` if ``keep_aspect_ratio`` is true, otherwise it will set it to ``GTK_CONTENT_FIT_FILL``. :param keep_aspect_ratio: whether to keep aspect ratio .. method:: set_paintable(paintable: ~gi.repository.Gdk.Paintable | None = None) -> None Makes ``self`` display the given ``paintable``. If ``paintable`` is :const:`None`, nothing will be displayed. See :obj:`~gi.repository.Gtk.Picture.new_for_paintable` for details. :param paintable: a ``GdkPaintable`` .. method:: set_pixbuf(pixbuf: ~gi.repository.GdkPixbuf.Pixbuf | None = None) -> None Sets a ``GtkPicture`` to show a ``GdkPixbuf``. See :obj:`~gi.repository.Gtk.Picture.new_for_pixbuf` for details. This is a utility function that calls :obj:`~gi.repository.Gtk.Picture.set_paintable`. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gtk.Picture.set_paintable` instead :param pixbuf: a ``GdkPixbuf`` .. method:: set_resource(resource_path: str | None = None) -> None Makes ``self`` load and display the resource at the given ``resource_path``. This is a utility function that calls :obj:`~gi.repository.Gtk.Picture.set_file`. :param resource_path: the resource to set Properties ---------- .. rst-class:: interim-class .. class:: Picture :no-index: .. attribute:: props.alternative_text :type: str The alternative textual description for the picture. .. attribute:: props.can_shrink :type: bool If the ``GtkPicture`` can be made smaller than the natural size of its contents. .. attribute:: props.content_fit :type: ~gi.repository.Gtk.ContentFit How the content should be resized to fit inside the ``GtkPicture``. .. versionadded:: 4.8 .. attribute:: props.file :type: ~gi.repository.Gio.File The ``GFile`` that is displayed or :const:`None` if none. .. attribute:: props.keep_aspect_ratio :type: bool Whether the GtkPicture will render its contents trying to preserve the aspect ratio. .. deprecated:: 4.8 Use :obj:`~gi.repository.Gtk.Picture.props.content_fit` instead. .. attribute:: props.paintable :type: ~gi.repository.Gdk.Paintable The ``GdkPaintable`` to be displayed by this ``GtkPicture``.