.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Xpm 3"
.TH Xpm 3 "2000-11-09" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Image::Xpm \- Load, create, manipulate and save xpm image files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Image::Xpm;
\&
\&    my $j = Image::Xpm\->new(\-file, \*(AqCamel.xpm\*(Aq);
\&
\&    my $i = Image::Xpm\->new(\-width => 10, \-height => 16);
\&
\&    my $h = $i\->new; # Copy of $i
\&
\&    $i\->xy(5, 8, \*(Aqred\*(Aq);       # Set a colour (& add to palette if necessary)
\&    print $i\->xy(9, 3);        # Get a colour
\&
\&    $i\->xy(120, 130, \*(Aq#1256DD\*(Aq);
\&    $i\->xy(120, 130, $i\->rgb2colour(66, 0x4D, 31));
\&
\&    $i\->vec(24, \*(Aq#808080\*(Aq);    # Set a colour using a vector offset
\&    print $i\->vec(24);         # Get a colour using a vector offset
\&
\&    print $i\->get(\-width);     # Get and set object attributes
\&    $i\->set(\-height, 15);
\&
\&    $i\->load(\*(Aqtest.xpm\*(Aq);
\&    $i\->save;
\&
\&    # Changing just the palette
\&    $i\->add_colours(qw(red green blue #123456 #C0C0C0));
\&    $i\->del_colour(\*(Aqblue\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class module provides basic load, manipulate and save functionality for
the xpm file format. It inherits from \f(CW\*(C`Image::Base\*(C'\fR which provides additional
manipulation functionality, e.g. \f(CW\*(C`new_from_image()\*(C'\fR. See the \f(CW\*(C`Image::Base\*(C'\fR
pod for information on adding your own functionality to all the Image::Base
derived classes.
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 3
\&    my $i = Image::Xpm\->new(\-file => \*(Aqtest.xpm\*(Aq);
\&    my $j = Image::Xpm\->new(\-width => 12, \-height => 18);
\&    my $k = $i\->new;
.Ve
.PP
We can create a new xpm image by reading in a file, or by creating an image
from scratch (all the pixels are white by default), or by copying an image
object that we created earlier.
.PP
If we set \f(CW\*(C`\-file\*(C'\fR then all the other arguments are ignored (since they're
taken from the file). If we don't specify a file, \f(CW\*(C`\-width\*(C'\fR and \f(CW\*(C`\-height\*(C'\fR are
mandatory and \f(CW\*(C`\-cpp\*(C'\fR will default to 1 unless specified otherwise.
.ie n .IP """\-file""" 4
.el .IP "\f(CW\-file\fR" 4
.IX Item "-file"
The name of the file to read when creating the image. May contain a full path.
This is also the default name used for \f(CW\*(C`load\*(C'\fRing and \f(CW\*(C`save\*(C'\fRing, though it
can be overridden when you load or save.
.ie n .IP """\-width""" 4
.el .IP "\f(CW\-width\fR" 4
.IX Item "-width"
The width of the image; taken from the file or set when the object is created;
read-only.
.ie n .IP """\-height""" 4
.el .IP "\f(CW\-height\fR" 4
.IX Item "-height"
The height of the image; taken from the file or set when the object is created;
read-only.
.ie n .IP """\-cpp""" 4
.el .IP "\f(CW\-cpp\fR" 4
.IX Item "-cpp"
Characters per pixel. Commonly 1 or 2, default is 1 for images created by the
module; read-only.
.Sp
See the example for how to change an image's cpp.
.ie n .IP """\-hotx""" 4
.el .IP "\f(CW\-hotx\fR" 4
.IX Item "-hotx"
The x\-coord of the image's hotspot; taken from the file or set when the object
is created. Set to \-1 if there is no hotspot.
.ie n .IP """\-hoty""" 4
.el .IP "\f(CW\-hoty\fR" 4
.IX Item "-hoty"
The y\-coord of the image's hotspot; taken from the file or set when the object
is created. Set to \-1 if there is no hotspot.
.ie n .IP """\-ncolours""" 4
.el .IP "\f(CW\-ncolours\fR" 4
.IX Item "-ncolours"
The number of unique colours in the palette. The image may not be using all
of them; read-only.
.ie n .IP """\-cindex""" 4
.el .IP "\f(CW\-cindex\fR" 4
.IX Item "-cindex"
An hash whose keys are colour names, e.g. '#123456' or 'blue' and whose values
are the palette names, e.g. ' ', '#', etc; read-only. If you want to add more
colours to the image itself simply write pixels with the new colours using
\&\f(CW\*(C`xy\*(C'\fR; if you want to add more colours to the palette without necessarily
using them in the image use \f(CW\*(C`add_colours\*(C'\fR.
.ie n .IP """\-palette""" 4
.el .IP "\f(CW\-palette\fR" 4
.IX Item "-palette"
A hash whose keys are the palette names, e.g. ' ', '#', etc. and whose values
are hashes of colour type x colour name pairs, e.g. \f(CW\*(C`c => red\*(C'\fR, etc;
read-only. If you want to add more colours to the image itself simply write
pixels with the new colours using \f(CW\*(C`xy\*(C'\fR; if you want to add more colours to
the palette without necessarily using them in the image use \f(CW\*(C`add_colours\*(C'\fR.
.ie n .IP """\-pixels""" 4
.el .IP "\f(CW\-pixels\fR" 4
.IX Item "-pixels"
A string of palette names which constitutes the data for the image itself;
read-only.
.ie n .IP """\-extname""" 4
.el .IP "\f(CW\-extname\fR" 4
.IX Item "-extname"
The name of the extension text if any; commonly \s-1XPMEXT\s0; read-only.
.ie n .IP """\-extlines""" 4
.el .IP "\f(CW\-extlines\fR" 4
.IX Item "-extlines"
The lines of text of any extensions; read-only.
.ie n .IP """\-comments""" 4
.el .IP "\f(CW\-comments\fR" 4
.IX Item "-comments"
An array (possibly empty) of comment lines that were in a file that was read
in; they will be written out although we make no guarantee regarding their
placement; read-only.
.SS "\fIget()\fP"
.IX Subsection "get()"
.Vb 2
\&    my $width = $i\->get(\-width);
\&    my ($hotx, $hoty) = $i\->get(\-hotx, \-hoty);
.Ve
.PP
Get any of the object's attributes. Multiple attributes may be requested in a
single call.
.PP
See \f(CW\*(C`xy\*(C'\fR and \f(CW\*(C`vec\*(C'\fR to get/set colours of the image itself.
.SS "\fIset()\fP"
.IX Subsection "set()"
.Vb 1
\&    $i\->set(\-hotx => 120, \-hoty => 32);
.Ve
.PP
Set any of the object's attributes. Multiple attributes may be set in a single
call; some attributes are read-only.
.PP
See \f(CW\*(C`xy\*(C'\fR and \f(CW\*(C`vec\*(C'\fR to get/set colours of the image itself.
.SS "\fIxy()\fP"
.IX Subsection "xy()"
.Vb 2
\&    $i\->xy(4, 11, \*(Aq#123454\*(Aq);    # Set the colour at point 4,11
\&    my $v = $i\->xy(9, 17);       # Get the colour at point 9,17
.Ve
.PP
Get/set colours using x, y coordinates; coordinates start at 0. If the colour
does not exist in the palette it will be added automatically.
.PP
When called to set the colour the value returned is characters used for that
colour in the palette; when called to get the colour the value returned is the
colour name, e.g. 'blue' or '#f0f0f0', etc, e.g.
.PP
.Vb 2
\&    $colour = xy($x, $y);            # e.g. #123456 
\&    $cc     = xy($x, $y, $colour);   # e.g. !
.Ve
.PP
We don't normally pick up the return value when setting the colour.
.SS "\fIvec()\fP"
.IX Subsection "vec()"
.Vb 2
\&    $i\->vec(43, 0);      # Unset the bit at offset 43
\&    my $v = $i\->vec(87); # Get the bit at offset 87
.Ve
.PP
Get/set bits using vector offsets; offsets start at 0. The offset of a pixel
is ((y * width * cpp) + (x * cpp)).
.PP
The sort of return value depends on whether we are reading (getting) or
writing (setting) the colour \- see \f(CW\*(C`xy\*(C'\fR for an explanation.
.SS "\fIrgb2colour()\fP and \fIrgb2color()\fP"
.IX Subsection "rgb2colour() and rgb2color()"
.Vb 2
\&    $i\->rgb2colour(0xff, 0x40, 0x80);    # Returns #ff4080
\&    Image::Xpm\->rgb2colour(10, 20, 30);  # Returns #0a141e
.Ve
.PP
Convenience class or object methods which accept three integers and return a
colour name string.
.SS "\fIload()\fP"
.IX Subsection "load()"
.Vb 2
\&    $i\->load;
\&    $i\->load(\*(Aqtest.xpm\*(Aq);
.Ve
.PP
Load the image whose name is given, or if none is given load the image whose
name is in the \f(CW\*(C`\-file\*(C'\fR attribute.
.SS "\fIsave()\fP"
.IX Subsection "save()"
.Vb 2
\&    $i\->save;
\&    $i\->save(\*(Aqtest.xpm\*(Aq);
.Ve
.PP
Save the image using the name given, or if none is given save the image using
the name in the \f(CW\*(C`\-file\*(C'\fR attribute. The image is saved in xpm format.
.SS "\fIadd_colours()\fP and \fIadd_colors()\fP"
.IX Subsection "add_colours() and add_colors()"
.Vb 1
\&    $i\->add_colours(qw(#C0C0DD red blue #123456));
.Ve
.PP
These are for adding colours to the palette; you don't need to use them to set
a pixel's colour \- use \f(CW\*(C`xy\*(C'\fR for that.
.PP
Add one or more colour names either as hex strings or as literal colour names.
These are always added as type 'c' colours; duplicates are ignored.
.PP
\&\s-1NB\s0 If you just want to set some pixels in colours that may not be in the
palette, simply do so using \f(CW\*(C`xy\*(C'\fR since new colours are added automatically.
.SS "\fIdel_colour()\fP and \fIdel_color()\fP"
.IX Subsection "del_colour() and del_color()"
.Vb 1
\&    $i\->del_colour(\*(Aqgreen\*(Aq);
.Ve
.PP
Delete a colour from the palette; returns undef if the colour isn't in the
palette, false (0) if the colour is in the palette but also in the image, or
true (1) if the colour has been deleted (i.e. it was in the palette but not in
use in the image).
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.SS "Changing the \-cpp of an image:"
.IX Subsection "Changing the -cpp of an image:"
.Vb 3
\&    my $i = Image::Xpm(\-file => \*(Aqtest1.xpm\*(Aq); # test1.xpm has cpp == 1
\&    my $j = $i\->new_from_image(\*(AqImage::xpm\*(Aq, \-cpp => 2);
\&    $j\->save(\*(Aqtest2.xpm\*(Aq);
\&
\&    # Could have written 2nd line above as:
\&    my $j = $i\->new_from_image(ref $i, \-cpp => 2);
.Ve
.SH "CHANGES"
.IX Header "CHANGES"
2000/11/09
.PP
Added Jerrad Pierce's patch to allow \fIload()\fR to accept filehandles or strings;
will document in next release.
.PP
2000/10/19
.PP
Fixed bugs in \fIxy()\fR and \fIvec()\fR reported by Pat Gunn.
.PP
2000/05/25
.PP
Fixed a bug in the test file; fixed a bug in \fIsave()\fR which affected xpm
extensions.
.PP
2000/05/04
.PP
Fixed bugs in \fIxy()\fR, \fIvec()\fR, \fIsave()\fR and \fIload()\fR. 
Improved the test program.
.PP
2000/05/03
.PP
Created.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mark Summerfield. I can be contacted as <summer@perlpress.com> \-
please include the word 'xpm' in the subject line.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) Mark Summerfield 2000. All Rights Reserved.
.PP
This module may be used/distributed/modified under the \s-1GPL. \s0
