gtk.gdk.PixbufLoader
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.PixbufLoader

gtk.gdk.PixbufLoader — an object providing application-driven progressive image loading

## Synopsis

    class gtk.gdk.PixbufLoader(gobject.GObject):
        gtk.gdk.PixbufLoader(image_type=None)
        def write(buf, count=-1)
        def get_pixbuf()
        def get_animation()
        def close()
        def set_size(width, height)
        def get_format()

    Functions

        def gtk.gdk.pixbuf_loader_new_with_mime_type(mime_type)

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.PixbufLoader

## Signal Prototypes

"area-prepared" | `def callback(`pixbufloader`, `user_param1`, `...`)`
"area-updated" | `def callback(`pixbufloader`, `x`, `y`, `width`, `height`, `user_param1`, `...`)`
"closed" | `def callback(`pixbufloader`, `user_param1`, `...`)`
"size-prepared" | `def callback(`pixbufloader`, `width`, `height`, `user_param1`, `...`)`

## Description

A `gtk.gdk.PixbufLoader` 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 instead of the `gtk.gdk.pixbuf_new_from_file` function or the `gtk.gdk.PixbufAnimation` constructor 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 `gtk.gdk.PixbufLoader` to load an image, just create a new one, and call the `write`() method to send the data to it. When done, the `close`() method should be called to end the stream and finalize everything. The loader will emit two important signals throughout the process. The first, "area-prepared", will be called as soon as the image has enough information to determine the size of the image to be used. The application can call the `get_pixbuf`() method to retrieve the pixbuf. No actual image data will be in the pixbuf, so it can be safely filled with any temporary graphics (or an initial color) as needed.

The "area-updated" signal is 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 area updated. For example, in an interlaced image, you 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 "area-prepared" signal has been emitted, you can call the `get_animation`() method to get the `gtk.gdk.PixbufAnimation` object and the `gtk.gdk.PixbufAnimation.get_iter`() method to get an `gtk.gdk.PixbufAnimationIter` for displaying it.

## Constructor

        gtk.gdk.PixbufLoader(image_type=None)

`image_type` : | the name of the image format or `None`
Returns : | A new `gtk.gdk.PixbufLoader` object.

Creates a new `gtk.gdk.PixbufLoader` object. If `image_type` is not specified or is `None` the image type will be automatically deduced from the image data. If `image_type` is specified the `gtk.gdk.PixbufLoader` attempts to parse the image data as if it were an image of the specified type. Identifying the image type 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.

This constructor raises the GError exception if an error occurs trying to load the module for `image_type`.

## Methods

### gtk.gdk.PixbufLoader.write

        def write(buf, count=-1)

`buf` : | a string containing some portion of the image data.
`count` : | the length of `buf` in bytes.
Returns : | `TRUE` if the write was successful.

The `write`() method causes the pixbuf loader to parse the bytes of an image contained in the string specified by `buf`. If `count` is specified and is in the range (0, len(buf)) only `count` bytes of `buf` are used. This method returns `TRUE` if the image data was loaded successfully. If an error occurred this method raises the GError exception and will not accept further writes. The loader may or may not be closed depending on the error.

### gtk.gdk.PixbufLoader.get_pixbuf

        def get_pixbuf()

Returns : | the `gtk.gdk.Pixbuf` that the loader is creating, or `None` if not enough data has been read to determine how to create the image buffer.

The `get_pixbuf`() method returns the `gtk.gdk.Pixbuf` that a pixbuf loader is currently creating. In general it only makes sense to call this method after the "area-prepared" signal has been emitted by the loader which 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 the `write`() method, this method returns `None`. The same pixbuf will be returned in all future calls to this method. Also, if the loader is an animation, it will return the "static image" of the animation (see the `gtk.gdk.PixbufAnimation.get_static_image`() method).

### gtk.gdk.PixbufLoader.get_animation

        def get_animation()

Returns : | the `gtk.gdk.PixbufAnimation` that the loader is loading, or `None` if not enough data has been read to determine the information.

The `get_animation`() method returns the `gtk.gdk.PixbufAnimation` that the pixbuf loader is currently creating. In general it only makes sense to call this method after the "area-prepared" signal has been emitted by the loader. If the loader doesn't have enough bytes yet (hasn't emitted the "area-prepared" signal) this method will return `None`.

### gtk.gdk.PixbufLoader.close

        def close()

Returns : | `TRUE` if all image data written so far was successfully passed out via the "area_update" signal

The `close`() method informs the pixbuf loader that no further writes using the `write`() will occur, so that it can free its internal loading structures. Also, the pixbuf loader tries to parse any data that hasn't yet been parsed and if the remaining data is partial or corrupt, the GError exception will be raised.

### gtk.gdk.PixbufLoader.set_size

        def set_size(width, height)

`width` : | The desired width for the image being loaded.
`height` : | The desired height for the image being loaded.

### Note

This method is available in PyGTK 2.4 and above.

The `set_size`() method causes the image to be scaled to the size specified by `width` and `height` while it is being loaded. The desired image size can be determined relative to the original size of the image by calling the `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".

### gtk.gdk.PixbufLoader.get_format

        def get_format()

Returns : | a Python dict containing the image format information or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `get_format`() method returns the available information about the format of the currently loading image file. This method returns None if their is no information available e.g. before the image has started loading.

## Functions

### gtk.gdk.pixbuf_loader_new_with_mime_type

        def gtk.gdk.pixbuf_loader_new_with_mime_type(mime_type)

`mime_type` : | the mime type to be loaded
Returns : | a new `gtk.gdk.PixbufLoader` object.

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.gdk.pixbuf_loader_new_with_mime_type`() function creates a new pixbuf loader object that always attempts to parse image data as if it were an image of the mime type specified by `mime_type`, instead of identifying the type automatically. 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.

This function raises the GError exception if an error occurs during the loading of the mime type image module.

## Signals

### The "area-prepared" gtk.gdk.PixbufLoader Signal

        def callback(pixbufloader, user_param1, ...)

`pixbufloader` : | the pixbufloader that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "area-prepared" signal is emitted when sufficient image data has been received and parsed to determine the size of the image.

### The "area-updated" gtk.gdk.PixbufLoader Signal

        def callback(pixbufloader, x, y, width, height, user_param1, ...)

`pixbufloader` : | the pixbufloader that received the signal
`x` : | the X coordinate of the region
`y` : | the Y coordinate of the region
`width` : | the width of the region
`height` : | the height of the region
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "area-updated" signal is emitted when sufficient image data has been received and parsed to allow the region specified by `x`, `y`, `width` and `height` to be displayed.

### The "closed" gtk.gdk.PixbufLoader Signal

        def callback(pixbufloader, user_param1, ...)

`pixbufloader` : | the pixbufloader that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "closed" signal is emitted when the `pixbufloader` is closed by calling the `close`() method.

### The "size-prepared" gtk.gdk.PixbufLoader Signal

        def callback(pixbufloader, width, height, user_param1, ...)

`pixbufloader` : | the pixbufloader that received the signal
`width` : | the original width of the image
`height` : | he original height of the image
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.2 and above.

The "size-prepared" 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 the `set_size`() method in response to this signal to set the desired size of the image.

Prev | Up | Next
gtk.gdk.PixbufAnimationIter | Home | gtk.gdk.Pixmap