Package org.gnome.gdkpixbuf

Class PixbufLoader

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gdkpixbuf.PixbufLoader

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class PixbufLoader
extends GObject

Incremental image loader.

GdkPixbufLoader provides a way for applications to drive the process of loading an image, by letting them send the image data directly to the loader instead of having the loader read the data from a file. Applications can use this functionality instead of gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() when they need to parse image data in small chunks. For example, it should be used when reading an image from a (potentially) slow network connection, or when loading an extremely large file.

To use GdkPixbufLoader to load an image, create a new instance, and call write(byte[]) to send the data to it. When done, close() should be called to end the stream and finalize everything.

The loader will emit three important signals throughout the process:

• GdkPixbuf.PixbufLoader::size-prepared will be emitted as soon as the image has enough information to determine the size of the image to be used. If you want to scale the image while loading it, you can call setSize(int, int) in response to this signal.
• GdkPixbuf.PixbufLoader::area-prepared will be emitted as soon as the pixbuf of the desired has been allocated. You can obtain the GdkPixbuf instance by calling getPixbuf(). If you want to use it, simply acquire a reference to it. You can also call gdk_pixbuf_loader_get_pixbuf() later to get the same pixbuf.
• GdkPixbuf.PixbufLoader::area-updated will be emitted every time a region is updated. This way you can update a partially completed image. Note that you do not know anything about the completeness of an image from the updated area. For example, in an interlaced image you will need to make several passes before the image is done loading.

Loading an animation
Loading an animation is almost as easy as loading an image. Once the first GdkPixbuf.PixbufLoader::area-prepared signal has been emitted, you can call getAnimation() to get the PixbufAnimation instance, and then call and PixbufAnimation.getIter(org.gnome.glib.TimeVal) to get a PixbufAnimationIter to retrieve the pixbuf for the desired time stamp.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	PixbufLoader.AreaPreparedCallback	Functional interface declaration of the AreaPreparedCallback callback.
static interface	PixbufLoader.AreaUpdatedCallback	Functional interface declaration of the AreaUpdatedCallback callback.
static class	PixbufLoader.Builder<B extends PixbufLoader.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	PixbufLoader.ClosedCallback	Functional interface declaration of the ClosedCallback callback.
static class	PixbufLoader.PixbufLoaderClass
static interface	PixbufLoader.SizePreparedCallback	Functional interface declaration of the SizePreparedCallback callback.

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

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
protected void	areaPrepared()
protected void	areaUpdated(int x, int y, int width, int height)
protected PixbufLoader	asParent()	Returns this instance as if it were its parent type.
static PixbufLoader.Builder<? extends PixbufLoader.Builder>	builder()	A PixbufLoader.Builder object constructs a PixbufLoader with the specified properties.
boolean	close()	Informs a pixbuf loader that no further writes with gdk_pixbuf_loader_write() will occur, so that it can free its internal loading structures.
protected void	closed()
void	emitAreaPrepared()	Emits the "area-prepared" signal.
void	emitAreaUpdated(int x, int y, int width, int height)	Emits the "area-updated" signal.
void	emitClosed()	Emits the "closed" signal.
void	emitSizePrepared(int width, int height)	Emits the "size-prepared" signal.
@Nullable PixbufAnimation	getAnimation()	Queries the GdkPixbufAnimation that a pixbuf loader is currently creating.
@Nullable PixbufFormat	getFormat()	Obtains the available information about the format of the currently loading image file.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
@Nullable Pixbuf	getPixbuf()	Queries the GdkPixbuf that a pixbuf loader is currently creating.
static @Nullable Type	getType()	Get the GType of the PixbufLoader class
SignalConnection<PixbufLoader.AreaPreparedCallback>	onAreaPrepared(PixbufLoader.AreaPreparedCallback handler)	This signal is emitted when the pixbuf loader has allocated the pixbuf in the desired size.
SignalConnection<PixbufLoader.AreaUpdatedCallback>	onAreaUpdated(PixbufLoader.AreaUpdatedCallback handler)	This signal is emitted when a significant area of the image being loaded has been updated.
SignalConnection<PixbufLoader.ClosedCallback>	onClosed(PixbufLoader.ClosedCallback handler)	This signal is emitted when gdk_pixbuf_loader_close() is called.
SignalConnection<PixbufLoader.SizePreparedCallback>	onSizePrepared(PixbufLoader.SizePreparedCallback handler)	This signal is emitted when the pixbuf loader has been fed the initial amount of data that is required to figure out the size of the image that it will create.
void	setSize(int width, int height)	Causes the image to be scaled while it is loaded.
protected void	sizePrepared(int width, int height)
static PixbufLoader	withMimeType(String mimeType)	Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of MIME type mimeType, instead of identifying the type automatically.
static PixbufLoader	withType(String imageType)	Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of type imageType, instead of identifying the type automatically.
boolean	write(@org.jspecify.annotations.Nullable byte @Nullable [] buf)	Parses the next count bytes in the given image buffer.
boolean	writeBytes(byte[] buffer)	Parses the next contents of the given image buffer.

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

