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

=head1 NAME

IUP::Val - [GUI element] selects a value in a limited interval (aka scale, trackbar)

=head1 DESCRIPTION 

Creates a Valuator control. Selects a value in a limited interval. Also
known as Scale or Trackbar in native systems.

=begin HTML

<p>
  <table border="1">
    <col style="background-color: rgb(173, 177, 194);">
    <col style="background-color: rgb(212, 208, 200);">
    <col style="background-color: rgb(236, 233, 216);">
    <col style="background-color: rgb(240, 240, 240);">
    <col style="background-color: rgb(239, 235, 231);">
    <tbody align="center">
      <tr>
        <th>Motif</th>
        <th>Windows<br>Classic</th>
        <th>Windows<br>w/ Styles</th>
	<th>Windows<br>Vista</th>
        <th>GTK</th>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_mot_horiz.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_win2k_horiz.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_winxp_horiz.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_vista_horiz.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_gtk_horiz.png"></td>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_mot_vert.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_win2k_vert.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_winxp_vert.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_vista_vert.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupval_gtk_vert.png"></td>
      </tr>
      <tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 $val = IUP::Val->new( ORIENTATION=>"VERTICAL" );

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 L<BGCOLOR|IUP::Manual::03_Attributes/BGCOLOR>

Transparent in all systems
except in Motif. It will use the background color of the native parent.

=item B<CANFOCUS>

I<(creation only) (non inheritable)>

Enables the focus
traversal of the control. In Windows the control will still get the
focus when clicked. Default: YES. 

=item B<INVERTED>

Invert the minimum and maximum positions on screen. When
INVERTED=YES maximum is at top and left (minimum is bottom and right),
when INVERTED=NO maximum is at bottom and right (minimum is top and
left). The initial value depends on ORIENTATION passed as parameter on
creation, if ORIENTATION=VERTICAL default is YES, if
ORIENTATION=HORIZONTAL default is NO. 

=item B<MAX>

Contains the maximum valuator value. Default is "1". When
changed the display will not be updated until VALUE is set.

=item B<MIN>

Contains the minimum valuator value. Default is "0". When
changed the display will not be updated until VALUE is set.

=item B<PAGESTEP>

Controls the increment for pagedown and pageup keys. It is
not the size of the increment. The increment size is
"pagestep*(max-min)", so it must be 0E<lt>pagestepE<lt>1. Default is
"0.1".

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

I<(non inheritable)>

The initial size is 100 pixels along the major axis, and the handler normal
size on the minor axis. If there are ticks then they are added to the
natural size on the minor axis. The handler can be smaller than the
normal size. Set to C<undef> to allow the automatic layout use smaller
values.

=item B<SHOWTICKS>

I<[Windows and Motif Only]>

The number of tick marks along
the valuator trail. Minimum value is "2". Default is "0", in this case
the ticks are not shown. It can not be changed to 0 from a non zero
value, or vice-versa, after the control is mapped. GTK does not support
ticks.

=item B<STEP>

Controls the increment for keyboard control and the mouse
wheel. It is not the size of the increment. The increment size is
"step*(max-min)", so it must be 0E<lt>stepE<lt>1. Default is "0.01".

=item B<TICKSPOS>

I<[Windows Only] (creation only)>

Allows to position the
ticks in both sides (BOTH) or in the reverse side (REVERSE). Default:
NORMAL. The normal position for horizontal orientation is at the top of
the control, and for vertical orientation is at the left of the
control. In Motif, the ticks position is always normal. 

=item B<ORIENTATION>

I<(non inheritable)>

Informs whether the valuator is
"VERTICAL" or "HORIZONTAL". Vertical valuators are bottom to up, and
horizontal valuators are left to right variations of min to max (but
can be inverted using INVERTED). Default: "HORIZONTAL".

=item B<VALUE>

I<(non inheritable)>

Contains a number between MIN and MAX,
indicating the valuator position. Default: "0.0".

=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<EXPAND|IUP::Manual::03_Attributes/EXPAND>, 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<SIZE|IUP::Manual::03_Attributes/SIZE>,
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<VALUECHANGED_CB>

Called after the value was interactively changed by the user.

B<Callback handler prototype:>

 sub valuechanged_cb_handler {
   my ($self) = @_;
   #...
 }

=over

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

=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

This control replaces the old L<IUP::Val|IUP::Val> implemented
in the additional controls. The old callbacks are still supported but
called only if the VALUECHANGED_CB callback is not defined. The
MOUSEMOVE_CB callback is only called when the user moves the handler
using the mouse. The BUTTON_PRESS_CB callback is called only when the
user press a key that changes the position of the handler. The
BUTTON_RELEASE_CB callback is called only when the user release the
mouse button after moving the handler.

In Motif, after the user clicks the handler a KILLFOCUS will be ignored
when the control loses its focus.

=head2 Keyboard Mapping

This is the default mapping when INVERTED has the default value, or
ORIENTATION=HORIZONTAL+INVERTED=NO.

 Keys                       Action for HORIZONTAL
 ------------------------------------------------------------
 Right Arrow                move right, increment by one step
 Left Arrow                 move left, decrement by one step
 Ctrl+Right Arrow or PgDn   move right, increment by one page step
 Ctrl+Left Arrow or PgUp    move left, decrement by one page step
 Home                       move all left, set to minimum
 End                        move all right, set to maximum

This is the default mapping when INVERTED has the default value, or
ORIENTATION=VERTICAL+INVERTED=YES.

 Keys                       Action for VERTICAL
 ------------------------------------------------------------
 Up Arrow                   move up, increment by one step
 Down Arrow                 move down, decrement by one step
 Ctrl+Up Arrow or PgUp      move up, increment by one page step
 Ctrl+Down Arrow or PgDn    move down, decrement by one page step
 Home                       move all up, set to maximum
 End                        move all down, set to minimum

Visually all the keys move to the same direction independent from the
INVERTED attribute.

Semantically all the keys change the value depending on the INVERTED
attribute.

This behavior is slightly different from the defined by the native
systems (Home and End keys are different). But it is the same in all
systems.

=head1 EXAMPLES


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

=over

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

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

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

=item * L<1-apps/app-sample1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-sample1.pl> - example used for screenshot - IUP.pod

=item * L<1-apps/app-sample2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-sample2.pl> - example based on the original sample.c

=item * L<1-apps/app-simple-demo.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-simple-demo.pl> - example used for screenshot - IUP.pod

=back 



=head1 SEE ALSO

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

=cut