Package org.gnome.gtk

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("io.github.jwharm.JavaGI")
public class Picture
extends Widget
implements Accessible, Buildable, ConstraintTarget

Displays a GdkPaintable.

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(org.gnome.gdk.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(java.lang.String) and setResource(java.lang.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Picture.Builder<B extends Picture.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	Picture.PictureClass

Nested classes/interfaces inherited from class org.gnome.gtk.Widget

Widget.DestroyCallback, Widget.DirectionChangedCallback, Widget.HideCallback, Widget.KeynavFailedCallback, Widget.MapCallback, Widget.MnemonicActivateCallback, Widget.MoveFocusCallback, Widget.QueryTooltipCallback, Widget.RealizeCallback, Widget.ShowCallback, Widget.StateFlagsChangedCallback, Widget.UnmapCallback, Widget.UnrealizeCallback, Widget.Widget$Impl, Widget.WidgetClass

Nested classes/interfaces inherited from class org.gnome.gobject.InitiallyUnowned

InitiallyUnowned.InitiallyUnownedClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Nested classes/interfaces inherited from interface org.gnome.gtk.Accessible

Accessible.Accessible$Impl, Accessible.AccessibleInterface

Nested classes/interfaces inherited from interface org.gnome.gtk.Buildable

Buildable.Buildable$Impl, Buildable.BuildableIface

Nested classes/interfaces inherited from interface org.gnome.gtk.ConstraintTarget

ConstraintTarget.ConstraintTarget$Impl, ConstraintTarget.ConstraintTargetInterface

Constructor Summary

Constructors

Constructor	Description
Picture()	Creates a new Picture.
Picture(MemorySegment address)	Create a Picture proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected Picture	asParent()	Returns this instance as if it were its parent type.
static Picture.Builder<? extends Picture.Builder>	builder()	A Picture.Builder object constructs a Picture with the specified properties.
static Picture	forFile(@Nullable File file)	Creates a new GtkPicture displaying the given file.
static Picture	forFilename(@Nullable String filename)	Creates a new GtkPicture displaying the file filename.
static Picture	forPaintable(@Nullable Paintable paintable)	Creates a new GtkPicture displaying paintable.
static Picture	forPixbuf(@Nullable Pixbuf pixbuf)	Deprecated. Use forPaintable(org.gnome.gdk.Paintable) and Texture.forPixbuf(org.gnome.gdkpixbuf.Pixbuf) instead
static Picture	forResource(@Nullable String resourcePath)	Creates a new GtkPicture displaying the resource at resourcePath.
@Nullable String	getAlternativeText()	Gets the alternative textual description of the picture.
boolean	getCanShrink()	Returns whether the GtkPicture respects its contents size.
ContentFit	getContentFit()	Returns the fit mode for the content of the GtkPicture.
@Nullable File	getFile()	Gets the GFile currently displayed if this Picture is displaying a file.
boolean	getKeepAspectRatio()	Deprecated. Use getContentFit() instead.
@Nullable Paintable	getPaintable()	Gets the GdkPaintable being displayed by the GtkPicture.
static @Nullable Type	getType()	Get the GType of the Picture class
void	setAlternativeText(@Nullable String alternativeText)	Sets an alternative textual description for the picture contents.
void	setCanShrink(boolean canShrink)	If set to true, the this Picture can be made smaller than its contents.
void	setContentFit(ContentFit contentFit)	Sets how the content should be resized to fit the GtkPicture.
void	setFile(@Nullable File file)	Makes this Picture load and display file.
void	setFilename(@Nullable String filename)	Makes this Picture load and display the given filename.
void	setKeepAspectRatio(boolean keepAspectRatio)	Deprecated. Use setContentFit(org.gnome.gtk.ContentFit) instead.
void	setPaintable(@Nullable Paintable paintable)	Makes this Picture display the given paintable.
void	setPixbuf(@Nullable Pixbuf pixbuf)	Deprecated. Use setPaintable(org.gnome.gdk.Paintable) instead
void	setResource(@Nullable String resourcePath)	Makes this Picture load and display the resource at the given resourcePath.

Methods inherited from class org.gnome.gtk.Widget

actionSetEnabled, activateActionIfExists, activateDefault, activateWidget, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, childFocus, computeBounds, computeExpand, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, cssChanged, directionChanged, disposeTemplate, dragCheckThreshold, emitDestroy, emitDirectionChanged, emitHide, emitKeynavFailed, emitMap, emitMnemonicActivate, emitMoveFocus, emitQueryTooltip, emitRealize, emitShow, emitStateFlagsChanged, emitUnmap, emitUnrealize, errorBell, focus, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getBaseline, getCanFocus, getCanTarget, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getDefaultDirection, getDirection, getDisplay, getFirstChild, getFocusable, getFocusChild, getFocusOnClick, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getMemoryLayout, getName, getNative, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPreferredSize, getPrevSibling, getPrimaryClipboard, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, moveFocus, observeChildren, observeControllers, onDestroy, onDirectionChanged, onHide, onKeynavFailed, onMap, onMnemonicActivate, onMoveFocus, onQueryTooltip, onRealize, onShow, onStateFlagsChanged, onUnmap, onUnrealize, pick, pick, queryTooltip, queueAllocate, queueDraw, queueResize, realize, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, root, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setDefaultDirection, setDirection, setFocusable, setFocusChild, setFocusOnClick, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setLayoutManager, setLimitEvents, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible, shouldLayout, show, sizeAllocate, sizeAllocate, snapshot, snapshotChild, stateFlagsChanged, systemSettingChanged, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unroot, unsetStateFlags, unsetStateFlags

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.gnome.gtk.Accessible

announce, getAccessibleParent, getAccessibleRole, getAtContext, getBounds, getFirstAccessibleChild, getNextAccessibleSibling, getPlatformState, resetProperty, resetRelation, resetState, setAccessibleParent, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState

Methods inherited from interface org.gnome.gtk.Buildable

getBuildableId

Methods inherited from interface org.javagi.base.Proxy

handle

Constructor Details

Picture

public Picture(MemorySegment address)

Create a Picture proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Picture

public Picture()

Creates a new Picture.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Picture class

Returns:

the GType

asParent

protected Picture asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class Widget

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(org.gnome.gio.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(org.gnome.gdk.Paintable) and Texture.forPixbuf(org.gnome.gdkpixbuf.Pixbuf) instead

Creates a new GtkPicture displaying pixbuf.

This is a utility function that calls forPaintable(org.gnome.gdk.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(org.gnome.gio.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(org.gnome.gdk.Paintable) was used, then null is returned.

Returns:

The GFile displayed by self.

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, the 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(org.gnome.gtk.Align) and Widget.setValign(org.gnome.gtk.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(org.gnome.gio.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 [method@Gtk.Image.set_from_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(org.gnome.gio.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 [method@Gtk.Image.set_from_paintable].

Parameters:

filename - the filename to play

setKeepAspectRatio

@Deprecated
public void setKeepAspectRatio(boolean keepAspectRatio)

Deprecated.

Use setContentFit(org.gnome.gtk.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(org.gnome.gdk.Paintable) for details.

Parameters:

paintable - a GdkPaintable

setPixbuf

@Deprecated
public void setPixbuf(@Nullable Pixbuf pixbuf)

Deprecated.

Use setPaintable(org.gnome.gdk.Paintable) instead

Sets a GtkPicture to show a GdkPixbuf.

See forPixbuf(org.gnome.gdkpixbuf.Pixbuf) for details.

This is a utility function that calls setPaintable(org.gnome.gdk.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(org.gnome.gio.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