=pod

=head1 NAME

Fl::Color - Easily Imported Color-related Functions and Static Values

=head1 Synopsis

    use Fl qw[:enum]; # Import with all enums!
    use Fl qw[:color]; # Import just the stuff in here

=head1 Description

This file contains type definitions, general enumerations, and several
functions which can be inported with the C<:color> tag.

Colors are either 8-bit indexes into a virtual colormap or 24-bit RGB color
values. (See Fl::Draw for the default colormap)

Color indices occupy the lower 8 bits of the value, while RGB colors occupy
the upper 24 bits, for a byte organization of RGBI.

    Fl_Color => 0xrrggbbii
                   | | | |
                   | | | +--- index between 0 and 255
                   | | +----- blue color component (8 bit)
                   | +------- green component (8 bit)
                   +--------- red component (8 bit)

=cut

MODULE = Fl        PACKAGE = Fl

BOOT:
=pod

Here's a list of built-in colors:

=over

=item FL_FOREGROUND_COLOR

The default foreground color used for labels and text.

=item FL_BACKGROUND2_COLOR

The default background color for text, list, and valuator widgets.

=item FL_INACTIVE_COLOR

The inactive foreground color.

=item FL_SELECTION_COLOR

The default selection/highlight color.

=item FL_GRAY0

=item FL_DARK3

=item FL_DARK2

=item FL_DARK1

=item FL_BACKGROUND_COLOR

=item FL_LIGHT1

=item FL_LIGHT2

=item FL_LIGHT3

=item FL_BLACK

=item FL_RED

=item FL_GREEN

=item FL_YELLOW

=item FL_BLUE

=item FL_MAGENTA

=item FL_CYAN

=item FL_DARK_RED

=item FL_DARK_GREEN

=item FL_DARK_YELLOW

=item FL_DARK_BLUE

=item FL_DARK_MAGENTA

=item FL_DARK_CYAN

=item FL_WHITE

=back

=cut

    export_constant( "FL_FOREGROUND_COLOR", "color", newSViv(FL_FOREGROUND_COLOR ));
    export_constant( "FL_BACKGROUND2_COLOR","color", newSViv(FL_BACKGROUND2_COLOR ));
    export_constant( "FL_INACTIVE_COLOR",   "color", newSViv(FL_INACTIVE_COLOR ));
    export_constant( "FL_SELECTION_COLOR",  "color", newSViv(FL_SELECTION_COLOR ));
    export_constant( "FL_GRAY0",            "color", newSViv(FL_GRAY0 ));
    export_constant( "FL_DARK3",            "color", newSViv(FL_DARK3 ));
    export_constant( "FL_DARK2",            "color", newSViv(FL_DARK2 ));
    export_constant( "FL_DARK1",            "color", newSViv(FL_DARK1 ));
    export_constant( "FL_BACKGROUND_COLOR", "color", newSViv(FL_BACKGROUND_COLOR ));
    export_constant( "FL_LIGHT1",           "color", newSViv(FL_LIGHT1 ));
    export_constant( "FL_LIGHT2",           "color", newSViv(FL_LIGHT2 ));
    export_constant( "FL_LIGHT3",           "color", newSViv(FL_LIGHT3 ));
    export_constant( "FL_BLACK",            "color", newSViv(FL_BLACK ));
    export_constant( "FL_RED",              "color", newSViv(FL_RED ));
    export_constant( "FL_GREEN",            "color", newSViv(FL_GREEN ));
    export_constant( "FL_YELLOW",           "color", newSViv(FL_YELLOW ));
    export_constant( "FL_BLUE",             "color", newSViv(FL_BLUE ));
    export_constant( "FL_MAGENTA",          "color", newSViv(FL_MAGENTA ));
    export_constant( "FL_CYAN",             "color", newSViv(FL_CYAN ));
    export_constant( "FL_DARK_RED",         "color", newSViv(FL_DARK_RED ));
    export_constant( "FL_DARK_GREEN",       "color", newSViv(FL_DARK_GREEN ));
    export_constant( "FL_DARK_YELLOW",      "color", newSViv(FL_DARK_YELLOW ));
    export_constant( "FL_DARK_BLUE",        "color", newSViv(FL_DARK_BLUE ));
    export_constant( "FL_DARK_MAGENTA",     "color", newSViv(FL_DARK_MAGENTA ));
    export_constant( "FL_DARK_CYAN",        "color", newSViv(FL_DARK_CYAN ));
    export_constant( "FL_WHITE",            "color", newSViv(FL_WHITE ));

