Adding comments to recent Fluid changes.

2 files changed, 54 insertions, 14 deletions

diff --git a/fluid/Shortcut_Button.cxx b/fluid/Shortcut_Button.cxx
index 72e4470a9..07135c96b 100644
--- a/fluid/Shortcut_Button.cxx
+++ b/fluid/Shortcut_Button.cxx
@@ -179,9 +179,13 @@ int Widget_Bin_Window_Button::handle(int inEvent)
 
 /** \class Fluid_Coord_Input
  An Input field for widget coordinates and sizes.
- This widget adds basic math capability to the text input field.
+ This widget adds basic math capability to the text input field and a number
+ of variables that can be used in the formula.
  */
 
+/**
+ Create an input field.
+ */
 Fluid_Coord_Input::Fluid_Coord_Input(int x, int y, int w, int h, const char *l) :
 Fl_Input(x, y, w, h, l),
 user_callback_(0L),
@@ -201,6 +205,15 @@ void Fluid_Coord_Input::callback_handler(void *v) {
   value( value() );
 }
 
+/**
+ Get the value of a variable.
+ Collects all conesecutive ASCII letters into a variable name, scans the
+ Variable list for that name, and then calls the corresponding callback from
+ the Variable array.
+ \param s points to the first character of the variable name, must point after
+    the last character of the variable name when returning.
+ \return the integer value that wasf= found or calculated
+ */
 int Fluid_Coord_Input::eval_var(uchar *&s) const {
   if (!vars_)
     return 0;
@@ -217,10 +230,10 @@ int Fluid_Coord_Input::eval_var(uchar *&s) const {
 }
 
 /**
- Evaluate a textual function into an integer.
- \param s remaining text in this function
+ Evaluate a formula into an integer, recursive part.
+ \param s remaining text in this formula, must return a pointer to the next
+    character that will be interpreted.
  \param prio priority of current operation
- \param flags
  \return the value so far
  */
 int Fluid_Coord_Input::eval(uchar *&s, int prio) const {
@@ -270,6 +283,15 @@ int Fluid_Coord_Input::eval(uchar *&s, int prio) const {
   return v;
 }
 
+/**
+ Evaluate a formula into an integer.
+ The interpreter understand unary plus and minus, basic integer math
+ (+, -, *, /), brackets, and can handle a user defined list of variables
+ by name. There is no error checking. We assume that the formula is
+ entered correctly.
+ \param s formula as a C string
+ \return the calculated value
+ */
 int Fluid_Coord_Input::eval(const char *s) const
 {
   // duplicate the text, so we can modify it
@@ -289,18 +311,16 @@ int Fluid_Coord_Input::eval(const char *s) const
   return ret;
 }
 
-
+/**
+ Evaluate the formula and return the result.
+ */
 int Fluid_Coord_Input::value() const {
-
-//  int v = 0;
-//  v = eval("2+5+10");
-//  v = eval("2*5+20"); // 30
-//  v = eval("2+5*20"); // 102
-//  v = eval("(2+5)*20"); // 140
-//  v = eval("2*(2+5)*20"); // 140
   return eval(text());
 }
 
+/**
+ Set the field to an integer value, replacing previous texts.
+ */
 void Fluid_Coord_Input::value(int v) {
   char buf[32];
   fl_snprintf(buf, sizeof(buf), "%d", v);
diff --git a/fluid/Shortcut_Button.h b/fluid/Shortcut_Button.h
index 443d2bd67..97d7d9323 100644
--- a/fluid/Shortcut_Button.h
+++ b/fluid/Shortcut_Button.h
@@ -20,6 +20,7 @@
 #include <FL/Fl_Button.H>
 #include <FL/Fl_Input.H>
 
+// Button will catch and display keyboard shortcuts when activated.
 class Shortcut_Button : public Fl_Button {
 public:
   int svalue;
@@ -29,6 +30,7 @@ public:
     Fl_Button(X,Y,W,H,l) {svalue = 0;}
 };
 
+// Adding drag and drop for dragging widgets into windows.
 class Widget_Bin_Button : public Fl_Button {
 public:
   int handle(int);
@@ -36,6 +38,7 @@ public:
   Fl_Button(X,Y,W,H,l) { }
 };
 
+// Adding drag and drop functionality to drag window prototypes onto the desktop.
 class Widget_Bin_Window_Button : public Fl_Button {
 public:
   int handle(int);
@@ -43,15 +46,20 @@ public:
   Fl_Button(X,Y,W,H,l) { }
 };
 
-
+// Callback signature for function returning the value of a variable.
 typedef int (Fluid_Coord_Callback)(class Fluid_Coord_Input const *, void*);
 
+// Entry for a list of variables available to an input field.
+// Fluid_Coord_Input::variables() expects an array of Fluid_Coord_Input_Vars
+// with the last entry's name_ set to NULL.
 typedef struct Fluid_Coord_Input_Vars {
   const char *name_;
   Fluid_Coord_Callback *callback_;
 } Fluid_Coord_Input_Vars;
 
-class Fluid_Coord_Input : public Fl_Input {
+// A text input widget that understands simple math.
+class Fluid_Coord_Input : public Fl_Input
+{
   Fl_Callback *user_callback_;
   Fluid_Coord_Input_Vars *vars_;
   void *vars_user_data_;
@@ -60,15 +68,27 @@ class Fluid_Coord_Input : public Fl_Input {
   int eval_var(uchar *&s) const;
   int eval(uchar *&s, int prio) const;
   int eval(const char *s) const;
+
 public:
   Fluid_Coord_Input(int x, int y, int w, int h, const char *l=0L);
+
+  /** Return the text in the widget text field. */
   const char *text() const { return Fl_Input::value(); }
+
+  /** Set the text in the text field */
   void text(const char *v) { Fl_Input::value(v); }
+
   int value() const;
   void value(int v);
+
+  /** Set the general callback for this widget. */
   void callback(Fl_Callback *cb) {
     user_callback_ = cb;
   }
+
+  /** Set the list of the available variables
+   \param vars array of variables, last entry `has name_` set to `NULL`
+   \param user_data is forwarded to the Variable callback */
   void variables(Fluid_Coord_Input_Vars *vars, void *user_data) {
     vars_ = vars;
     vars_user_data_ = user_data;