Constructor Details

PixbufLoader

public PixbufLoader(MemorySegment address)

Create a PixbufLoader proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

PixbufLoader

public PixbufLoader()

Creates a new PixbufLoader.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the PixbufLoader class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected PixbufLoader 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 GObject

withMimeType

public static PixbufLoader withMimeType(String mimeType)
                                 throws GErrorException

Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of MIME type mimeType, instead of identifying the type automatically.

This function is useful if you want an error if the image isn't the expected MIME type; for loading image formats that can't be reliably identified by looking at the data; or if the user manually forces a specific MIME type.

The list of supported mime types depends on what image loaders are installed, but typically "image/png", "image/jpeg", "image/gif", "image/tiff" and "image/x-xpixmap" are among the supported mime types. To obtain the full list of supported mime types, call gdk_pixbuf_format_get_mime_types() on each of the GdkPixbufFormat structs returned by gdk_pixbuf_get_formats().

Parameters:

mimeType - the mime type to be loaded

Returns:

A newly-created pixbuf loader.

Throws:

GErrorException - see GError

Since:

2.4

withType

public static PixbufLoader withType(String imageType)
                             throws GErrorException

Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of type imageType, instead of identifying the type automatically.

This function is useful if you want an error if the image isn't the expected type; for loading image formats that can't be reliably identified by looking at the data; or if the user manually forces a specific type.

The list of supported image formats depends on what image loaders are installed, but typically "png", "jpeg", "gif", "tiff" and "xpm" are among the supported formats. To obtain the full list of supported image formats, call gdk_pixbuf_format_get_name() on each of the GdkPixbufFormat structs returned by gdk_pixbuf_get_formats().

Parameters:

imageType - name of the image format to be loaded with the image

Returns:

A newly-created pixbuf loader.

Throws:

GErrorException - see GError

close

public boolean close()
              throws GErrorException

Informs a pixbuf loader that no further writes with gdk_pixbuf_loader_write() will occur, so that it can free its internal loading structures.

This function also tries to parse any data that hasn't yet been parsed; if the remaining data is partial or corrupt, an error will be returned.

If FALSE is returned, error will be set to an error from the GDK_PIXBUF_ERROR or G_FILE_ERROR domains.

If you're just cancelling a load rather than expecting it to be finished, passing NULL for error to ignore it is reasonable.

Remember that this function does not release a reference on the loader, so you will need to explicitly release any reference you hold.

Returns:

TRUE if all image data written so far was successfully passed out via the update_area signal

Throws:

GErrorException - see GError

getAnimation

public @Nullable PixbufAnimation getAnimation()

Queries the GdkPixbufAnimation that a pixbuf loader is currently creating.

In general it only makes sense to call this function after the GdkPixbuf.PixbufLoader::area-prepared signal has been emitted by the loader.

If the loader doesn't have enough bytes yet, and hasn't emitted the area-prepared signal, this function will return NULL.

Returns:

The animation that the loader is currently loading

getFormat

public @Nullable PixbufFormat getFormat()

Obtains the available information about the format of the currently loading image file.

Returns:

A GdkPixbufFormat

Since:

2.2

getPixbuf

public @Nullable Pixbuf getPixbuf()

Queries the GdkPixbuf that a pixbuf loader is currently creating.

In general it only makes sense to call this function after the GdkPixbuf.PixbufLoader::area-prepared signal has been emitted by the loader; this means that enough data has been read to know the size of the image that will be allocated.

If the loader has not received enough data via gdk_pixbuf_loader_write(), then this function returns NULL.

