Class Picture

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.Picture
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class Picture extends Widget implements Accessible, Buildable, ConstraintTarget

Displays a GdkPaintable.

An example GtkPicture

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:

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 and image loading framework such as libglycin, then create the GtkPicture with forPaintable(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, forResource(String) and setResource(String) should be used.

GtkPicture displays an image at its natural size. See 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 Gtk.Picture:content-fit. See Gtk.ContentFit for details. Gtk.Picture: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 Gtk.Widget:halign and Gtk.Widget: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.AccessibleRole.img role.

  • Constructor Details

    • Picture

      public Picture(MemorySegment address)
      Create a Picture instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Picture

      public Picture()
      Create a new Picture.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Picture class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Picture asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • forFile

      public static Picture forFile(@Nullable File file)

      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 an image loading framework such as libglycin to load the file yourself, then create the GtkPicture from the texture.

      Parameters:
      file - a GFile
      Returns:
      a new GtkPicture

    • forFilename

      public static Picture forFilename(@Nullable String filename)

      Creates a new GtkPicture displaying the file filename.

      This is a utility function that calls forFile(File). See that function for details.

      Parameters:
      filename - a filename
      Returns:
      a new GtkPicture

    • forPaintable

      public static Picture forPaintable(@Nullable Paintable paintable)

      Creates a new GtkPicture displaying paintable.

      The GtkPicture will track changes to the paintable and update its size and contents in response to it.

      Parameters:
      paintable - a GdkPaintable
      Returns:
      a new GtkPicture

    • forPixbuf

      @Deprecated public static Picture forPixbuf(@Nullable Pixbuf pixbuf)
      Deprecated.
      Use forPaintable(Paintable) and Texture#forPixbuf instead

      Creates a new GtkPicture displaying pixbuf.

      This is a utility function that calls forPaintable(Paintable), See that function for details.

      The pixbuf must not be modified after passing it to this function.

      Parameters:
      pixbuf - a GdkPixbuf
      Returns:
      a new GtkPicture

    • forResource

      public static Picture forResource(@Nullable String resourcePath)

      Creates a new GtkPicture displaying the resource at resourcePath.

      This is a utility function that calls forFile(File). See that function for details.

      Parameters:
      resourcePath - resource path to play back
      Returns:
      a new GtkPicture

    • getAlternativeText

      public @Nullable String getAlternativeText()

      Gets the alternative textual description of the picture.

      The returned string will be null if the picture cannot be described textually.

      Returns:
      the alternative textual description of self.

    • getCanShrink

      public boolean getCanShrink()
      Returns whether the GtkPicture respects its contents size.
      Returns:
      true if the picture can be made smaller than its contents

    • getContentFit

      public ContentFit getContentFit()

      Returns the fit mode for the content of the GtkPicture.

      See Gtk.ContentFit for details.

      Returns:
      the content fit mode
      Since:
      4.8

    • getFile

      public @Nullable File getFile()

      Gets the GFile currently displayed if this Picture is displaying a file.

      If this Picture is not displaying a file, for example when setPaintable(Paintable) was used, then null is returned.

      Returns:
      The GFile displayed by self.

    • getIsolateContents

      public boolean getIsolateContents()
      Returns whether the contents are isolated.
      Returns:
      True if contents are isolated
      Since:
      4.22

    • getKeepAspectRatio

      @Deprecated public boolean getKeepAspectRatio()
      Deprecated.
      Use getContentFit() instead. This will now return FALSE only if Gtk.Picture:content-fit is GTK_CONTENT_FIT_FILL. Returns TRUE otherwise.
      Returns whether the GtkPicture preserves its contents aspect ratio.
      Returns:
      true if the self tries to keep the contents' aspect ratio

    • getPaintable

      public @Nullable Paintable getPaintable()
      Gets the GdkPaintable being displayed by the GtkPicture.
      Returns:
      the displayed paintable

    • setAlternativeText

      public void setAlternativeText(@Nullable String alternativeText)

      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 null.

      Parameters:
      alternativeText - a textual description of the contents

    • setCanShrink

      public void setCanShrink(boolean canShrink)

      If set to true, then this Picture 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 Widget.setSizeRequest(int, int).

      Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via Widget.setHalign(Align) and Widget.setValign(Align).

      Parameters:
      canShrink - if this Picture can be made smaller than its contents

    • setContentFit

      public void setContentFit(ContentFit contentFit)

      Sets how the content should be resized to fit the GtkPicture.

      See Gtk.ContentFit for details.

      Parameters:
      contentFit - the content fit mode
      Since:
      4.8

    • setFile

      public void setFile(@Nullable File file)

      Makes this Picture load and display file.

      See forFile(File) for details.

      ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture, and then use Image.setFromPaintable(Paintable).

      Parameters:
      file - a GFile

    • setFilename

      public void setFilename(@Nullable String filename)

      Makes this Picture load and display the given filename.

      This is a utility function that calls setFile(File).

      ::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture, and then use Image.setFromPaintable(Paintable).

      Parameters:
      filename - the filename to play

    • setIsolateContents

      public void setIsolateContents(boolean isolateContents)

      If set to true, then the contents will be rendered individually.

      If set to false they will be able to erase or otherwise mix with the background.

      GTK supports finer grained isolation, in rare cases where you need this, you can use Snapshot.pushIsolation(Set) yourself to achieve this.

      By default contents are isolated.

      Parameters:
      isolateContents - if contents are rendered separately
      Since:
      4.22

    • setKeepAspectRatio

      @Deprecated public void setKeepAspectRatio(boolean keepAspectRatio)
      Deprecated.
      Use setContentFit(ContentFit) instead. If still used, this method will always set the Gtk.Picture:content-fit property to GTK_CONTENT_FIT_CONTAIN if keepAspectRatio is true, otherwise it will set it to GTK_CONTENT_FIT_FILL.

      If set to true, the this Picture 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 false or if the contents provide no aspect ratio, the contents will be stretched over the picture's whole area.

      Parameters:
      keepAspectRatio - whether to keep aspect ratio

    • setPaintable

      public void setPaintable(@Nullable Paintable paintable)

      Makes this Picture display the given paintable.

      If paintable is NULL, nothing will be displayed.

      See forPaintable(Paintable) for details.

      Parameters:
      paintable - a GdkPaintable

    • setPixbuf

      @Deprecated public void setPixbuf(@Nullable Pixbuf pixbuf)
      Deprecated.
      Use setPaintable(Paintable) instead

      Sets a GtkPicture to show a GdkPixbuf.

      See forPixbuf(Pixbuf) for details.

      This is a utility function that calls setPaintable(Paintable).

      Parameters:
      pixbuf - a GdkPixbuf

    • setResource

      public void setResource(@Nullable String resourcePath)

      Makes this Picture load and display the resource at the given resourcePath.

      This is a utility function that calls setFile(File).

      Parameters:
      resourcePath - the resource to set

    • builder

      public static Picture.Builder<? extends Picture.Builder> builder()
      A Picture.Builder object constructs a Picture with the specified properties. Use the various set...() methods to set properties, and finish construction with Picture.Builder.build().
      Returns:
      the builder object