NAME

Image::Base::Gtk2::Gdk::Pixbuf -- draw image files using Gtk2::Gdk::Pixbuf

SYNOPSIS

 use Image::Base::Gtk2::Gdk::Pixbuf;
 my $image = Image::Base::Gtk2::Gdk::Pixbuf->new
                 (-width => 100,
                  -height => 100);
 $image->line (0,0, 99,99, '#FF00FF');
 $image->rectangle (10,10, 20,15, 'white');

CLASS HIERARCHY

Image::Base::Gtk2::Gdk::Pixbuf is a subclass of Image::Base,

    Image::Base
      Image::Base::Gtk2::Gdk::Pixbuf

DESCRIPTION

Image::Base::Gtk2::Gdk::Pixbuf extends Image::Base to create and update image files using GdkPixbuf. PNG and JPEG can always be read and written, and in recent Gtk also TIFF, ICO and BMP. Many further formats can be read but not written, including XPM, GIF, XBM and PCX.

Pixbufs are held in client-side memory and don't require an X server or Gtk2->init(), which means they can be used for general-purpose image and image file manipulations.

The current drawing code is not very fast, but if you've got some pixel twiddling in Image::Base style then this is a handy way to have it read or write several file formats.

Colour Names

Colour names are anything recognised by Gtk2::Gdk::Color->parse(), which means various names like "pink" plus hex #RRGGBB or #RRRRGGGGBBB. As of Gtk 2.20 the names are from the Pango compiled-in copy of the X11 rgb.txt. Special colour "None" means a transparent pixel on a pixbuf with an "alpha" channel.

Only 8-bit RGB or RGBA pixbufs are supported by this module. This is all that Gtk 2.20 itself supports too.

FUNCTIONS

See "FUNCTIONS" in Image::Base for the behaviour common to all Image-Base classes.

$image = Image::Base::Gtk2::Gdk::Pixbuf->new (key=>value,...)

Create and return a new GdkPixbuf image object. It can be pointed at an existing pixbuf,

    $image = Image::Base::Gtk2::Gdk::Pixbuf->new
                 (-pixbuf => $gdkpixbuf);

Or a file can be read,

    $image = Image::Base::Gtk2::Gdk::Pixbuf->new
                 (-file => '/my/file/name.jpeg');

Or a new pixbuf created with width and height,

    $image = Image::Base::Gtk2::Gdk::Pixbuf->new
                 (-width  => 10,
                  -height => 10);

When creating a pixbuf an alpha channel (transparency) can be requested with -has_alpha,

    $image = Image::Base::Gtk2::Gdk::Pixbuf->new
                 (-width     => 10,
                  -height    => 10,
                  -has_alpha => 1);

$image->load ()

$image->load ($filename)

Read the -file, or set -file to $filename and then read. This creates and sets a new underlying -pixbuf because it's not possible to read into an existing pixbuf object, only read a new one. -file_format is set from the loaded file's format.

$image->save ()

$image->save ($filename)

Write the -file, or set -file to $filename and then write. -file_format is the saved format.

If -file_format is not set there's a secret experimental feature which looks up the -file filename extension in the available pixbuf formats. Is that a good idea, or would just say png fallback be better?

Some formats can be loaded but not saved. png and jpeg can be saved always, then ico in Gtk 2.4 up, bmp in Gtk 2.8 up, and tiff in Gtk 2.10 up.

ATTRIBUTES

-pixbuf (Gtk2::Gdk::Pixbuf object)

The target Gtk2::Gdk::Pixbuf object.

-file_format (string, default undef)

The file format from the last load and to use in save. This is one of the GdkPixbuf format names such as "png" or "jpeg", in upper or lower case.

-width (integer, read-only)

-height (integer, read-only)

The size of a pixbuf cannot be changed once created.

-has_alpha (boolean, read-only)

Whether the underlying pixbuf has a alpha channel, meaning a transparency mask (or partial transparency). This cannot be changed once created.

-quality_percent (0 to 100 or undef)

The image quality when saving to JPEG format. JPEG compresses by reducing colours and resolution in ways that are not too noticeable to the human eye. 100 means full quality, no such reductions. undef means the GdkPixbuf default, which is 75.

This becomes the quality parameter to $pixbuf->save().

-zlib_compression (integer, no default)

The Zlib compression level to use when saving.

This becomes the compress parameter to $pixbuf->save() if applicable (only "png" format currently) and if possible (which means Gtk 2.8.0 up).

-hotx (integer or undef, default undef)

-hoty (integer or undef, default undef)

The cursor hotspot in xpm and ico images.

These are loaded from xpm and ico files in Gtk 2.2 up (get_option "x_hot" and "y_hot"), and are saved to ico in Gtk 2.4 and higher (ico saving is new in Gtk 2.4, and there's no xpm saving as of Gtk 2.22).

In the current code these are treated as belonging to the pixbuf, so a new pixbuf set or loaded replaces -hotx or -hoty. But the settings are not held in the pixbuf as such since as of Gtk 2.22 $pixbuf->set_option won't replace existing option values in the pixbuf.

SEE ALSO

Image::Base, Gtk2::Gdk::Pixbuf, Image::Xpm

HOME PAGE

http://user42.tuxfamily.org/image-base-gtk2/index.html

LICENSE

Copyright 2010, 2011, 2012 Kevin Ryde

Image-Base-Gtk2 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Image-Base-Gtk2 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Image-Base-Gtk2. If not, see http://www.gnu.org/licenses/.