=pod

=head1 NAME

FLTK::MultiImage - Image type that draws a different image depending on the flags

=head1 Description

A L<Symbol|FLTK::Symbol> containing pointers to a set of different
L<Symbol|FLTK::Symbol>s. The L<C<drawflags()>|FLTK::MultiImage/"drawflags">
are used to select which one to draw. This is most useful for making an image
for a button that is different depending on whether it is pushed in, the
current value is on, or when the mouse is over it.

The basic constructor takes the C<$image0> which is the image that is drawn if
no other image is used. You can then use L<C<add()>|FLTK::MultiImage/"add"> or
L<C<replace()>|FLTK::MultiImage/"replace"> to add pairs of images and flags.
These are searched and the last one where all it's flags are turned on is
used. There are also inline constructors so that a fully-populated
L<MultiImage|FLTK::MultiImage> with up to C<8> images can be declared inline.

Typical example:

    my $buttonImage = FLTK::MultiImage->new(
                          $OffImage,
        STATE,            $OnImage,
        INACTIVE_R,       $DimOffImage,
        INACTIVE_R|STATE, $DimOnImage,
        FOCUSED,          $FocusedOffImage,
        FOCUSED|STATE,    $FocusedOnImage,
        HIGHLIGHT,        $BrightOffImage,
        HIGHLIGHT|STATE,  $BrightOnImage,
        PUSHED,           $BrightPushedOffImage,
        PUSHED|STATE,     $BrightPushedOnImage
    );

In the above example, because the C<PUSHED> is later than the C<FOCUSED>, when
the user pushes the button and it has the focus they will see the pushed
image. If they were the other way around they would see the focused image and
not see any feedback from pushing the button. In addition, although the
highlight or focus should not turn on for an inactive widget, this will show
if it happens.

Also note that the number of images is less than C<2^n> where C<n> is the
number of flags you care about. This seems to be true of most hand-painted
image sets. The user probably does not care or is confused by showing the
focus or highlight state of a button they are pushing.

A fully-populated example like the above is not necessary, as the flags are
passed to the sub-images. If they respond to them (for instance drawing
differently depending on C<STATE>) then fewer images are necessary.

Useful flags are:

=over 

=item C<INACTIVE_R>

=item C<STATE>

True for button that is turned on.

=item C<HIGHLIGHT>

True when the mouse is over widget or pushing it (you must also set
L<C<highlight_color()>|FLTK::Color/"highlight_color"> to non-zero or most
widgets will not redraw because they don't think they changed appearance).

=item C<PUSHED>

True if user is pushing button.

=item C<FOCUSED>

True if button has the keyboard focus.

=back 

...import these with the C<:flags> tag.

=head1 Functions

=head2 C<_draw>
X<_draw>

=over

=item C<$multiimage-E<gt>_draw( $rect );>X<_multiimage_E_gt__draw_rect_>

Select one of the images and draw it. The last image with all the flags
specified for it turned on will be drawn. If none of them match then
C<$image0> is drawn.

=for hackers xs/MultiImage.xs line 123

=back

=head2 C<_measure>
X<_measure>

=over

=item C<my @xy = $multiimage-E<gt>_measure( );>X<my_xy_multiimage_E_gt__measure_>

It probably is useless for the images to be different sizes. However if they
are, C<$image0> (the first one passed to the constructor) is used to figure
out the size.

=for hackers xs/MultiImage.xs line 111

=back

=head2 C<add>
X<add>

=over

=item C<$multiimage-E<gt>add( $flags, $image );>X<_multiimage_E_gt_add_flags_image_>

Makes it draw C<$image> if B<all> of the C<$flags> are turned on in
L<C<drawflags()>|FLTK::MultiImage/"drawflags">.

If C<$flags> is zero, this replaces the image0 that was provided to the
constructor. Otherwise, if any image with C<$flags> has already been
specified, it is replaced with this image. Otherwise a new pair of flags and
image is added to the end of the list.

=for hackers xs/MultiImage.xs line 176

=back

=head2 C<current_image>
X<current_image>

=over

=item C<my $image = $multiimage-E<gt>current_image( );>X<my_image_multiimage_E_gt_current_image_>

Return the image that will be drawn according to the current value of
L<C<drawflags()>|FLTK::MultiImage/"drawflags">. The B<last> image with all the
flags specified for it turned on will be drawn. If none of them match then
C<$image0> (the first one passed to the constructor) is returned.

=for hackers xs/MultiImage.xs line 135

=back

=head2 C<fills_rectangle>
X<fills_rectangle>

=over

=item C<my $does = $multiimage-E<gt>fills_rectangle( );>X<my_does_multiimage_E_gt_fills_rectangle_>

Returns the info from the first image given to the constructor.

=for hackers xs/MultiImage.xs line 158

=back

=head2 C<inset>
X<inset>

=over

=item C<$multiimage-E<gt>inset( $rect );>X<_multiimage_E_gt_inset_rect_>

Calls the same image that L<C<_draw()>|FLTK::MultiImage/"_draw"> will call to
get the inset.

=for hackers xs/MultiImage.xs line 147

=back

=head2 C<is_frame>
X<is_frame>

=over

=item C<my $frame = $multiimage-E<gt>is_frame( );>X<my_frame_multiimage_E_gt_is_frame_>

Returns the info from the first image given to the constructor.

=for hackers xs/MultiImage.xs line 167

=back

=head2 C<new>
X<new>

=over

=item C<my $self = $multiimage-E<gt>new( );>X<my_self_multiimage_E_gt_new_>

For constructing list of L<MultiImage|FLTK::MultiImage>s using
L<C<set()>|FLTK::MultiImage/"set"> for post initialization.

=for hackers xs/MultiImage.xs line 101

=back

=head2 C<release>
X<release>

=over

=item C<$multiimage-E<gt>release( );>X<_multiimage_E_gt_release_>

Destroys everything except C<image0>.

=pod 

=for hackers xs/MultiImage.xs line 192

=back

=head1 Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

=head1 License and Legal

Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under
the terms of
L<The Artistic License 2.0|http://www.perlfoundation.org/artistic_license_2_0>.
See the F<LICENSE> file included with this distribution or
L<notes on the Artistic License 2.0|http://www.perlfoundation.org/artistic_2_0_notes>
for clarification.

When separated from the distribution, all original POD documentation is
covered by the
L<Creative Commons Attribution-Share Alike 3.0 License|http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>.
See the
L<clarification of the CCA-SA3.0|http://creativecommons.org/licenses/by-sa/3.0/us/>.


=for git $Id: MultiImage.xs c629eeb 2010-09-27 04:12:30Z sanko@cpan.org $

=cut