FLTK::Valuator - Base class for sliders and all other one-value "knobs"
Base class for sliders and all other one-value "knobs".
The FLTK::Valuator class controls a single floating-point value and provides a consistent interface to set the
and insures that callbacks are done the same for every object.
Callbacks are done each time the user changes the value. So if they drag a slider, the callback is done each time the slider handle moves to a new pixel.
For most subclasses you can call
when() to get some other callback behaviors:
FLTK::WHEN_CHANGED: this is the default, callback is done on any change.
FLTK::WHEN_RELEASE: it will only do the callback when the user moves the slider and then lets it go on a different value than it started.
FLTK::WHEN_RELEASE_ALWAYS: will do the callback when the user lets go of the slider whether or not the value changed.
FLTK::WHEN_NEVER: do not do the callback, instead it will turn on the
$valuator->linesize( $value );
my $value = $valuator->linesize( );
The linesize is the amount the valuator moves in response to an arrow key,
or the user clicking an up/down button,
or a click of the mouse wheel.
If this has not been set,
this will return the maximum of
1/50 of the range.
$valuator->maximum( $value );
Sets the maximum value for the valuator.
For most subclasses the user cannot move the value outside the
minimum( )..maximum( ) range if it starts inside this range.
These values should be multiples of the
step( ) to avoid ambiguity and possible implementation changes.
For most subclasses, the minimum may be greater than the maximum. This has the effect of "reversing" the object so the larger values are in the opposite direction. This also switches which end of the filled sliders is filled.
You probably need to
redraw() the widget after changing the range.
$valuator->minimum( $value );
Sets the minimum value for the valuator.
my $self = $valuator->new( $x, $y, $w, $h, $label );
The constructor initializes:
$valuator->step( $value );
Set the step value.
As the user moves the mouse the value is rounded to a multiple of this.
Values that are sufficently close to
N is an integer) are detected and assummed to be exactly
step(.00001) will work as wanted.
If this is zero (the default) then all rounding is disabled. This results in the smoothest controller movement but this is not recommended if you want to present the resulting numbers to the user as text, because they will have useless extra digits of precision.
Negative values for
step() produce undocumented results.
my $val = $valuator->value( );
Returns the current value.
my $okay = $valuator->value( $v );
Sets the current value,
redrawing the widget if necessary by calling
The new value is stored unchanged,
even if it is outside the range or not a multiple of
Returns true if the new value is different.
Should you require a subclass of Valuator, here are a few notes to get you started.
The base class
handle( ) accepts
FOCUS and recognizes a number of keystrokes that adjust the value.
Your subclass can call this to get these keystrokes,
it can also do it's own keystroke handling if it wants.
linesize(), Style::wheel_scroll_lines is ignored. However Scrollbar does use Style::wheel_scroll_lines.
format( ) prints the current value into the passed buffer as a user-readable and editable string.
Returns the number of bytes (not counting the terminating
\0) written to the buffer.
Calling code can assumme that the written string is never longer than 20 characters.
This is used by subclasses that let the user edit the value in a textfield. Since this is a virtual function, you can override this in a subclass of those and change how the numbers are displayed.
The default version prints enough digits for the current
step() is zero it does a
If step is an integer it does
Otherwise it does a
%.nf format where
n is enough digits to show the step,
maximum of 8.
Subclasses should call this when the user starts to change the value.
Subclasses should call this as the user moves the value.
The passed number is an arbitrary-precision value you want to set it to,
this function clamps it to the range (if
previous_value() is in range) and rounds it to the nearest multiple of
and then stores it into
It then does the
callback() if necessary.
Subclasses should call this when the user stops moving the value. It may call the callback.
Sanko Robinson <email@example.com> - http://sankorobinson.com/
Copyright (C) 2008-2010 by Sanko Robinson <firstname.lastname@example.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.