gtk.gdk.PixbufLoader — an object providing application-driven progressive image loading
class gtk.gdk.PixbufLoader( |
Functions
def gtk.gdk.pixbuf_loader_new_with_mime_type(mime_type) def callback( | |
def callback( | |
"closed" | def callback( |
def callback( |
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 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.
gtk.gdk.PixbufLoader(image_type=None)
| 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.
def write(buf, count=-1)
| a string containing some portion of the image data. |
| 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.
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).
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.
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.
def set_size(width, height)
| The desired width for the image being loaded. |
| The desired height for the image being loaded. |
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".
def get_format()Returns : | a Python dict containing the image format
information or None |
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.
def gtk.gdk.pixbuf_loader_new_with_mime_type(mime_type)
| the mime type to be loaded |
Returns : | a new gtk.gdk.PixbufLoader
object. |
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.
def callback(pixbufloader, user_param1, ...)
| the pixbufloader that received the signal |
| the first user parameter (if any) specified
with the connect() |
| 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.
def callback(pixbufloader, x, y, width, height, user_param1, ...)
| the pixbufloader that received the signal |
| the X coordinate of the region |
| the Y coordinate of the region |
| the width of the region |
| the height of the region |
| the first user parameter (if any) specified
with the connect() |
| 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.
def callback(pixbufloader, user_param1, ...)
| the pixbufloader that received the signal |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
The "closed" signal is emitted when the
pixbufloader is closed by calling the close()
method.
def callback(pixbufloader, width, height, user_param1, ...)
| the pixbufloader that received the signal |
| the original width of the image |
| he original height of the image |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
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.