NAME

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

Description

A Symbol containing pointers to a set of different Symbols. The 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 $image0 which is the image that is drawn if no other image is used. You can then use add() or 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 MultiImage with up to 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 PUSHED is later than the 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 2^n where 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 STATE) then fewer images are necessary.

Useful flags are:

INACTIVE_R

STATE

True for button that is turned on.

HIGHLIGHT

True when the mouse is over widget or pushing it (you must also set highlight_color() to non-zero or most widgets will not redraw because they don't think they changed appearance).

PUSHED

True if user is pushing button.

FOCUSED

True if button has the keyboard focus.

...import these with the :flags tag.

Functions

_draw

$multiimage->_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 $image0 is drawn.

_measure

my @xy = $multiimage->_measure( );

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

add

$multiimage->add( $flags, $image );

Makes it draw $image if all of the $flags are turned on in drawflags().

If $flags is zero, this replaces the image0 that was provided to the constructor. Otherwise, if any image with $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.

current_image

my $image = $multiimage->current_image( );

Return the image that will be drawn according to the current value of drawflags(). The last image with all the flags specified for it turned on will be drawn. If none of them match then $image0 (the first one passed to the constructor) is returned.

fills_rectangle

my $does = $multiimage->fills_rectangle( );

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

inset

$multiimage->inset( $rect );

Calls the same image that _draw() will call to get the inset.

is_frame

my $frame = $multiimage->is_frame( );

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

new

my $self = $multiimage->new( );

For constructing list of MultiImages using set() for post initialization.

release

$multiimage->release( );

Destroys everything except image0.

Author

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

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 The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

cpanm FLTK

perl -MCPAN -e shell
install FLTK