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