NAME

Image::Base::Tk::Photo -- draw with Tk::Photo

SYNOPSIS

 use Image::Base::Tk::Photo;
 my $image = Image::Base::Tk::Photo->new (-for_widget => $mw,
                                          -width => 100,
                                          -height => 100);
 $image->rectangle (0,0, 99,99, 'white');
 $image->xy (20,20, 'black');
 $image->line (50,50, 70,70, '#FF00FF');
 $image->line (50,70, 70,50, '#0000AAAA9999');
 $image->save ('/some/filename.png');

CLASS HIERARCHY

Image::Base::Tk::Photo is a subclass of Image::Base,

    Image::Base
      Image::Base::Tk::Photo

DESCRIPTION

Image::Base::Tk::Photo extends Image::Base to create or update image files using the Tk::Photo module from Perl-Tk.

See Tk::Photo for the supported file formats. Perl-Tk 804 includes

   PNG, JPEG, XPM, XBM, GIF, BMP, PPM/PGM

   TIFF    separate Tk::TIFF module

A Tk::Photo requires a Tk::MainWindow and so an X display (etc), though there's no need to actually display the MainWindow. Drawing operations use the Photo pixel/rectangle put().

For reference, to draw arbitrary graphics in Perl-Tk the choice is between a Tk::Canvas with arcs etc, or a Tk::Photo of pixels which is set as the -image of a Tk::Label or similar. Is that right? No drawing area widget as such?

Colours

Colour names are anything recognised by Tk_GetColor(3tk), plus "None",

    X server names     usually /etc/X11/rgb.txt
    #RGB               hex
    #RRGGBB            hex
    #RRRGGGBBB         hex
    #RRRRGGGGBBBB      hex
    None               transparent

The hex forms end up going to Xlib which means the shorter ones are padded with zeros, so "#FFF" is "#F000F000F000" which is a light grey rather than white. See X(7) "COLOR NAMES".

"None" means a transparent pixel, as per $tkphoto->transparencySet().

FUNCTIONS

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

$image = Image::Base::Tk::Photo->new (key=>value,...)

Create and return a new image object. It can be given an existing Tk::Photo,

    $image = Image::Base::Tk::Photo->new (-tkphoto => $tkphoto);

Or it can create a new Tk::Photo. The -for_widget option gives a widget hierarchy where the new Tk::Photo will be used. A toplevel Tk::MainWindow is suitable.

    $image = Image::Base::Tk::Photo->new (-for_widget => $widget);

-width and -height size can be given. Zero or omitted gives the usual auto-sizing of Tk::Photo.

    $image = Image::Base::Tk::Photo->new (-for_widget => $widget,
                                          -width => 200,
                                          -height => 100);

Or a file can be read,

    $image = Image::Base::Tk::Photo->new
                (-for_widget => $widget,
                 -file => '/some/filename.xpm');

A Tk::Photo must be explicitly destroyed with $tkphoto->delete() the same as all Tk::Image types (see Tk::Image). Image::Base::Tk::Photo doesn't currently do that in its own destruction. Should it do so when it created the photo? But probably don't want to destroy when merely set in as a -tkphoto.

$new_image = $image->new (key=>value,...)

This is supposed to clone the image object, but it's not implemented yet. How to clone a Tk::Photo?

$image->load ()

$image->load ($filename)

Read the current -file, or set -file to $filename and then read.

The file format is recognised automatically by Tk::Photo from the formats registered. Some formats are builtin, but for PNG, JPEG and TIFF the corresponding format modules Tk::PNG, Tk::JPEG or Tk::TIFF must be used first. For example,

    use Tk::PNG;
    $image->load ('/my/filename.png');

$image->save ()

$image->save ($filename)

Save to -file, or with a $filename argument set -file then save to that.

The saved file format is taken from -file_format (see "ATTRIBUTES" below) if that was set, either from a load() or explicit set().

For convenience, when saving PNG, JPEG and TIFF the necessary Tk::PNG, Tk::JPEG or Tk::TIFF module is loaded automatically. Any other non-builtin formats will require their modules loaded before attempting a save().

ATTRIBUTES

-width (integer)

-height (integer)

Setting these changes the size of the image.

-tkphoto

The underlying Tk::Photo object.

-file_format (string or undef)

The file format as a string like "png" or "jpeg", or undef if unknown or never set.

After load the -file_format is the format read. Setting -file_format can change the format for a subsequent save().

There's no attempt to check or validate the -file_format value since it's possible to add new formats to Tk::Photo at run time. Expect save() to croak if the format is unknown.

SEE ALSO

Tk::Photo, Image::Base, Image::Base::Tk::Canvas

HOME PAGE

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

LICENSE

Image-Base-Tk is Copyright 2010, 2011, 2012 Kevin Ryde

Image-Base-Tk 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-Tk 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-Tk. If not, see <http://www.gnu.org/licenses/>.

cpanm Image::Base::Tk::Photo

perl -MCPAN -e shell
install Image::Base::Tk::Photo