: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` The ``GtkPicture`` widget displays a ``GdkPaintable``. .. image:: https://docs.gtk.org/gtk4/picture.png Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display it, there’s a convenience function to do this: .. code-block:: :dedent: GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png"); If the file isn’t loaded successfully, the picture 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 ``GtkPicture`` with :obj:`~gi.repository.Gtk.Picture.new_for_paintable`. Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of ``GResource`` for details. In this case, :obj:`~gi.repository.Gtk.Picture.new_for_resource` and :obj:`~gi.repository.Gtk.Picture.set_resource` should be used. ``GtkPicture`` displays an image at its natural size. See :obj:`~gi.repository.Gtk.Image` if you want to display a fixed-size image, such as an icon. Sizing the paintable -------------------- You can influence how the paintable is displayed inside the ``GtkPicture`` by changing :obj:`~gi.repository.Gtk.Picture.props.content_fit`. See :obj:`~gi.repository.Gtk.ContentFit` for details. :obj:`~gi.repository.Gtk.Picture.props.can_shrink` can be unset to make sure that paintables are never made smaller than their ideal size - but be careful if you do not know the size of the paintable in use (like when displaying user-loaded images). This can easily cause the picture to grow larger than the screen. And :obj:`~gi.repository.Gtk.Widget.props.halign` and :obj:`~gi.repository.Gtk.Widget.props.valign` can be used to make sure the paintable doesn't fill all available space but is instead displayed at its original size. CSS nodes --------- ``GtkPicture`` has a single CSS node with the name ``picture``. Accessibility ------------- ``GtkPicture`` uses the ``GTK_ACCESSIBLE_ROLE_IMG`` role. 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``.