=for comment based on iup-3.5 - http://www.tecgraf.puc-rio.br/iup/en/ctrl/iupcolorbar.html

=head1 NAME

IUP::ColorBar - [GUI element] color palette for color selection of 1 or 2 colors

=head1 DESCRIPTION

Creates a color palette to enable a color selection from several
samples. It can select one or two colors. The primary color is selected
with the left mouse button, and the secondary color is selected with
the right mouse button. You can double click a cell to change its color
and you can double click the preview area to switch between primary and
secondary colors.

=begin HTML

<p><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iupcolorbar.gif"></p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 $colorbar = IUP::Colorbar->new( SIZE=>"300x300" );

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.)
see L<IUP::Manual::03_Attributes|IUP::Manual::03_Attributes>. Attributes specific to this element:

=over

=item B<BUFFERIZE>

I<(non inheritable)>

Disables the automatic redrawing of
the control, so many attributes can be changed without many redraws.
Default: "NO". When set to "NO" the control is redrawn.

=item B<< CELL<n> >>

Contains the color of the "n" cell. "n" can be from 0
to NUM_CELLS-1.

=item B<NUM_CELLS>

I<(non inheritable)>

Contains the number of color cells.
Default: "16". The maximum number of colors is 256. The default colors
use the same set of L<IUP::Image|IUP::Image>.

=item B<COUNT>

I<(read-only) (non inheritable)>

Same as B<NUM_CELLS> but it is read-only. (since iup-3.3)

=item B<NUM_PARTS>

I<(non inheritable)>

Contains the number of lines or columns. Default: "1".

=item B<ORIENTATION>

Controls the orientation. It can be "VERTICAL" or "HORIZONTAL". Default "VERTICAL".

=item B<PREVIEW_SIZE>

I<(non inheritable)>

Fixes the size of the preview
area in pixels. The default size is dynamically calculated from the
size of the control. The size is reset to the default when
SHOW_PREVIEW=NO.

=item B<SHOW_PREVIEW>

Controls the display of the preview area. Default "YES".

=item B<SHOW_SECONDARY>

Controls the existence of a secondary color selection. Default "NO".

=item L<SIZE|IUP::Manual::03_Attributes/SIZE>

there is no initial size. You must define SIZE or RASTERSIZE.

=item B<PRIMARY_CELL>

I<(non inheritable)>

Contains the index of the primary color. Default "0" (black).

=item B<SECONDARY_CELL>

I<(non inheritable)>

Contains the index of the secondary color. Default "15" (white).

=item B<SQUARED>

Controls the aspect ratio of the color cells. Non square
cells expand equally to occupy all of the control area. Default: "YES".

=item B<SHADOWED>

Controls the 3D effect of the color cells. Default "YES".

=item B<TRANSPARENCY>

Contains a color that will be not rendered in the
color palette. The color cell will have a white and gray chess pattern.
It can be used to create a palette with less colors than the number of
cells.

=back

The following L<common attributes|IUP::Manual::03_Attributes/Common Attributes> are also accepted:

=over

=item * L<ACTIVE|IUP::Manual::03_Attributes/ACTIVE>,
L<BGCOLOR|IUP::Manual::03_Attributes/BGCOLOR>, L<FONT|IUP::Manual::03_Attributes/FONT>,
L<SCREENPOSITION|IUP::Manual::03_Attributes/SCREENPOSITION>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
L<MINSIZE|IUP::Manual::03_Attributes/MINSIZE>,
L<MAXSIZE|IUP::Manual::03_Attributes/MAXSIZE>, L<WID|IUP::Manual::03_Attributes/WID>,
L<TIP|IUP::Manual::03_Attributes/TIP>, L<EXPAND|IUP::Manual::03_Attributes/EXPAND>,
L<SIZE|IUP::Manual::03_Attributes/SIZE>,
L<RASTERSIZE|IUP::Manual::03_Attributes/RASTERSIZE>,
L<ZORDER|IUP::Manual::03_Attributes/ZORDER>,
L<VISIBLE|IUP::Manual::03_Attributes/VISIBLE>

=back

