@node Part III Valuator Objects
@chapter Valuator Objects

@ifnottex

@menu
* Slider Object:      Slider Object
* Scrollbar Object:   Scrollbar Object
* Dial Object:        Dial Object
* Positioner Object:  Positioner Object
* Counter Object:     Counter Object
* Spinner Object:     Spinner Object
* Thumbwheel Object:  Thumbwheel Object
@end menu

@end ifnottex


@node Slider Object
@section Slider Object

Sliders are useful for letting the user indicate a value between some
fixed bounds. Both horizontal and vertical sliders exist. They have a
minimum, a maximum and a current value (all floating point values).
The user can change the current value by shifting the slider with the
mouse. Whenever the value changes, this is reported to the application
program.

@ifnottex

@menu
* Adding Slider Objects:   Adding Slider Objects
* Slider Types:            Slider Types
* Slider Interaction:      Slider Interaction
* Other Slider Routines:   Other Slider Routines
* Slider Attributes:       Slider Attributes
* Remarks:                 Slider Remarks
@end menu

@end ifnottex


@node Adding Slider Objects
@subsection Adding Slider Objects

Adding an object To add a slider to a form use
@findex fl_add_slider()
@anchor{fl_add_slider()}
@example
FL_OBJECT *fl_add_slider(int type, FL_Coord x, FL_Coord y,
                         FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
or
@findex fl_add_valslider()
@anchor{fl_add_valslider()}
@example
FL_OBJECT *fl_add_valslider(int type, FL_Coord x, FL_Coord y,
                            FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed below the slider. The difference between a normal slider and a
valslider is that for the second type its value is displayed above or
to the left of the slider.


@node Slider Types
@subsection Slider Types

The following types of sliders are available:
@table @code
@tindex FL_VERT_SLIDER
@anchor{FL_VERT_SLIDER}
@item FL_VERT_SLIDER
A vertical slider.

@tindex FL_HOR_SLIDER
@anchor{FL_HOR_SLIDER}
@item FL_HOR_SLIDER
A horizontal slider.

@tindex FL_VERT_FILL_SLIDER
@anchor{FL_VERT_FILL_SLIDER}
@item FL_VERT_FILL_SLIDER
A vertical slider, filled from the bottom.

@tindex FL_HOR_FILL_SLIDER
@anchor{FL_HOR_FILL_SLIDER}
@item FL_HOR_FILL_SLIDER
A horizontal slider, filled from the left.

@tindex FL_VERT_NICE_SLIDER
@anchor{FL_VERT_NICE_SLIDER}
@item FL_VERT_NICE_SLIDER
A nice looking vertical slider.

@tindex FL_HOR_NICE_SLIDER
@anchor{FL_HOR_NICE_SLIDER}
@item FL_HOR_NICE_SLIDER
A nice looking horizontal slider.

@tindex FL_VERT_BROWSER_SLIDER
@anchor{FL_VERT_BROWSER_SLIDER}
@item FL_VERT_BROWSER_SLIDER
A different looking vertical slider.

@tindex FL_HOR_BROWSER_SLIDER
@anchor{FL_HOR_BROWSER_SLIDER}
@item FL_HOR_BROWSER_SLIDER
A different looking horizontal slider.
@end table

@ifhtml
@center @image{images/slidertypes}
@end ifhtml
@ifnothtml
@center @image{images/slidertypes,12cm}
@end ifnothtml


@node Slider Interaction
@subsection Slider Interaction

Whenever the user changes the value of the slider using the mouse, the
slider is returned (unless there's callback function associated with
the object) by the interaction routines. The slider position is
changed by moving the mouse inside the slider area. For fine control,
hold down the @code{<Shift>} key while moving the slider.

In some cases you might not want the slider to be returned or its
callback called each time its value changes. To change the default,
call the following routine:
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when)
@end example
@noindent
where the parameter @code{when} can be one of the four values:
@table @code
@item @ref{FL_RETURN_NONE}
Never return or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end (mouse release) if value is changed
since last return.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the slider value is changed. This
is the default.

@item @ref{FL_RETURN_END}
Return or invoke callback at end (mouse release) regardless if the
value is changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback when the value changed or at end (mouse
release).
@end table

See the demo program @file{objreturn.c} for an example use of this.


@node Other Slider Routines
@subsection Other Slider Routines

To change the value and bounds of a slider use the following routines
@findex fl_set_slider_value()
@anchor{fl_set_slider_value()}
@findex fl_set_slider_bounds()
@anchor{fl_set_slider_bounds()}
@example
void fl_set_slider_value(FL_OBJECT *obj, double val);
void fl_set_slider_bounds(FL_OBJECT *obj, double min, double max);
@end example
@noindent
By default, the minimum value for a slider is 0.0, the maximum is 1.0
and the value is 0.5. For vertical sliders the slider position for the
minimum value is at the left, for horizontal sliders at the top of the
slider. By setting @code{nin} to a larger value than @code{max} in a
call of @code{@ref{fl_set_slider_bounds()}} this can be reversed.

If in a call of @code{@ref{fl_set_slider_bounds()}} the actual value
of a slider isn't within the range of the new bounds, its value gets
adjusted to the nearest limit. When the requested new slider value in
a call of @code{@ref{fl_set_slider_value()}} is outside the range of
bounds it gets adjusted to the nearest boundary value.

To obtain the current value or bounds of a slider use
@findex fl_get_slider_value()
@anchor{fl_get_slider_value()}
@example
double fl_get_slider_value(FL_OBJECT *obj);
void fl_get_slider_bounds(FL_OBJECT *obj, double *min, double *max);
@end example

@c -----------------------------------------------------------------
@c The following function still exist but the description is wrong.
@c fl_set_slider_step() doesn't do anything and
@c fl_set_slider_increment() is only used internallyy for sliders
@c used in scrollbars (and doesn't do anything for normal sliders)

@c In a number of situations you may like slider values to be rounded to
@c some values, e.g. to integer values. To this end use the routine
@c @findex fl_set_slider_step()
@c @anchor{fl_set_slider_step()}
@c @example
@c void fl_set_slider_step(FL_OBJECT *obj, double step);
@c @end example
@c @noindent
@c After this call slider values will be rounded to multiples of @code{step}.
@c Use the value 0.0 for @code{step} to switch off rounding.


@c By default, if the mouse is pressed below or above the the sliding
@c bar, the sliding bar jumps to the location where the mouse got pressed.
@c You can, however, use the following routine to change this default so
@c the jumps are made is discrete increments:
@c @findex fl_set_slider_increment()
@c @anchor{fl_set_slider_increment()}
@c @example
@c void fl_set_slider_increment(FL_OBJECT *obj, double lj, double rj);
@c @end example
@c @noindent
@c where @code{lj} indicates how much to jump if the left mouse button is
@c pressed and @code{rj} indicates how much to increment if right/middle
@c mouse buttons pressed. This routine can be used if finer control of
@c the slider value is needed or to assign different meanings to different
@c mouse buttons. For example, for the slider in the browser class, the
@c left mouse jump is made to be one page and right jump is made to be
@c one line.
@c 
@c To obtain the current increment, use the following routine
@c @findex fl_get_slider_increment()
@c @anchor{fl_get_slider_increment()}
@c @example
@c void fl_get_slider_increment(FL_OBJECT *obj, double *lj, double *rj);
@c @end example
@c -----------------------------------------------------------------


@node Slider Attributes
@subsection Slider Attributes

Never use @code{FL_NO_BOX} as the boxtype for a slider. For
@code{FL_VERT_NICE_SLIDER}s and @code{FL_HOR_NICE_SLIDER}s it's best
to use a @code{FL_FLAT_BOX} in the color of the background to get the
nicest effect.

The first color argument (@code{col1}) to
@code{@ref{fl_set_object_color()}} controls the color of the
background of the slider, the second (@code{col2}) the color of the
slider itself.

You can control the size of the slider inside the box using the routine
@findex fl_set_slider_size()
@anchor{fl_set_slider_size()}
@example
void fl_set_slider_size(FL_OBJECT *obj, double size);
@end example
@noindent
@code{size} should be a floating point value between 0.0 and 1.0. The
default is
@tindex FL_SLIDER_WIDTH
@code{FL_SLIDER_WIDTH}, which is 0.1 for regular sliders and 0.15 for
browser sliders. With a value for @code{size} of 1.0, the slider
covers the box completely and can no longer be moved. This function
does nothing if applied to sliders of type @code{NICE_SLIDER} and
@code{FILL_SLIDER}.

The routine
@findex fl_set_slider_precision()
@anchor{fl_set_slider_precision()}
@example
void fl_set_slider_precision(FL_OBJECT *obj, int prec);
@end example
@noindent
sets the precision with which the value of the slider is shown. This
only applies to sliders showing their value, i.e.@: valsliders.

By default, the value shown by a valslider is the slider value in
floating point format. You can override the default by registering a
filter function using the following routine
@findex fl_set_slider_filter()
@anchor{fl_set_slider_filter()}
@example
void fl_set_slider_filter(FL_OBJECT *obj,
                          const char *(*filter)(FL_OBJECT *,
                                                double value,
                                                int prec));
@end example
@noindent
where @code{value} and @code{prec} are the slider value and precision
respectively. The filter function @code{filter} should return a string
that is to be shown. The default filter is equivalent to the following
@example
const char *filter(FL_OBJECT *obj, double value, int prec) @{
    static char buf[32];

     sprintf(buf, "%.*f", prec, value);
     return buf;
@}
@end example

@node Slider Remarks
@subsection Remarks

See the demo program @file{demo05.c} for an example of the use of
sliders. See demo programs @file{sldsize.c} and @file{sliderall.c}
for the effect of setting slider sizes and the different types of
sliders.


@node Scrollbar Object
@section Scrollbar Object

Scrollbars are similar to sliders (as a matter of fact, scrollbars are
made with sliders and scrollbuttons), and useful in letting the user
indicate a value between some fixed bounds. Both horizontal and
vertical scrollbars exist. They have a minimum, maximum and current
value (all floating point values). The user can change this value by
dragging the sliding bar with the mouse or press the scroll buttons.
Whenever the value changes, it is reported to the application program
via the callback function.

@ifnottex

@menu
* Adding Scrollbar Objects:   Adding Scrollbar Objects
* Scrollbar Types:            Scrollbar Types
* Scrollbar Interaction:      Scrollbar Interaction
* Other Scrollbar Routines:   Other Scrollbar Routines
* Scrollbar Attributes:       Scrollbar Attributes
* Remarks:                    Scrollbar Remarks
@end menu

@end ifnottex


@node Adding Scrollbar Objects
@subsection Adding Scrollbar Objects

To add a scrollbar to a form use
@findex fl_add_scrollbar()
@anchor{fl_add_scrollbar()}
@example
FL_OBJECT *fl_add_scrollbar(int type, FL_Coord x, FL_Coord y,
                            FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed below the scrollbar.


@ifhtml
@center @image{images/scrollbars}
@end ifhtml
@ifnothtml
@center @image{images/scrollbars,14cm}
@end ifnothtml


@node Scrollbar Types
@subsection Scrollbar Types

The following types of scrollbar are available:
@table @code
@tindex FL_VERT_SCROLLBAR
@anchor{FL_VERT_SCROLLBAR}
@item FL_VERT_SCROLLBAR
A vertical scrollbar.

@tindex FL_HOR_SCROLLBAR
@anchor{FL_HOR_SCROLLBAR}
@item FL_HOR_SCROLLBAR
A horizontal scrollbar.

@tindex FL_VERT_THIN_SCROLLBAR
@anchor{FL_VERT_THIN_SCROLLBAR}
@item FL_VERT_THIN_SCROLLBAR
A different looking vertical scrollbar.

@tindex FL_HOR_THIN_SCROLLBAR
@anchor{FL_HOR_THIN_SCROLLBAR}
@item FL_HOR_THIN_SCROLLBAR
A different looking horizontal scrollbar.

@tindex FL_VERT_NICE_SCROLLBAR
@anchor{FL_VERT_NICE_SCROLLBAR}
@item FL_VERT_NICE_SCROLLBAR
A vertical scrollbar using @code{FL_NICE_SLIDER}.

@tindex FL_HOR_NICE_SCROLLBAR
@anchor{FL_HOR_NICE_SCROLLBAR}
@item FL_HOR_NICE_SCROLLBAR
A horizontal scrollbar using @code{FL_NICE_SLIDER}.

@tindex FL_VERT_PLAIN_SCROLLBAR
@anchor{FL_VERT_PLAIN_SCROLLBAR}
@item FL_VERT_PLAIN_SCROLLBAR
Similar to @code{FL_THIN_SCROLLBAR}.

@tindex FL_HOR_PLAIN_SCROLLBAR
@anchor{FL_HOR_PLAIN_SCROLLBAR}
@item FL_HOR_PLAIN_SCROLLBAR
Similar to @code{FL_HOR_THIN_SCROLLBAR}.
@end table


@node Scrollbar Interaction
@subsection Scrollbar Interaction

Whenever the user changes the value of the scrollbar, the scrollbar's
callback is called (if one is associated with the scrollbar). The
scrollbar position is changed by moving the mouse inside the scrollbar
area or. For fine control hold down the left or right @code{<Shift>}
key while moving the slider.

You can control under which conditions the scrollbar gets returned to
your application or its callback invoked. To change the default, call
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
@noindent
where the parameter @code{when} can be one of the following four
values:
@table @code
@item @ref{FL_RETURN_NONE}
Never return or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end (mouse release) if value is changed
(since last return).

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the scrollbar value is changed.
This is the default.

@item @ref{FL_RETURN_END}
Return or invoke callback at end (mouse release) regardless if the
value is changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback whenever value changed or mouse button was
released.
@end table

The default setting for @code{when} for a scrollbar object is
@code{@ref{FL_RETURN_CHANGED}} (unless during the build of XForms you
set the configuration flag @code{--enable-bwc-bs-hack} in which case
the default is @code{@ref{FL_RETURN_NONE}} to keep backward
compatibility with earlier releases of the library).

See demo program @file{objreturn.c} for an example use of this.


@node Other Scrollbar Routines
@subsection Other Scrollbar Routines

To change the value and bounds of a scrollbar use the following
routines:
@findex fl_set_scrollbar_value()
@anchor{fl_set_scrollbar_value()}
@findex fl_set_scrollbar_bounds()
@anchor{fl_set_scrollbar_bounds()}
@example
void fl_set_scrollbar_value(FL_OBJECT *obj, double val);
void fl_set_scrollbar_bounds(FL_OBJECT *obj, double min, double max);
@end example
By default, the minimum value for a slider is 0.0, the maximum is 1.0
and the value is 0.5. For vertical sliders the slider position for the
minimum value is at the left, for horizontal sliders at the top of the
slider. By setting @code{min} to a larger value than @code{max} in a
call of @code{@ref{fl_set_scrollbar_bounds()}} this can be reversed.

If in a call of @code{@ref{fl_set_scrollbar_bounds()}} the actual
value of a scrollbar isn't within the range of the new bounds, its
value gets adjusted to the nearest limit. When the requested new
scrollbar value in a call of @code{@ref{fl_set_scrollbar_value()}} is
outside the range of bounds it gets adjusted to the nearest boundary
value.


To obtain the current value and bounds of a scrollbar use
@findex fl_get_scrollbar_value()
@anchor{fl_get_scrollbar_value()}
@findex fl_get_scrollbar_bounds()
@anchor{fl_get_scrollbar_bounds()}
@example
double fl_get_scrollbar_value(FL_OBJECT *obj);
void fl_get_scrollbar_bounds(FL_OBJECT *obj, double *min, double *max);
@end example

@c ---------------------------------------------------------------
@c The function fl_set_scrollbar_step() still exists but doesn't
@c has any effect!

@c In a number of situations you would like scrollbar values to be
@c rounded to some values, e.g. to integer values. To this end use the
@c routine
@c @findex fl_set_scrollbar_step()
@c @anchor{fl_set_scrollbar_step()}
@c @example
@c void fl_set_scrollbar_step(FL_OBJECT *obj, double step);
@c @end example
@c @noindent
@c After this call the scrollbar values will be rounded to multiples of
@c @code{step}. Use the value 0.0 for @code{step} to switch off rounding.
@c This should not be confused with the increment/decrement value when
@c the scroll buttons are pressed. Use
@c @code{@ref{fl_set_scrollbar_increment()}} to change the increment
@c value.
@c ---------------------------------------------------------------

By default, if the mouse is pressed beside the the sliding bar, the
bar starts to jumps in the direction of the mouse position. You can
use the following routine to change this size of the steps being
made :
@findex fl_set_scrollbar_increment()
@anchor{fl_set_scrollbar_increment()}
@example
void fl_set_scrollbar_increment(FL_OBJECT *obj, double lj, double rj);
@end example
@noindent
where @code{lj} indicates how much to increment if the left mouse
button is pressed and @code{rj} indicates how much to jump if the
middle mouse button pressed. For example, for the scrollbar in the
browser class, the left mouse jump is made to be one page and middle
mouse jump is made to be one line. The increment (decrement) value
when the scrollbuttons are pressed is set to the value of the right
jump. The default values for @code{lj} and @code{rj} are @code{0.1}
and @code{0.02}.

To obtain the current increment settings, use the following routine
@findex fl_get_scrollbar_increment()
@anchor{fl_get_scrollbar_increment()}
@example
void fl_get_scrollbar_increment(FL_OBJECT *obj, double *lj, double *sj);
@end example


@node Scrollbar Attributes
@subsection Scrollbar Attributes

Never use @code{FL_NO_BOX} as the boxtype for a scrollbar. For
@code{FL_VERT_NICE_SCROLLBAR}s and @code{FL_HOR_NICE_SCROLLBAR}s it's
best to use a @code{FL_FLAT_BOX} boxtype in the color of the
background to get the nicest effect.

The first color argument (@code{col1} to
@code{@ref{fl_set_object_color()}} controls the color of the
background of the scrollbar, the second (@code{col2}) the color of the
sliding bar itself.

You can control the size of the sliding bar inside the box using the
routine
@findex fl_set_scrollbar_size()
@anchor{fl_set_scrollbar_size()}
@example
void fl_set_scrollbar_size(FL_OBJECT *obj, double size);
@end example
@noindent
@code{size} should be a value between 0.0 and 1.0. The default is
@tindex FL_SLIDER_WIDTH
@code{FL_SLIDER_WIDTH}, which is 0.15 for all scrollbars With
@code{size} set to 1.0, the scrollbar covers the box completely and
can no longer be moved. This function does nothing if applied to
scrollbars of type @code{FL_NICE_SCROLLBAR}.


@node Scrollbar Remarks
@subsection Remarks

See the demo program @file{scrollbar.c} for an example of the use of
scrollbars.


@node Dial Object
@section Dial Object

Dial objects are dials that the user can put in a particular position
using the mouse. They have a minimum, maximum and current value (all
floating point values). The user can change this value by turning the
dial with the mouse. Whenever the value changes, this is reported to
the application program.

@ifnottex

@menu
* Adding Dial Objects:    Adding Dial Objects
* Dial Types:             Dial Types
* Dial Interaction:       Dial Interaction
* Other Dial Routines:    Other Dial Routines
* Dial Attributes:        Dial Attributes
* Remarks:                Dial Remarks
@end menu

@end ifnottex


@node Adding Dial Objects
@subsection Adding Dial Objects

To add a dial to a form use
@findex fl_add_dial()
@anchor{fl_add_dial()}
@example
FL_OBJECT *fl_add_dial(int type, FL_Coord x, FL_Coord y,
                       FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed below the dial.

@node Dial Types
@subsection Dial Types

@ifhtml
@center @image{images/dials}
@end ifhtml
@ifnothtml
@center @image{images/dials,10cm}
@end ifnothtml


The following types of dials are available:
@table @code
@tindex FL_NORMAL_DIAL
@anchor{FL_NORMAL_DIAL}
@item FL_NORMAL_DIAL
A dial with a knob indicating the position.

@tindex FL_LINE_DIAL
@anchor{FL_LINE_DIAL}
@item FL_LINE_DIAL
A dial with a line indicating the position.

@tindex FL_FILL_DIAL
@anchor{FL_FILL_DIAL}
@item FL_FILL_DIAL
The area between initial and current is filled.
@end table


@node Dial Interaction
@subsection Dial Interaction

By default, the dial value is returned to the application when the
user releases the mouse. It is possible to change this behavior using
the following routine
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
@noindent
where @code{when} can be one of the following
@table @code
@item @ref{FL_RETURN_NONE}
Never report or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end (mouse release) and only if the dial
value is changed. This is the default setting.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the dial value is changed.

@item @ref{FL_RETURN_END}
Return or invoke callback at the end regardless if the dial value is
changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback when value has changed or mouse button has
been released.
@end table

@node Other Dial Routines
@subsection Other Dial Routines

To change the value of the dial and its bounds use
@findex fl_set_dial_value()
@anchor{fl_set_dial_value()}
@findex fl_set_dial_bounds()
@anchor{fl_set_dial_bounds()}
@example
void fl_set_dial_value(FL_OBJECT *obj, double val);
void fl_set_dial_bounds(FL_OBJECT *obj, double min, double max);
@end example
@noindent
By default, the minimum value is 0.0, the maximum is 1.0 and the value
is 0.5.

To obtain the current values of the dial and its bounds use
@findex fl_get_dial_value()
@anchor{fl_get_dial_value()}
@findex fl_get_dial_bounds()
@anchor{fl_get_dial_bounds()}
@example
double fl_get_dial_value(FL_OBJECT *obj);
void fl_get_dial_bounds(FL_OBJECT *obj, double *min, double *max);
@end example

Sometimes, it might be desirable to limit the angular range a dial can
take or choose an angle other than 0 to represent the minimum value.
For this purpose, use the following routine
@findex fl_set_dial_angles()
@anchor{fl_set_dial_angles()}
@example
void fl_set_dial_angles(FL_OBJECT *obj, double thetai, double thetaf)
@end example
@noindent
where @code{thetai} maps to the minimum value of the dial and
@code{thetaf} to its maximum value. The angles are relative to the
origin of the dial, which is by default at 6 o'clock and rotates
clock-wise. By default, the minimum angle is 0 and the maximum angle
is 360.

By default, crossing from 359.9 to 0 or from 0 to 359.9 is not
allowed. To allowing crossing over, use the following routine
@findex fl_set_dial_crossover()
@anchor{fl_set_dial_crossover()}
@example
void fl_set_dial_crossover(FL_OBJECT *obj, int yes_no);
@end example
@noindent
where a true value for @code{yes_no} indicates that cross-over is
allowed.

In a number of situations you might want dial values to be rounded to
some values, e.g. to integer values. To this end use the routine
@findex fl_set_dial_step()
@anchor{fl_set_dial_step()}
@example
void fl_set_dial_step(FL_OBJECT *obj, double step);
@end example
@noindent
After this call dial values will be rounded to multiples of
@code{step}. Use a value of 0.0 for @code{step} to switch off
rounding.

By default, clock-wise rotation increases the dial value. To change,
use the following routine
@findex fl_set_dial_direction()
@anchor{fl_set_dial_direction()}
@example
void fl_set_dial_direction(FL_OBJECT *obj, int dir);
@end example
@noindent
where @code{dir} can be either
@tindex FL_DIAL_CCW
@code{FL_DIAL_CCW} or
@tindex FL_DIAL_CW
@code{FL_DIAL_CW}.


@node Dial Attributes
@subsection Dial Attributes

You can use any boxtype you like, but the final dial face always
appears to be circular although certain correlation between the
requested boxtype and actual boxtype exists (for example,
@code{FL_FRAME_BOX} is translated into a circular frame box.)

The first color argument (@code{col1} to
@code{@ref{fl_set_object_color()}} controls the color of the
background of the dial, the second @code{col2}) the color of the knob
or the line or the fill color.


@node Dial Remarks
@subsection Remarks

The resolution of a dial is about 0.2 degrees, i.e., there are only
about 2000 steps per 360 degrees and, depending on the size of the
dial, it is typically less.

The dial is always drawn with a circular box. If you specify a
@code{FL_UP_BOX}, a @code{FL_OVAL3D_UPBOX} will be used.

See the demo programs @file{ldial.c}, @file{ndial.c} and
@file{fdial.c} for examples of the use of dials.


@node Positioner Object
@section Positioner Object

A positioner is an object in which the user can indicate a position
with an x- and a y-coordinate. It displays a box with a cross-hair
cursor in it (except an invisble positioner, of course). Clicking the
mouse inside the box changes the position of the cross-hair cursor
and, hence, the x- and y-values.

@ifnottex

@menu
* Adding Positioner Objects:   Adding Positioner Objects
* Positioner Types:            Positioner Types
* Positioner Interaction:      Positioner Interaction
* Other Positioner Routines:   Other Positioner Routines
* Positioner Attributes:       Positioner Attributes
* Remarks:                     Positioners Remarks
@end menu

@end ifnottex


@node Adding Positioner Objects
@subsection Adding Positioner Objects

A positioner can be added to a form using the call
@findex fl_add_positioner()
@anchor{fl_add_positioner()}
@example
FL_OBJECT *fl_add_positioner(int type, FL_Coord x, FL_Coord y,
                             FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is placed below
the box by default.


@node Positioner Types
@subsection Positioner Types

The following types of positioner exist:
@table @code
@tindex FL_NORMAL_POSITIONER
@anchor{FL_NORMAL_POSITIONER}
@item FL_NORMAL_POSITIONER
Cross-hair inside a box.

@tindex FL_OVERLAY_POSITIONER
@anchor{FL_OVERLAY_POSITIONER}
@item FL_OVERLAY_POSITIONER
Cross-hair inside a transparent box (i.e.@{ drawn in in XOR mode).

@tindex FL_INVISIBLE_POSITIONER
@anchor{FL_INVISIBLE_POSITIONER}
@item FL_INVISIBLE_POSITIONER
Completely invisible positioner to be used just for the side effect
of obtaining a position (typically an object is below below it that
otherwise would receive user events).
@end table


@node Positioner Interaction
@subsection Positioner Interaction

The user changes the setting of the positioner using the mouse inside
the box. Per default whenever the values changes, the object is
returned by the interaction routines or its callback invoked (if
one exists.

To change the default use the function
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
@noindent
where @code{when} can be one of the following
@table @code
@item @ref{FL_RETURN_NONE}
Never report or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end (mouse release) and only when
the positioner ended in a different position than the one it
started from.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the positioners value is changed,
default setting.

@item @ref{FL_RETURN_END}
Return or invoke callback at the end only but regardless if the
positioners value changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback when value has changed or mouse button has
been released.
@end table


@node Other Positioner Routines
@subsection Other Positioner Routines

To set the value of the positioner and the boundary values use the
routines:
@findex fl_set_positioner_xvalue()
@anchor{fl_set_positioner_xvalue()}
@findex fl_set_positioner_xbounds()
@anchor{fl_set_positioner_xbounds()}
@findex fl_set_positioner_yvalue()
@anchor{fl_set_positioner_yvalue()}
@findex fl_set_positioner_ybounds()
@anchor{fl_set_positioner_ybounds()}
@example
void fl_set_positioner_xvalue(FL_OBJECT *obj, double val);
void fl_set_positioner_xbounds(FL_OBJECT *obj, double min, double max);
void fl_set_positioner_yvalue(FL_OBJECT *obj, double val);
void fl_set_positioner_ybounds(FL_OBJECT *obj, double min, double max);
@end example
@noindent
By default the minimum values are 0.0, the maximum values are 1.0 and
the actual values are 0.5. For boundaries in x-direction @code{min}
and @code{max} should be taken to mean the left- and right-most
position, respectively, and for the y-boundaries @code{min} and @code{max}
should be taken to mean the value at the bottom and value at the top
of the positioner.

To obtain the current values of the positioner and the bounds use
@findex fl_get_positioner_xvalue()
@anchor{fl_get_positioner_xvalue()}
@findex fl_get_positioner_xbounds()
@anchor{fl_get_positioner_xbounds()}
@findex fl_get_positioner_yvalue()
@anchor{fl_get_positioner_yvalue()}
@findex fl_get_positioner_ybounds()
@anchor{fl_get_positioner_ybounds()}
@example
double fl_get_positioner_xvalue(FL_OBJECT *obj);
void fl_get_positioner_xbounds(FL_OBJECT *obj,
                               double *min, double *max);
double fl_get_positioner_yvalue(FL_OBJECT *obj);
void fl_get_positioner_ybounds(FL_OBJECT *obj,
                               double *min, double *max);
@end example
@noindent

In a number of situations you might like positioner values to be
rounded to some values, e.g. to integer values. To this end use the
routines
@findex fl_set_positioner_xstep()
@anchor{fl_set_positioner_xstep()}
@findex fl_set_positioner_ystep()
@anchor{fl_set_positioner_ystep()}
@example
void fl_set_positioner_xstep(FL_OBJECT *obj, double step);
void fl_set_positioner_ystep(FL_OBJECT *obj, double step);
@end example
@noindent
After these calls positioner values will be rounded to multiples of
@code{step}. Use a value of 0.0 for @code{step} to switch off rounding.

Sometimes, it makes more sense for a positioner to have an icon/pixmap
as the background that represents a minified version of the area where
the positioner's values apply. Type @code{FL_OVERLAY_POSITIONER} is
specifically designed for this by drawing the moving cross-hair in XOR
mode as not to erase the background. A typical creation procedure
might look something like the following
@example
obj = fl_add_pixmap(FL_NORMAL_PIXMAP, x, y, w, h, label);
fl_set_pixmap_file(obj, iconfile);
pos = fl_add_positioner(FL_OVERLAY_POSITIONER, x, y, w, h, label);
@end example
@noindent
Of course, you can overlay this type of positioner on objects other
than a pixmap. See the demo program @file{positionerXOR.c} for an
example.


@node Positioner Attributes
@subsection Positioner Attributes

Never use @code{FL_NO_BOX} as the boxtype for a positioner of type.
@code{FL_NORMAL_POSITIONER} (but the other two types will have a box
type of @code{FL_NO_BOX} per default).

The first color argument (@code{col1}) to
@code{@ref{fl_set_object_color()}} controls the color of the box, the
second (@code{col2}) the color of the cross-hair.


@node Positioners Remarks
@subsection Remarks

A demo can be found in @file{positioner.c}.


@node Counter Object
@section Counter Object

A counter provides a different mechanism for the user to indicate a
value. In consists of a box displaying a value and two or four
buttons, two at the left and two at the right side. The user can press
these buttons to change the value. If the counter has four buttons,
the left-most and right-most button make the value change in large
steps, the other buttons make it change in small steps. As long as the
user keeps the mouse pressed, the value changes.


@ifnottex

@menu
* Adding Counter Objects:   Adding Counter Objects
* Counter Types:            Counter Types
* Counter Interaction:      Counter Interaction
* Other Counter Routines:   Other Counter Routines
* Counter Attributes:       Counter Attributes
* Remarks:                  Counter Remarks
@end menu

@end ifnottex


@node Adding Counter Objects
@subsection Adding Counter Objects

To add a counter to a form use
@findex fl_add_counter()
@anchor{fl_add_counter()}
@example
FL_OBJECT *fl_add_counter(int type, FL_Coord x, FL_Coord y,
                          FL_Coord w, FL_Coord h, const char *label)
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed below the counter.

@node Counter Types
@subsection Counter Types

@ifhtml
@center @image{images/counters}
@end ifhtml
@ifnothtml
@center @image{images/counters,8cm}
@end ifnothtml


The following types of counters are available:
@table @code
@tindex FL_NORMAL_COUNTER
@anchor{FL_NORMAL_COUNTER}
@item FL_NORMAL_COUNTER
A counter with two buttons on each side.

@tindex FL_SIMPLE_COUNTER
@anchor{FL_SIMPLE_COUNTER}
@item FL_SIMPLE_COUNTER
A counter with one button on each side.
@end table

@node Counter Interaction
@subsection Counter Interaction

The user changes the value of the counter by keeping his mouse pressed
on one of the buttons. Per default whenever the mouse is released and
the counter value is changed the counter is returned to the
application program or its callback is invoked.

In some applications you might want the counter to be returned to the
application program (or the callback invoked) e.g.@: whenever the
value changes and not only when the mouse is released. To this end use
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
@noindent
where @code{when} can be either
@table @code
@item @ref{FL_RETURN_NONE}
Never report or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end (mouse release) and only if the counter
value is changed.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the counter value is changed. This
is the default setting.

@item @ref{FL_RETURN_END}
Return or invoke callback at the end regardless if the counter value is
changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback when the counter value has changed or mouse
button has been released.
@end table


@node Other Counter Routines
@subsection Other Counter Routines

To change the value of the counter, it's bounds and stp size use the
routines
@findex fl_set_counter_value()
@anchor{fl_set_counter_value()}
@findex fl_set_counter_bounds()
@anchor{fl_set_counter_bounds()}
@findex fl_set_counter_step()
@anchor{fl_set_counter_step()}
@example
void fl_set_counter_value(FL_OBJECT *obj, double val);
void fl_set_counter_bounds(FL_OBJECT *obj, double min, double max);
void fl_set_counter_step(FL_OBJECT *obj, double small, double large);
@end example
@noindent
The first routine sets the value (default is 0) of the counter, the
second routine sets the minimum and maximum values that the counter
will take (default are -1000000 and 1000000, respectively) and the
third routine sets the sizes of the small and large steps (defaults to 0.1
and 1). (For simple counters only the small step is used.)

For conflicting settings, bounds take precedence over value, i.e., if
setting a value that is outside of the current bounds, it is clamped.
Also changing the bounds in a way that the current counter value isn't
within the new bounds range anymore will result in its value being
adjusted to the nearest of the new limits.

To obtain the current value of the counter use
@findex fl_get_counter_value()
@anchor{fl_get_counter_value()}
@example
double fl_get_counter_value(FL_OBJECT *obj);
@end example

To obtain the current bounds and steps, use the following functions
@findex fl_get_counter_bounds()
@anchor{fl_get_counter_bounds()}
@findex fl_get_counter_step()
@anchor{fl_get_counter_step()}
@example 
void fl_get_counter_bounds(FL_OBJECT *obj, double *min, double *max);
void fl_get_counter_step(FL_OBJECT *obj, double *small, double *large);
@end example

To set the precision (number of digits after the dot) with which the
counter value is displayed use the routine
@findex fl_set_counter_precision()
@anchor{fl_set_counter_precision()}
@example
void fl_set_counter_precision(FL_OBJECT *obj, int prec);
@end example

To determine the current value of the precision use
@findex fl_get_counter_precision()
@anchor{fl_get_counter_precision()}
@example
int fl_get_counter_precision(FL_OBJECT *obj);
@end example

By default, the value shown is the counter value in floating point
format. You can override the default by registering a filter function
using the following routine
@findex fl_set_counter_filter()
@anchor{fl_set_counter_filter()}
@example
void fl_set_counter_filter(FL_OBJECT *obj,
                           const char *(*filter)(FL_OBJECT *,
                                                 double value,
                                                 int prec));
@end example
@noindent
where @code{value} and @code{prec} are the counter value and precision
respectively. The filter function @code{filter} should return a string
that is to be shown. Note that the default filter is equivalent to the
following
@example
const char *filter(FL_OBJECT *obj, double value, int prec) @{
    static char buf[32];

     sprintf(buf, "%.*f",prec,value);
     return buf;
@}
@end example

By default the counter value changes first slowly and the rate of
change then accelerates until a final speed is reached. The default delay
between the value changing is @w{600 ms} at the start and the final
delay is @w{50 ms}. You can change the initial delay by a call of
the function
@findex fl_set_counter_repeat()
@anchor{fl_set_counter_repeat()}
@example
void fl_set_counter_repeat(FL_OBJECT *obj, int millisec);
@end example
@noindent
and the final delay by using
@findex fl_set_counter_min_repeat()
@anchor{fl_set_counter_min_repeat()}
@example
void fl_set_counter_min_repeat(FL_OBJECT *obj, int millisec);
@end example
@noindent
where in both cases the argument @code{millisec} is the delay in
milli-seconds. The current settings for the initial and final delay
can be obtained by calling the functions
@findex fl_get_counter_repeat()
@anchor{fl_get_counter_repeat()}
@findex fl_get_counter_min_repeat()
@anchor{fl_get_counter_min_repeat()}
@example
int fl_get_counter_repeat(FL_OBJECT *obj);
int fl_get_counter_min_repeat(FL_OBJECT *obj);
@end example

Until version 1.0.91 of the library the delay between changes of a
counter was constant (with a default value of @w{100 ms}). To obtain
this traditional behaviour simple set the initial and final delay to
the same value.

As a third alternative you can also request that only the first change
of the counter has a different delay from all the following ones. To
achieve this call
@findex fl_set_counter_speedjump()
@anchor{fl_set_counter_speedjump()}
@example
void fl_set_counter_speedjump(FL_OBJECT *obj, int yes_no);
@end example
@noindent
with a true value for @code{yes_no}. The delay for the first change of
the counter value will then be the one set by
@code{@ref{fl_set_counter_repeat()}} and the following delays last as
long as set by @code{@ref{fl_set_counter_min_repeat()}}.

To determine the setting for "speedjumping" call
@findex fl_get_counter_speedjump()
@anchor{fl_get_counter_speedjump()}
@example
int fl_get_counter_speedjump(FL_OBJECT *obj);
@end example


@node Counter Attributes
@subsection Counter Attributes

Never use @code{FL_NO_BOX} as the boxtype for a counter.

The first color argument (@code{col1}) t
@code{@ref{fl_set_object_color()}} controls the color of the
background of the counter, the second (@code{col2}) sets the color of
the arrow buttons of the counter.


@node Counter Remarks
@subsection Remarks

See demo program @file{counter.c} for an example of the use of
counters.


@node Spinner Object
@section Spinner Object

A spinner object is a combination of a (numerical) input field with
two (touch) buttons that allow to increment or decrement the value in
the (editable) input field. I.e.@: the user can change the spinners
value by either editing the value of the input field or by using the
up/down buttons shown beside the input field.

There are two types of spinner objects, one for integer and one for
floating point values. You can set limits on the values that can be
input and you can also set the amount of increment/decrement achieved
when clicking on its buttons.

@ifnottex

@menu
* Adding Spinner Objects:   Adding Spinner Objects
* Spinner Types:            Spinner Types
* Spinner Interaction:      Spinner Interaction
* Other Spinner Routines:   Other Spinner Routines
* Spinner Attributes:       Spinner Attributes
@end menu

@end ifnottex

@node Adding Spinner Objects
@subsection Adding Spinner Objects

To add a spinner to a form use
@findex fl_add_spinner()
@anchor{fl_add_spinner()}
@example
FL_OBJECT *fl_add_spinner(int type, FL_Coord x, FL_Coord y,
                          FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed on the left of the spinner object.


@node Spinner Types
@subsection Spinner Types

There are two types of spinners, one for input of integer and
one for floating point values:
@table @code
@tindex FL_INT_SPINNER
@anchor{FL_INT_SPINNER}
@item FL_INT_SPINNER
A spinner that allows input of integer values.

@tindex FL_FLOAT_SPINNER
@anchor{FL_FLOAT_SPINNER}
@item FL_FLOAT_SPINNER
A spinner that allows input of floating point values.
@end table

The way a spinner looks like depends on its dimensions. If it's at
least as wide as it's high the two buttons are drawn above each other
to the right of the input field (and are marked with and up and
down pointing triangle), while when the object is higher than it's
wide they are drawn beside each other and below the input field
(and the markers are then left and right pointing arrows).


@node Spinner Interaction
@subsection Spinner Interaction

The user can change the value of a spinner in two ways. She can either
edit the value in the spinner directly (exactly the same as for an
integer or floating point input object (@ref{Part III Input Objects})
or by clicking on one of the buttons that will increment or decrement
the value.

Per default the spinner object gets returned to the application
(or the associated callback is called) whenever the value changed
and the interaction seems to have ended. If you want it returned
under different circumstances use the function
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
where the parameter @code{when} can be one of the four values
@table @code
@item @ref{FL_RETURN_NONE}
Never return or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end of interaction (when either the input
field loses the focus or one of the buttons was released) and the
spinner's value changed during the interaction.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the spinner's value changed. This
is the default.

@item @ref{FL_RETURN_END}
Return or invoke callback at end of interaction regardless of the
spinner's value having changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback whenever the value changed or the
interaction ended.
@end table


@node Other Spinner Routines
@subsection Other Spinner Routines

Probably the most often used spinner functions are
@findex fl_get_spinner_value()
@anchor{fl_get_spinner_value()}
@findex fl_set_spinner_value()
@anchor{fl_set_spinner_value()}
@example
double fl_get_spinner_value(FL_OBJECT *obj );
double fl_set_spinner_value(FL_OBJECT *obj, double val);
@end example
@noindent
The first one returns the value of a spinner. The type of the return
value is a double for both integer and floating point spinners, so
you have to convert it for integer spinners appropriately, e.g:@:
using the @code{FL_nint()} macro, that converts a double to the
nearest integer value.

You can set or retrieve the upper and lower limit the value a spinner
can be set to using the functions
@findex fl_set_spinner_bounds()
@anchor{fl_set_spinner_bounds()}
@findex fl_get_spinner_bounds()
@anchor{fl_get_spinner_bounds()}
@example
void fl_set_spinner_bounds(FL_OBJECT *obj, double min, double max);
void fl_get_spinner_bounds(FL_OBJECT *obj, double *min, double *max);
@end example
@noindent
Since this function is to be used for integer as well as floating
point spinner objects the @code{double} type values must be converted
as necessary for @code{@ref{FL_INT_SPINNER}}.

The default limits are @code{-10000} and @code{10000}, but can be
set to up to @code{INT_MIN} and @code{INT_MIN} for
@code{@ref{FL_INT_SPINNER}}s and @code{-DBL_MAX} and @code{DBL_MAX}
for @code{@ref{FL_FLOAT_SPINNER}}s.

To set or determine the step size by which a spinner will be
incremented or decremented when one of the buttons is clicked on use
@findex fl_set_spinner_step()
@anchor{fl_set_spinner_step()}
@findex fl_get_spinner_step()
@anchor{fl_get_spinner_step()}
@example
void fl_set_spinner_step(FL_OBJECT *obj, double step);
double fl_get_spinner_step(FL_OBJECT *obj);
@end example
@noindent
The default step size is @code{1} for both @code{@ref{FL_INT_SPINNER}}
and @code{@ref{FL_FLOAT_SPINNER}} objects.


For @code{@ref{FL_FLOAT_SPINNER}} objects you can set (or determine)
how many digits after the decimal point are shown by using
@findex fl_set_spinner_precision()
@anchor{fl_set_spinner_precision()}
@findex fl_get_spinner_precision()
@anchor{fl_get_spinner_precision()}
@example
void fl_set_spinner_precision(FL_OBJECT *obj, int prec);
int fl_get_spinner_precision(FL_OBJECT *obj);
@end example
@noindent
This is per default set to 6 digits after the decimal point. The
function for setting the precision has no effect on
@code{@ref{FL_INT_SPINNER}} objects and the other one returns 0 for
this type of spinners.


@node Spinner Attributes
@subsection Spinner Attributes

Please don't change the boxtype from @code{@ref{FL_NO_BOX}}.

The label color and font can be set using the normal
@code{@ref{fl_set_object_lcol()}}, @code{@ref{fl_set_object_lsize()}}
and @code{@ref{fl_set_object_lstyle()}} functions. The color of the
input field of a spinner object can be set via using
@code{@ref{fl_set_object_color()}} where the first color argument
(@code{col1}) controls the color of the input field when it is not
selected and the second (@code{col2}) is the color when selected.

Instead of creating a plethora of functions to influence all the other
aspects of how the spinner is drawn (colors, font types etc.) the user
is given direct access to the sub-objects of a spinner. To this end
three functions exist:
@findex fl_get_spinner_input()
@anchor{fl_get_spinner_input()}
@findex fl_get_spinner_up_button()
@anchor{fl_get_spinner_up_button()}
@findex fl_get_spinner_down_button()
@anchor{fl_get_spinner_down_button()}
@example
FL_OBJECT *fl_get_spinner_input(FL_OBJECT *obj);
FL_OBJECT *fl_get_spinner_up_button(FL_OBJECT *obj);
FL_OBJECT *fl_get_spinner_down_button(FL_OBJECT *obj);
@end example
@noindent
They return the addresses of the objects the spinner object is made up
from and those then can be used to set or query the way the individual
components are drawn. The addresses of these sub-objects shouldn't be
used for any other purposes, especially their callback function may
never be changed!


@node Thumbwheel Object
@section Thumbwheel Object

Thumbwheel is another valuator that can be useful for letting the user
indicate a value between some fixed bounds. Both horizontal and
vertical thumbwheels exist. They have a minimum, a maximum and a
current value (all floating point values). The user can change the
current value by rolling the wheel.

@ifnottex

@menu
* Adding Thumbwheel Objects:   Adding Thumbwheel Objects
* Thumbwheel Types:            Thumbwheel Types
* Thumbwheel Interaction:      Thumbwheel Interaction
* Other Thumbwheel Routines:   Other Thumbwheel Routines
* Thumbwheel Attributes:       Thumbwheel Attributes
* Remarks:                     Thumbwheel Remarks
@end menu

@end ifnottex


@node Adding Thumbwheel Objects
@subsection Adding Thumbwheel Objects

To add a thumbwheel to a form use
@findex fl_add_thumbwheel()
@anchor{fl_add_thumbwheel()}
@example
FL_OBJECT *fl_add_thumbwheel(int type, FL_Coord x, FL_Coord y,
                             FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed below the thumbwheel.


@node Thumbwheel Types
@subsection Thumbwheel Types


@ifhtml
@center @image{images/thumbwheels}
@end ifhtml
@ifnothtml
@center @image{images/thumbwheels,7cm}
@end ifnothtml


The following types of thumbwheels are available:
@table @code
@tindex FL_VERT_THUMBWHEEL
@anchor{FL_VERT_THUMBWHEEL}
@item FL_VERT_THUMBWHEEL
A vertical thumbwheel.

@tindex FL_HOR_THUMBWHEEL
@anchor{FL_HOR_THUMBWHEEL}
@item FL_HOR_THUMBWHEEL
A horizontal thumbwheel.
@end table


@node Thumbwheel Interaction
@subsection Thumbwheel Interaction

Whenever the user changes the value of the thumbwheel using the mouse
or keyboard, the thumbwheel is returned (or the callback called) by
the interaction routines. You change the value of a thumbwheel by
dragging the mouse inside the wheel area or, for vertical thumbwheels
also by using the scroll wheel of the mouse. Each pixel of movement
changes the value of the thumbwheel by 0.005, which you can change
using the @code{@ref{fl_set_thumbwheel_step()}} function.

The keyboard can be used to change the value of a thumbwheel.
Specifically, the @code{<Up>} and @code{<Down>} cursor keys can be
used to increment or decrement the value of a vertical thumbwheel and
the @code{<Right>} and @code{<Left>} cursor keys can be used to
increment or decrement the value of horizontal thumbwheel. Each
pressing of the cursor key changes the thumbwheel value by the current
step value. The @code{<Home>} key can be used to set the thumbwheel to
a known value, which is the average of the minimum and the maximum
value of the thumbwheel.

In some applications you might not want the thumbwheel to be returned
all the time. To change the default, call the following routine:
@example
void fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
where the parameter @code{when} can be one of the four values
@table @code
@item @ref{FL_RETURN_NONE}
Never return or invoke callback.

@item @ref{FL_RETURN_END_CHANGED}
Return or invoke callback at end (mouse release) if value is changed
since last return.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever the thumbwheel value is changed.

@item @ref{FL_RETURN_END}
Return or invoke callback at end (mouse release) regardless if the
value is changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback whenever the value changes or the mouse
button is released.
@end table

See demo program @file{thumbwheel.c} for an example use of this.


@node Other Thumbwheel Routines
@subsection Other Thumbwheel Routines

To change the value and bounds of a thumbwheel use the following routines
@findex fl_set_thumbwheel_value()
@anchor{fl_set_thumbwheel_value()}
@findex fl_set_thumbwheel_bounds()
@anchor{fl_set_thumbwheel_bounds()}
@example
double fl_set_thumbwheel_value(FL_OBJECT *obj, double val);
void fl_set_thumbwheel_bounds(FL_OBJECT *obj, double min, double max);
@end example
@noindent
By default, the minimum value is 0.0, the maximum is 1.0 and the value
is 0.5.

To obtain the current value or bounds of a thumbwheel use
@findex fl_get_thumbwheel_value()
@anchor{fl_get_thumbwheel_value()}
@findex fl_get_thumbwheel_bounds()
@anchor{fl_get_thumbwheel_bounds()}
@example
double fl_get_thumbwheel_value(FL_OBJECT *obj);
void fl_get_thumbwheel_bounds(FL_OBJECT *obj, double *min, double *max);
@end example

By default, the bounds are "hard", i.e., once you reach the minimum or
maximum, the wheel would not turn further in this direction. However,
if desired, you can make the bounds to turn over such that it crosses
over from the minimum to the maximum value and vice versa. To this
end, the following routine is available
@findex fl_set_thumbwheel_crossover()
@anchor{fl_set_thumbwheel_crossover()}
@example
int fl_set_thumbwheel_crossover(FL_OBJECT *obj, int yes_no);
@end example

In a number of situations you might like thumbwheel values to be
rounded to some values, e.g. to integer values. To this end use the
routine
@findex fl_set_thumbwheel_step()
@anchor{fl_set_thumbwheel_step()}
@example
void fl_set_thumbwheel_step(FL_OBJECT *obj, double step);
@end example
@noindent
After this call thumbwheel values will be rounded to multiples of
@code{step}. Use a value 0.0 for @code{step} to switch off rounding.


@node Thumbwheel Attributes
@subsection Thumbwheel Attributes

Setting colors via @code{@ref{fl_set_object_color()}} has no effect on
thumbwheels.


@node Thumbwheel Remarks
@subsection Remarks

See the demo program @file{thumbwheel.c} for an example of the use of
thumbwheels.