FLTK Valuators

A "valuator" widget controls a single floating-point value. All valuators are subclasses of the widget Fl_Valuator. This widget provides a consistent interface to set the value, range, and step, and insures that callbacks are done the same for every object.

There are probably more of these classes in fltk than any others:

In the above diagram each box surrounds an actual subclass. These are further differentiated by setting the type() of the widget to the symbolic value labelling the widget. The ones labelled "0" are the default versions with a type(0). For consistency the symbol "FL_VERTICAL" is defined as zero.

class Fl_Valuator : public Fl_Widget

double Fl_Valuator::value() const;
int Fl_Valuator::value(double);

Get or set the current value. The new value is not clamped or otherwise changed before storing it (use clamp() or round() to modify the value before calling this if you want). If the new value is different than the current one the object is redrawn if necessary. The initial value is zero.

double Fl_Valuator::minimum() const ;
void Fl_Valuator::minimum(double);
double Fl_Valuator::maximum() const ;
void Fl_Valuator::maximum(double);
void Fl_Valuator::range(double min, double max);

When the user manipulates the widget, the value is limited to this range. This clamping is done after rounding to the step value (this makes a difference if the range is not a multiple of the step).

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.

Some widgets consider this a "soft" range. This means they will stop at the range, but if the user releases and grabs the control again and tries to move it further, it is allowed.

The range may affect the display, if so you must redraw() the widget after changing the range.

double Fl_Valuator::step() const;
void Fl_Valuator::step(double);
void Fl_Valuator::step(int A, int B);

Get or set the step value. As the user moves the mouse the value is rounded to the nearest multiple of the step value. This is done before clamping it to the range. For most objects the default step is zero.

For precision the step is stored as the ratio of two integers, A/B. You can set these integers directly. Currently setting a floating point value sets the nearest A/1 or 1/B value possible.

int Fl_Valuator::format(char*, double);

Format the passed value to show enough digits so that for the current step value. If the step has been set to zero then it does a %g format. The characters are written into the passed buffer.

double Fl_Valuator::round(double);

Round the passed value to the nearest step increment. Does nothing if step is zero.

double Fl_Valuator::clamp(double);

Clamp the passed value to the range.

double Fl_Valuator::increment(double,int n);

Adds n times the step value to the passed value. If step was set to zero it uses fabs(maximum()-minimum())/100.

int Fl_Widget::changed() const;
void Fl_Widget::set_changed();
void Fl_Widget::clear_changed();

This value is true if the user has moved the slider. It is turned off by value(x) and just before doing a callback (the callback can turn it back on if desired).

Fl_When Fl_Widget::when() const;
void Fl_Widget::when(Fl_When);

Controls when callbacks are done. The following values are useful:
• 0 : The callback is not done. changed() is turned on when the user moves the slider.
• FL_WHEN_CHANGED (default value) : The callback is done as the user moves the slider.
• FL_WHEN_RELEASE : The callback is done when the user releases the mouse.
• FL_WHEN_RELEASE|FL_WHEN_NOT_CHANGED : The callback is done when the user clicks the mouse on the slider, even if the slider does not move.

Fl_Valuator Protected methods

If you are making your own subclass of Fl_Valuator you should call these to handle events, along with the public clamp, double, increment methods shown above.

void Fl_Valuator::handle_push();

Copies the current value to previous_value().

double Fl_Valuator::previous_value();

The value when the mouse was pushed.

double Fl_Valuator::softclamp(double);

Same as Fl_Valuator::clamp() except it does nothing if previous_value() was already at the maximum() or minimum() and the new value is outside the range in that direction.

void Fl_Valuator::handle_drag(double newvalue);

