NAME

Image::Base::Wx::Image -- draw into a Wx::Image

SYNOPSIS

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

CLASS HIERARCHY

Image::Base::Wx::Image is a subclass of Image::Base,

    Image::Base
      Image::Base::Wx::Image

DESCRIPTION

Image::Base::Wx::Image extends Image::Base to draw into a Wx::Image.

A Wx::Image is platform-independent 24-bit RGB image. Drawing is done with SetRGB() of pixels and rectangles. A Wx::Image cannot be drawn with Wx::DC or displayed directly, though it can be converted to a platform-dependent Wx::Bitmap for display.

File Formats

The file formats supported in Wx 2.8 include the following, perhaps depending which supporting libraries it was built with.

    BMP      always available
    PNG
    JPEG
    GIF      load-only
    PCX
    PNM
    TIFF
    TGA      load-only
    IFF      load-only
    XPM
    ICO
    CUR
    ANI      load-only

Each format has a Wx::ImageHandler class. save() creates a handler for the target -file_format as necessary. load() attempts all the globally registered handlers. All formats can be registered with

    Wx::InitAllImageHandlers();

Or just selected ones with for example

    Wx::Image::AddHandler (Wx::PNGHandler->new);

Colour Names

Colour names are 1 to 4 digit hex and anything recognised by Wx::ColourDatabase,

    "pink" etc        wxColourDatabase
    "#RGB"            1 to 4 digit hex
    "#RRGGBB"
    "#RRRGGGBBB"
    "#RRRRGGGGBBB"
    "None"            transparent

Special colour "None" means transparent, which is applied by SetAlpha() on the drawn pixels. The way it's done here is slightly experimental yet. In the current code drawing a colour doesn't turn pixels back to opaque. The intention would be that it should, but don't really want to do a SetAlpha call on top of SetRGB for every pixel.

FUNCTIONS

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

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

Create and return a new image object. It can read a file,

    $image = Image::Base::Wx::Image->new
               (-file => '/my/file/name.bmp');

Or start a new image created with width and height,

    $image = Image::Base::Wx::Image->new
                 (-width  => 200,
                  -height => 100);

Or be pointed at an existing wxImage object,

    my $wximage = Wx::Image->new (200, 100);
    my $image = Image::Base::Wx::Image->new
                 (-wximage => $wximage);

Further parameters are applied per set (see "ATTRIBUTES" below).

$image->xy ($x, $y, $colour)

Get or set the pixel at $x,$y.

Getting a pixel is per Wx::Image GetPixel(). In the current code colours are returned in "#RRGGBB" form.

$image->load ()

$image->load ($filename)

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

The file format is detected by attempting each of the globally added image format handlers.

Currently the possible formats are a hard-coded list, but the intention would be to use Wx::Image::GetHandlers if/when available. The repeated load attempts probably means a seekable file is required, so some special devices are no good. Perhaps could be improved by automatically copying to a tempfile if necessary.

$image->save ()

$image->save ($filename)

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

An existing handler for the -file_format from FindHandler is used if registered. Otherwise a handler is created for the purpose with Wx::PNGHandler etc (but not added to the globals with AddHandler).

If -file_format is not set then the current code doesn't look at the $filename extension such as ".png" etc the way the underlying $wximage->SaveFile() does. Perhaps it could do so in the future.

ATTRIBUTES

-wximage (Wx::Image object)

The target Wx::Image.

-file_format (string, default undef)

The file format from the last load() and the format to use in save(). This is one of the wxBITMAP_TYPE_XXX names such as "PNG" or "JPEG".

-width (integer)

-height (integer)

The size of the image. These are per $wximage->GetWidth() and $wximage->GetHeight().

Setting these resizes the image with $wximage->Resize(), filling any expanded area with black.

-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 Wx default.

This is the quality for $wximage->GetOption() and $wximage->SetOption().

-hotx (integer or undef, default undef)

-hoty (integer or undef, default undef)

The cursor hotspot in CUR images.

These are wxIMAGE_OPTION_CUR_HOTSPOT_X and wxIMAGE_OPTION_CUR_HOTSPOT_Y to $wximage->GetOption() and $wximage->SetOption().

(XPM format has an optional hotspot too, but Wx circa 2.8.12 doesn't seem to read it.)

SEE ALSO

Wx, Image::Base, Image::Base::Wx::DC

HOME PAGE

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

LICENSE

Copyright 2012 Kevin Ryde

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

cpanm Image::Base::Wx::DC

perl -MCPAN -e shell
install Image::Base::Wx::DC