=pod

The following functions are also imported with the C<:color> tag.

=over

=item fl_inactive(...)

    my $inactive_red = fl_inactive(FL_RED);

Returns the inactive, dimmed version of the given color.

=cut

Fl_Color
fl_inactive(Fl_Color color)

BOOT:
    export_function("fl_inactive", "color");

=pod

=item fl_contrast(...)

    my $fg = FL_RED;
    my $bg = FL_BLACK;
    my $color = fl_contrast($fg, $bg);

Returns a color that contrasts with the background color.

This will be the foreground color if it contrasts sufficiently with the
background color. Otherwise, returns C<FL_WHITE> or C<FL_BLACK> depending on
which color provides the best contrast.

=cut

Fl_Color
fl_contrast(Fl_Color fg, Fl_Color bg)

BOOT:
    export_function("fl_contrast", "color");

=pod

=item fl_color_average(...)

    my $average = fl_color_average(FL_RED, FL_BLUE, .14);

Returns the weighted average color between the two given colors.

The red, green and blue values are averages using the following formula:

    color = color1 * weight  + color2 * (1 - weight)

Thus, a weight value of 1.0 will return the first color, while a value of 0.0
will return the second color.

=cut

Fl_Color
fl_color_average(Fl_Color c1, Fl_Color c2, float weight)

BOOT:
    export_function("fl_color_average", "color");

=pod

=item fl_lighter(...)

    my $light_red = fl_lighter(FL_RED);

Returns a lighter version of the specified color.

=cut

Fl_Color
fl_lighter(Fl_Color c)

BOOT:
    export_function("fl_lighter", "color");

=pod

=item fl_darker(...)

    my $dark_red = fl_darker(FL_RED);

Returns a darker version of the specified color.

=cut

Fl_Color
fl_darker(Fl_Color c)

BOOT:
    export_function("fl_darker", "color");

=pod

=item fl_rgb_color(...)

    my $color = fl_rgb_color(100, 200, 180);

Returns the 24-bit color value closest to r, b, g.

    my $gray = fl_rgb_color(13);

Returns the 24-bit color value closest to g (grayscale).

=cut

Fl_Color
fl_rgb_color(uchar r, uchar g = NO_INIT, uchar b = NO_INIT)

BOOT:
    export_function("fl_rgb_color", "color");

=pod

=item fl_gray_ramp(...)

    my $gray = fl_gray_ramp(20 / 255);

Returns a gray color value scaled from black to white.

=cut

Fl_Color
fl_gray_ramp(int i)

BOOT:
    export_function("fl_gray_ramp", "color");

=pod

=item fl_color_cube(...)

    my ($r, $g, $b) = (200, 180, 0);
    my $color = fl_color_cube($r, $b, $g);

Returns a color out of the color cube.

C<$r> must be in the range 0 to FL_NUM_RED - 1,
C<$g> must be in the range 0 to FL_NUM_GREEN - 1,
C<$b> must be in the range 0 to FL_NUM_BLUE - 1.

To get the closest color to a 8-bit set of R,G,B values use:

fl_color_cube(R * (FL_NUM_RED - 1) / 255,
   G * (FL_NUM_GREEN - 1) / 255,
   B * (FL_NUM_BLUE - 1) / 255);

=cut

Fl_Color
fl_color_cube(int r, int g, int b)

BOOT:
    export_function("fl_color_cube", "color");

=pod

=item fl_show_colormap(...)

    my $new_color = fl_show_colormap(FL_RED);

Pops up a window to let the user pick a colormap entry. The provided color is
highlighted when the grid is shown.

=for markdown [http://www.fltk.org/doc-1.3/fl_show_colormap.png]

=for html <center><img src="http://www.fltk.org/doc-1.3/fl_show_colormap.png" /></center>

=cut

#include <FL/fl_show_colormap.H>

Fl_Color
fl_show_colormap(Fl_Color oldcol)

BOOT:
    export_function("fl_show_colormap", "color");

=pod

=back

=head1 LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=cut