Call this for any changes to the value caused by the user (don't call value(double), that is for changes caused by the application). This will produce the correct callbacks.

void Fl_Valuator::handle_release();

Call this when the user lets go of the mouse, or otherwise to confirm a change. This will produce the correct callbacks.

virtual void Fl_Valuator::value_damage();

This is called whenever the value being displayed changes. The default version does damage(2). You can do more (such as updating a text field), or do nothing (if the current value is not visible).

class Fl_Slider : public Fl_Valuator

A sliding knob inside a box, Often used as a scrollbar. Moving the box all the way to the top/left sets it to the minimum(), and to the bottom/right to the maximum(). The minimum() may be greater than the maximum() to "reverse" the slider direction.

Fl_Slider::Fl_Slider(int x,int y,int w,int h, const char *l = 0);

The constructor.

uchar Fl_Widget::type() const;
void Fl_Widget::type(uchar);

Setting this changes how the slider is drawn. The default value is FL_VERTICAL. Notice that the '1' bit indicates horizontal.
• FL_VERTICAL 0
• FL_HORIZONTAL 1
• FL_VERT_FILL_SLIDER 2
• FL_HOR_FILL_SLIDER 3
• FL_VERT_NICE_SLIDER 4
• FL_HOR_NICE_SLIDER 5

float Fl_Slider::slider_size() const;
void Fl_Slider::slider_size(float);

Get or set the dimensions of the moving piece of slider. This is the fraction of the size of the entire widget. If you set this to 1 then the slider cannot move. The default value is .08.

For the "fill" sliders this is the size of the area around the end that causes a drag effect rather than causing the slider to jump to the mouse.

Fl_Boxtype Fl_Slider::slider() const;
void Fl_Slider::slider(Fl_Boxtype);

Set the type of box to draw for the moving part of the slider. The color of the moving part (or of the notch in it for the nice sliders) is controlled by selection_color(). The default value of zero causes the slider to figure out what to draw from box().

int Fl_Slider::scrollvalue(int windowtop,int windowsize,int first,int totalsize);

Same as Fl_Scrollbar::value().

class Fl_Scrollbar : public Fl_Slider

Clicking on the arrows move up and down by linesize(). Scrollbars also accept FL_SHORTCUT events: the arrows move by linesize(), and vertical scrollbars take Page Up/Down (they move by the page size minus linesize()) and Home/End (they jump to the top or bottom).

Scrollbars have step(1) preset (they always return integers). If desired you can set the step() to non-integer values. You will then have to use casts to get at the floating-point versions of value() from Fl_Slider.

Fl_Scrollbar::Fl_Scrollbar(int x,int y,int w,int h, const char *l = 0);

The constructor. You want to do type(FL_HORIZONTAL) if you want a horizontal scrollbar.

int Fl_Scrollbar::value();

Scrollbars cast the value() to an integer (this avoids compiler warnings in common cases). You can get the floating point value with Fl_Slider::value().

int Fl_Scrollbar::value(int position, int size, int top, int total);

Correctly sets Fl_Slider::value(), range(), and slider_size() to make a variable-sized scrollbar. The 4 arguments are positions in arbitrary units (usually pixels). position is the position of the top of your window, size is the size of your window, top is the location your data starts at (usually 0), and total is the total size of your data. All strange cases (no data, data less than window size, window position outside the data, etc) are handled correctly by this function. You should call this every time your window changes size, your data changes size, or your scroll position changes (even if in response to a callback from this scrollbar). All necessary calls to redraw() are done.

int Fl_Scrollbar::linesize() const;
void Fl_Scrollbar::linesize(int i);

This number controls how big the steps are that the arrow keys do. In addition page up/down move by the size last sent to value() minus one linesize(). The default is 16.

class Fl_Value_Slider : public Fl_Slider

These are sliders with a box displaying the current value. All the methods for an Fl_Slider work.

Fl_Value_Slider::Fl_Value_Slider(int x,int y,int w,int h, const char *l = 0);

The constructor. You will want to call type() to set different types.

Fl_Font Fl_Value_Slider::textfont() const;
void Fl_Value_Slider::textfont(Fl_Font);
uchar Fl_Value_Slider::textsize() const;
void Fl_Value_Slider::textsize(uchar);
Fl_Color Fl_Value_Slider::textcolor() const;
void Fl_Value_Slider::textcolor(Fl_Color);

Get or set the font, font size, or color of the text. This is black by default.

class Fl_Adjuster : public Fl_Valuator

(The appearance is determined by which dimension is larger)
This type of control was stolen from Prisms, and has proven to be very useful for values that need a large dynamic range. When you press a button and drag to the right the value increases, when you drag to the left it decreases. The largest button adjusts by 100*step(), the next by 10*step() and that smallest button by step(). Clicking on the buttons increments by 10 times the amount dragging by a pixel does. Shift+click decrements by 10 times the amount.

Fl_Adjuster::Fl_Adjuster(int x,int y,int w,int h,const char* l=0);

The constructor takes a bounding box and label. It looks best if one of the dimensions is 3 times the other.

uchar Fl_Adjuster::soft() const;
void Fl_Adjuster::soft(uchar);

If "soft" is turned on, the user is allowed to drag the value outside the range. If they drag the value to one of the ends, let go, then grab again and continue to drag, they can get to any value. Default is one.

class Fl_Counter : public Fl_Valuator

This widget is provided for forms compatibility. It controls a single floating point value.

Fl_Counter::Fl_Counter(int x,int y,int w,int h,const char* l=0);

The constructor, makes a FL_NORMAL_COUNTER.

type(uchar);

• FL_NORMAL_COUNTER 0
• FL_SIMPLE_COUNTER 1

double Fl_Counter::lstep() const; void Fl_Counter::lstep(double);

Get or set the increment for the double-arrow buttons. The default value is 1.0.

class Fl_Dial : public Fl_Valuator

Circular dial to control a single floating point value.

Fl_Dial::Fl_Dial(int x,int y,int w,int h,const char* l=0);

The constructor, makes a FL_NORMAL_DIAL.

type(uchar);

• FL_NORMAL_DIAL 0
• FL_LINE_DIAL 1
• FL_FILL_DIAL 2

void Fl_Dial::angles(short a, short b);

These are supposed to control the angle the pointer is at when set to the minimum() or maximum(), but this is nyi.

class Fl_Roller : public Fl_Valuator

A knob similar to the zoom/dolly control in SGI's RapidApp toolkit. As you drag the mouse, each pixel of movement advances the value by step() (which defaults to 1/1000).

Fl_Roller::Fl_Roller(int x,int y,int w,int h,const char* l=0);

The constructor, makes a FL_VERTICAL roller.

Fl_Widget::type(uchar);

• FL_VERTICAL 0
• FL_HORIZONTAL 1

class Fl_Value_Input : public Fl_Valuator

The user can click in the text field and edit it (there is in fact a hidden Fl_Input with type(FL_FLOAT_INPUT) in there), and when they hit return or tab the value updates to what they typed and the callback is done.

If step() is not zero, the user can also drag the mouse across the object and thus slide the value. The left button moves one step() per pixel, the middle by 10*step(), and the left button by 100*step(). It is then impossible to select text by dragging across it, although clicking can still move the insertion cursor.

Fl_Value_Input::Fl_Value_Input(int x,int y,int w,int h,const char* l=0);

The constructor.

Fl_Font Fl_Value_Input::textfont() const;
void Fl_Value_Input::textfont(Fl_Font);
uchar Fl_Value_Input::textsize() const;
void Fl_Value_Input::textsize(uchar);
Fl_Color Fl_Value_Input::textcolor() const;
void Fl_Value_Input::textcolor(Fl_Color);
Fl_Color Fl_Value_Input::cursor_color() const;
void Fl_Value_Input::cursor_color(Fl_Color);

Get or set the colors and font used by the Fl_Input widget.

uchar Fl_Value_Input::soft() const;
void Fl_Value_Input::soft(uchar);

If "soft" is turned on, the user is allowed to drag the value outside the range. If they drag the value to one of the ends, let go, then grab again and continue to drag, they can get to any value. Default is zero.

class Fl_Value_Output : public Fl_Valuator

If you don't set the step() of this widget, it can be used as an output display for a floating point value.
If step() is not zero, the user can adjust the value by dragging the mouse left and right. The left button moves one step() per pixel, the middle by 10*step(), and the left button by 100*step().

This is much lighter-weight than a Fl_Value_Input because it contains no text editing code or character buffer.

Fl_Value_Output::Fl_Value_Output(int x,int y,int w,int h,const char* l=0);

The constructor.

Fl_Font Fl_Value_Output::textfont() const;
void Fl_Value_Output::textfont(Fl_Font);
uchar Fl_Value_Output::textsize() const;
void Fl_Value_Output::textsize(uchar);
FL_Color Fl_Value_Output::textcolor() const;
void Fl_Value_Output::textcolor(Fl_Color);

Get or set the font and color used to draw the number.

uchar Fl_Value_Output::soft() const;
void Fl_Value_Output::soft(uchar);

If "soft" is turned on, the user is allowed to drag the value outside the range. If they drag the value to one of the ends, let go, then grab again and continue to drag, they can get to any value. Default is zero.

(back to contents)