FL/Fl_Valuator.H

   1 //
   2 // "$Id: Fl_Valuator.H 7981 2010-12-08 23:53:04Z greg.ercolano $"
   3 //
   4 // Valuator header file for the Fast Light Tool Kit (FLTK).
   5 //
   6 // Copyright 1998-2010 by Bill Spitzak and others.
   7 //
   8 // This library is free software; you can redistribute it and/or
   9 // modify it under the terms of the GNU Library General Public
  10 // License as published by the Free Software Foundation; either
  11 // version 2 of the License, or (at your option) any later version.
  12 //
  13 // This library is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 // Library General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU Library General Public
  19 // License along with this library; if not, write to the Free Software
  20 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  21 // USA.
  22 //
  23 // Please report all bugs and problems on the following page:
  24 //
  25 //     http://www.fltk.org/str.php
  26 //
  27
  28 /* \file
  29    Fl_Valuator widget . */
  30
  31 #ifndef Fl_Valuator_H
  32 #define Fl_Valuator_H
  33
  34 #ifndef Fl_Widget_H
  35 #include "Fl_Widget.H"
  36 #endif
  37
  38 // shared type() values for classes that work in both directions:
  39 #define FL_VERTICAL             0 ///< The valuator can work vertically
  40 #define FL_HORIZONTAL           1 ///< The valuator can work horizontally
  41
  42 /**
  43   The Fl_Valuator class controls a single floating-point value
  44   and provides a consistent interface to set the value, range, and step,
  45   and insures that callbacks are done the same for every object.
  46   <P>There are probably more of these classes in FLTK than any others:
  47   <P ALIGN=CENTER>\image html  valuators.png</P>
  48   \image latex   valuators.png "Valuators derived from Fl_Valuators" width=10cm
  49   <P>In the above diagram each box surrounds an actual subclass.  These
  50   are further differentiated by setting the type() of the widget t
  51   o the symbolic value labeling the widget.
  52   The ones labelled "0" are the default versions with a type(0).
  53   For consistency the symbol FL_VERTICAL is defined as zero.
  54 */
  55 class FL_EXPORT Fl_Valuator : public Fl_Widget {
  56
  57   double value_;
  58   double previous_value_;
  59   double min, max; // truncates to this range *after* rounding
  60   double A; int B; // rounds to multiples of A/B, or no rounding if A is zero
  61
  62 protected:
  63   /** Tells if the valuator is an FL_HORIZONTAL one */
  64   int horizontal() const {return type()& FL_HORIZONTAL;}
  65   Fl_Valuator(int X, int Y, int W, int H, const char* L);
  66
  67   /** Gets the previous floating point value before an event changed it */
  68   double previous_value() const {return previous_value_;}
  69   /** Stores the current value in the previous value */
  70   void handle_push() {previous_value_ = value_;}
  71   double softclamp(double);
  72   void handle_drag(double newvalue);
  73   void handle_release(); // use drag() value
  74   virtual void value_damage(); // cause damage() due to value() changing
  75   /** Sets the current floating point value. */
  76   void set_value(double v) {value_ = v;}
  77
  78 public:
  79
  80     /**    Sets the minimum (a) and maximum (b) values for the valuator widget. */
  81     void bounds(double a, double b) {min=a; max=b;}
  82     /**    Gets the minimum value for the valuator.  */
  83     double minimum() const {return min;}
  84     /**    Sets the minimum value for the valuator.  */
  85     void minimum(double a) {min = a;}
  86     /**    Gets the maximum value for the valuator.  */
  87     double maximum() const {return max;}
  88     /**    Sets the maximum value for the valuator.  */
  89     void maximum(double a) {max = a;}
  90   /**
  91     Sets the minimum and maximum values for the valuator. When
  92     the user manipulates the widget, the value is limited to this
  93     range. This clamping is done <I>after</I> rounding to the step
  94     value (this makes a difference if the range is not a multiple of
  95     the step).
  96
  97     <P>The minimum may be greater than the maximum. This has the
  98     effect of "reversing" the object so the larger values
  99     are in the opposite direction. This also switches which end of
 100     the filled sliders is filled.</P>
 101
 102     <P>Some widgets consider this a "soft" range.  This
 103     means they will stop at the range, but if the user releases and
 104     grabs the control again and tries to move it further, it is
 105     allowed.</P>
 106
 107     <P>The range may affect the display. You must redraw()
 108     the widget after changing the range.
 109   */
 110   void range(double a, double b) {min = a; max = b;}
 111   /**    See double Fl_Valuator::step() const   */
 112   void step(int a) {A = a; B = 1;}
 113   /**    See double Fl_Valuator::step() const   */
 114   void step(double a, int b) {A = a; B = b;}
 115   void step(double s);
 116   /**
 117     Gets or sets the step value. As the user moves the mouse the
 118     value is rounded to the nearest multiple of the step value. This
 119     is done <I>before</I> clamping it to the range. For most widgets
 120     the default step is zero.
 121
 122     <P>For precision the step is stored as the ratio of two
 123     integers, A/B. You can set these integers directly. Currently
 124     setting a floating point value sets the nearest A/1 or 1/B value
 125     possible.
 126   */
 127   double step() const {return A/B;}
 128   void precision(int);
 129
 130   /** Gets the floating point(double) value. See int value(double) */
 131   double value() const {return value_;}
 132   int value(double);
 133
 134   virtual int format(char*);
 135   double round(double); // round to nearest multiple of step
 136   double clamp(double); // keep in range
 137   double increment(double, int); // add n*step to value
 138 };
 139
 140 #endif
 141
 142 //
 143 // End of "$Id: Fl_Valuator.H 7981 2010-12-08 23:53:04Z greg.ercolano $".
 144 //