=head2 CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.)
see L<IUP::Manual::04_Callbacks|IUP::Manual::04_Callbacks>. Callbacks specific to this element:

=over

=item B<CELL_CB>

called when the user double clicks a color cell to
change its value.

B<Callback handler prototype:>

 sub cell_cb_handler {
   my ($self, $cell) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::ColorBar) that activated the event

B<$cell:> index of the selected cell. If the user double click a preview
cell, the respective index is returned.

B<Returns:> a new color or C<undef> to ignore the change. By
default nothing is changed.

=back

=item B<EXTENDED_CB>

called when the user right click a cell with the
Shift key pressed. It is independent of the SHOW_SECONDARY attribute.

B<Callback handler prototype:>

 sub extended_cb_handler {
   my ($self, $cell) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::ColorBar) that activated the event

B<$cell:> index of the selected cell.

B<Returns:> If IUP_IGNORE the cell is not redrawn. By default the cell is
always redrawn.

=back

=item B<SELECT_CB>

called when a color is selected. The primary color is
selected with the left mouse button, and if existent the secondary is
selected with the right mouse button.

B<Callback handler prototype:>

 sub extended_cb_handler {
   my ($self, $cell, $type) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::ColorBar) that activated the event

B<$cell:> index of the selected cell.

B<$type:> indicates if the user selected a primary or secondary color.
In can be: C<IUP_PRIMARY(-1)> or C<IUP_SECONDARY(-2)>.

B<Returns:> If IUP_IGNORE the selection is not accepted. By default the
selection is always accepted.

=back

=item B<SWITCH_CB>

called when the user double clicks the preview area
outside the preview cells to switch the primary and secondary
selections. It is only called if SHOW_SECONDARY=YESB<.>

B<Callback handler prototype:>

 sub extended_cb_handler {
   my ($self, $prim_cell, $sec_cell) = @_;
   #...
 }

=over

B<$self:> reference to the element (IUP::ColorBar) that activated the event

B<$prim_cell:> index of the actual primary cell.

B<$sec_cell:> index of the actual secondary cell.

B<Returns:> If IUP_IGNORE the switch is not accepted. By default the
switch is always accepted.

=back

=back

The following L<common callbacks|IUP::Manual::04_Callbacks/Common Callbacks> are also accepted:

=over

=item * L<MAP_CB|IUP::Manual::04_Callbacks/MAP_CB>,
L<UNMAP_CB|IUP::Manual::04_Callbacks/UNMAP_CB>,
L<GETFOCUS_CB|IUP::Manual::04_Callbacks/GETFOCUS_CB>,
L<KILLFOCUS_CB|IUP::Manual::04_Callbacks/KILLFOCUS_CB>,
L<ENTERWINDOW_CB|IUP::Manual::04_Callbacks/ENTERWINDOW_CB>,
L<LEAVEWINDOW_CB|IUP::Manual::04_Callbacks/LEAVEWINDOW_CB>,
L<K_ANY|IUP::Manual::04_Callbacks/K_ANY>, L<HELP_CB|IUP::Manual::04_Callbacks/HELP_CB>

=back

=head1 NOTES

When the control has the focus the keyboard can be used to change the
colors and activate the callbacks. Use the arrow keys to move from cell
to cell, B<Home> goes to the first cell, B<End> goes to the last cell.
B<Space> will activate the B<SELECT_CB> callback for the primary color,
B<Ctrl>+B<Space> will activate the B<SELECT_CB> callback for the
secondary color. B<Shift>+B<Space> will activate the B<EXTENTED_CB>
callback. B<Shift>+B<Enter> will activate the B<CELL_CB> callback.

=head1 EXAMPLES


The element B<IUP::ColorBar> is used in the following sample scripts:

=over

=item * L<0-basic/colorbar.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/colorbar.pl> - IUP::ColorBar example

=back 



=head1 SEE ALSO

L<IUP::Canvas|IUP::Canvas>, L<IUP::Image|IUP::Image>

The original doc: L<iupcolorbar.html|http://www.tecgraf.puc-rio.br/iup/en/ctrl/iupcolorbar.html>
 

=cut