The returned pixbuf will be the same in all future calls to the loader, so if you want to keep using it, you should acquire a reference to it.

Additionally, if the loader is an animation, it will return the "static image" of the animation (see gdk_pixbuf_animation_get_static_image()).

Returns:

The pixbuf that the loader is creating

setSize

public void setSize(int width,
 int height)

Causes the image to be scaled while it is loaded.

The desired image size can be determined relative to the original size of the image by calling gdk_pixbuf_loader_set_size() from a signal handler for the ::size-prepared signal.

Attempts to set the desired image size are ignored after the emission of the ::size-prepared signal.

Parameters:

width - The desired width of the image being loaded.

height - The desired height of the image being loaded.

Since:

2.2

write

public boolean write(@org.jspecify.annotations.Nullable byte @Nullable [] buf)
              throws GErrorException

Parses the next count bytes in the given image buffer.

Parameters:

buf - Pointer to image data.

Returns:

TRUE if the write was successful, or FALSE if the loader cannot parse the buffer

Throws:

GErrorException - see GError

writeBytes

public boolean writeBytes(byte[] buffer)
                   throws GErrorException

Parses the next contents of the given image buffer.

Parameters:

buffer - The image data as a GBytes buffer.

Returns:

TRUE if the write was successful, or FALSE if the loader cannot parse the buffer

Throws:

GErrorException - see GError

Since:

2.30

areaPrepared

protected void areaPrepared()

areaUpdated

protected void areaUpdated(int x,
 int y,
 int width,
 int height)

closed

protected void closed()

sizePrepared

protected void sizePrepared(int width,
 int height)

onAreaPrepared

public SignalConnection<PixbufLoader.AreaPreparedCallback> onAreaPrepared(PixbufLoader.AreaPreparedCallback handler)

This signal is emitted when the pixbuf loader has allocated the pixbuf in the desired size.

After this signal is emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded pixbuf.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• PixbufLoader.AreaPreparedCallback.run()

emitAreaPrepared

public void emitAreaPrepared()

Emits the "area-prepared" signal. See onAreaPrepared(org.gnome.gdkpixbuf.PixbufLoader.AreaPreparedCallback).

onAreaUpdated

public SignalConnection<PixbufLoader.AreaUpdatedCallback> onAreaUpdated(PixbufLoader.AreaUpdatedCallback handler)

This signal is emitted when a significant area of the image being loaded has been updated.

Normally it means that a complete scanline has been read in, but it could be a different area as well.

Applications can use this signal to know when to repaint areas of an image that is being loaded.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• PixbufLoader.AreaUpdatedCallback.run(int, int, int, int)

emitAreaUpdated

public void emitAreaUpdated(int x,
 int y,
 int width,
 int height)

Emits the "area-updated" signal. See onAreaUpdated(org.gnome.gdkpixbuf.PixbufLoader.AreaUpdatedCallback).

onClosed

public SignalConnection<PixbufLoader.ClosedCallback> onClosed(PixbufLoader.ClosedCallback handler)

This signal is emitted when gdk_pixbuf_loader_close() is called.

It can be used by different parts of an application to receive notification when an image loader is closed by the code that drives it.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• PixbufLoader.ClosedCallback.run()

emitClosed

public void emitClosed()

Emits the "closed" signal. See onClosed(org.gnome.gdkpixbuf.PixbufLoader.ClosedCallback).

onSizePrepared

public SignalConnection<PixbufLoader.SizePreparedCallback> onSizePrepared(PixbufLoader.SizePreparedCallback handler)

This signal is emitted when the pixbuf loader has been fed the initial amount of data that is required to figure out the size of the image that it will create.

Applications can call gdk_pixbuf_loader_set_size() in response to this signal to set the desired size to which the image should be scaled.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• PixbufLoader.SizePreparedCallback.run(int, int)

emitSizePrepared

public void emitSizePrepared(int width,
 int height)

Emits the "size-prepared" signal. See onSizePrepared(org.gnome.gdkpixbuf.PixbufLoader.SizePreparedCallback).

builder

public static PixbufLoader.Builder<? extends PixbufLoader.Builder> builder()

A PixbufLoader.Builder object constructs a PixbufLoader with the specified properties. Use the various set...() methods to set properties, and finish construction with PixbufLoader.Builder.build().

Returns:

the builder object