Doxygen documentation WP11 Done!

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6255 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

8 files changed, 214 insertions, 16 deletions

diff --git a/FL/Fl_Spinner.H b/FL/Fl_Spinner.H
index 3ff59affb..3d65dfebc 100644
--- a/FL/Fl_Spinner.H
+++ b/FL/Fl_Spinner.H
@@ -40,10 +40,11 @@
 #  include <stdlib.h>
 
 
-//
-// Fl_Spinner widget class...
-//
-
+/**
+  This widget is a combination of the input
+  widget and repeat buttons. The user can either type into the
+  input area or use the buttons to change the value.
+*/
 class Fl_Spinner : public Fl_Group
 {
   double	value_;			// Current value
@@ -114,6 +115,11 @@ class Fl_Spinner : public Fl_Group
 
   public:
 
+		/**
+		  Creates a new Fl_Spinner widget using the given position, size,
+		  and label string.
+		  <P>Inherited destructor Destroys the widget and any value associated with it.
+		*/
 		Fl_Spinner(int X, int Y, int W, int H, const char *L = 0)
 		  : Fl_Group(X, Y, W, H, L),
 		    input_(X, Y, W - H / 2 - 2, H),
@@ -140,7 +146,9 @@ class Fl_Spinner : public Fl_Group
 		  down_button_.callback((Fl_Callback *)sb_cb, this);
 		}
 
+  /** Sets or returns the format string for the value. */
   const char	*format() { return (format_); }
+  /** Sets or returns the format string for the value. */
   void		format(const char *f) { format_ = f; update(); }
 
   int		handle(int event) {
@@ -163,13 +171,19 @@ class Fl_Spinner : public Fl_Group
 		  return Fl_Group::handle(event);
 		}
 
-  // Speling mistaks retained for source compatibility...
+  /** Speling mistakes retained for source compatibility \deprecated */
   double	maxinum() const { return (maximum_); }
+  /** Sets or returns the maximum value of the widget. */
   double	maximum() const { return (maximum_); }
+  /** Sets or returns the maximum value of the widget. */
   void		maximum(double m) { maximum_ = m; }
+  /** Speling mistakes retained for source compatibility \deprecated */
   double	mininum() const { return (minimum_); }
+  /** Sets or returns the minimum value of the widget. */
   double	minimum() const { return (minimum_); }
+  /** Sets or returns the minimum value of the widget. */
   void		minimum(double m) { minimum_ = m; }
+  /** Sets the minimum and maximum values for the widget. */
   void		range(double a, double b) { minimum_ = a; maximum_ = b; }
   void		resize(int X, int Y, int W, int H) {
 		  Fl_Group::resize(X,Y,W,H);
@@ -179,32 +193,51 @@ class Fl_Spinner : public Fl_Group
 		  down_button_.resize(X + W - H / 2 - 2, Y + H - H / 2,
 		                      H / 2 + 2, H / 2);
 		}
+  /**
+    Sets or returns the amount to change the value when the user clicks a button. 
+    Before setting step to a non-integer value, the spinner 
+    type() should be changed to floating point. 
+  */
   double	step() const { return (step_); }
+  /** See double Fl_Spinner::step() const */
   void		step(double s) {
 		  step_ = s;
 		  if (step_ != (int)step_) input_.type(FL_FLOAT_INPUT);
 		  else input_.type(FL_INT_INPUT);
 		  update();
 		}
+  /** Sets or Gets the color of the text in the input field. */
   Fl_Color	textcolor() const {
 		  return (input_.textcolor());
 		}
+  /** Sets or Gets the color of the text in the input field. */
   void		textcolor(Fl_Color c) {
 		  input_.textcolor(c);
 		}
+  /** Sets or Gets the font of the text in the input field. */
   Fl_Font       textfont() const {
 		  return (input_.textfont());
 		}
+  /** Sets or Gets the font of the text in the input field. */
   void		textfont(Fl_Font f) {
 		  input_.textfont(f);
 		}
+  /** Sets or Gets the size of the text in the input field. */
   Fl_Fontsize  textsize() const {
 		  return (input_.textsize());
 		}
+  /** Sets or Gets the size of the text in the input field. */
   void		textsize(Fl_Fontsize s) {
 		  input_.textsize(s);
 		}
+  /** Sets or returns the numeric representation in the input field.
+    Valid values are FL_INT_INPUT and FL_FLOAT_INPUT.
+    The first form also changes the format() template.
+    Setting a new spinner type via a superclass pointer will not work.
+    \note  type is not a virtual function. 
+  */
   uchar		type() const { return (input_.type()); }
+  /** See uchar	Fl_Spinner::type() const */
   void		type(uchar v) { 
                   if (v==FL_FLOAT_INPUT) {
                     format("%.*f");
@@ -213,7 +246,13 @@ class Fl_Spinner : public Fl_Group
                   }
                   input_.type(v); 
                 }
+  /**
+    Sets or returns the current value of the widget.
+    Before setting value to a non-integer value, the spinner 
+    type() should be changed to floating point. 
+  */
   double	value() const { return (value_); }
+  /** See double Fl_Spinner::value() const */
   void		value(double v) { value_ = v; update(); }
 };
 
diff --git a/FL/Fl_Text_Buffer.H b/FL/Fl_Text_Buffer.H
index aa4bbf704..5f8e4bd75 100644
--- a/FL/Fl_Text_Buffer.H
+++ b/FL/Fl_Text_Buffer.H
@@ -48,6 +48,10 @@ class FL_EXPORT Fl_Text_Selection {
     int end() { return mEnd; }
     int rect_start() { return mRectStart; }
     int rect_end() { return mRectEnd; }
+    /**
+       Returns a non-zero number if any text has been selected, or 0
+       if no text is selected.
+    */
     char selected() { return mSelected; }
     void selected(char b) { mSelected = b; }
     int includes(int pos, int lineStartPos, int dispIndex);
@@ -69,11 +73,26 @@ typedef void (*Fl_Text_Modify_Cb)(int pos, int nInserted, int nDeleted,
                                   void* cbArg);
 typedef void (*Fl_Text_Predelete_Cb)(int pos, int nDeleted, void* cbArg);
 
+/**
+  The Fl_Text_Buffer class is used by the Fl_Text_Display
+  and Fl_Text_Editor to manage complex text data and is based upon the
+  excellent NEdit text editor engine - see http://www.nedit.org/.
+*/
+/**
+  The Fl_Text_Buffer class is used by the 
+  Fl_Text_Display
+  and 
+  Fl_Text_Editor
+  to manage complex text data and is based upon the
+  excellent NEdit text editor engine - see
+  http://www.nedit.org/.
+*/
 class FL_EXPORT Fl_Text_Buffer {
   public:
     Fl_Text_Buffer(int requestedSize = 0);
     ~Fl_Text_Buffer();
 
+  /**    Returns the number of characters in the buffer.  */
     int length() { return mLength; }
     char* text();
     void text(const char* text);
@@ -81,6 +100,7 @@ class FL_EXPORT Fl_Text_Buffer {
     char character(int pos);
     char* text_in_rectangle(int start, int end, int rectStart, int rectEnd);
     void insert(int pos, const char* text);
+  /**    Appends the text string to the end of the buffer.  */
     void append(const char* t) { insert(length(), t); }
     void remove(int start, int end);
     void replace(int start, int end, const char *text);
@@ -88,11 +108,19 @@ class FL_EXPORT Fl_Text_Buffer {
     int undo(int *cp=0);
     void canUndo(char flag=1);
     int insertfile(const char *file, int pos, int buflen = 128*1024);
+    /**
+      Appends the named file to the end of the buffer. Returns 0 on 
+      success, non-zero on error (strerror() contains reason).  1 indicates 
+      open for read failed (no data loaded). 2 indicates error occurred 
+      while reading data (data was partially loaded).
+    */
     int appendfile(const char *file, int buflen = 128*1024)
       { return insertfile(file, length(), buflen); }
+    /** Loads a text file into the buffer */
     int loadfile(const char *file, int buflen = 128*1024)
       { select(0, length()); remove_selection(); return appendfile(file, buflen); }
     int outputfile(const char *file, int start, int end, int buflen = 128*1024);
+    /** Saves a text file from the current buffer */
     int savefile(const char *file, int buflen = 128*1024)
       { return outputfile(file, 0, length(), buflen); }
 
@@ -108,9 +136,11 @@ class FL_EXPORT Fl_Text_Buffer {
 
     void remove_rectangular(int start, int end, int rectStart, int rectEnd);
     void clear_rectangular(int start, int end, int rectStart, int rectEnd);
+    /** Gets the tab width.  */
     int tab_distance() { return mTabDist; }
     void tab_distance(int tabDist);
     void select(int start, int end);
+    /** Returns a non 0 value if text has been selected, 0 otherwise */
     int selected() { return mPrimary.selected(); }
     void unselect();
     void select_rectangular(int start, int end, int rectStart, int rectEnd);
@@ -123,7 +153,10 @@ class FL_EXPORT Fl_Text_Buffer {
     void remove_selection();
     void replace_selection(const char* text);
     void secondary_select(int start, int end);
+     /** Returns a non 0 value if text has been selected in the secondary
+       text selection, 0 otherwise */
     int secondary_selected() { return mSecondary.selected(); }
+     /** Clears any selection in the secondary text selection object. */
     void secondary_unselect();
 
     void secondary_select_rectangular(int start, int end, int rectStart,
@@ -137,6 +170,10 @@ class FL_EXPORT Fl_Text_Buffer {
     void remove_secondary_selection();
     void replace_secondary_selection(const char* text);
     void highlight(int start, int end);
+    /**
+      Returns the highlighted text. When you are done with the
+      text, free it using the free() function.
+    */
     int highlight() { return mHighlight.selected(); }
     void unhighlight();
     void highlight_rectangular(int start, int end, int rectStart, int rectEnd);
@@ -149,12 +186,21 @@ class FL_EXPORT Fl_Text_Buffer {
     void add_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void* cbArg);
     void remove_modify_callback(Fl_Text_Modify_Cb bufModifiedCB, void* cbArg);
 
+    /**
+       Calls all modify callbacks that have been registered using
+       the add_modify_callback()
+       method.
+    */
     void call_modify_callbacks() { call_modify_callbacks(0, 0, 0, 0, 0); }
 
     void add_predelete_callback(Fl_Text_Predelete_Cb bufPredelCB, void* cbArg);
     void remove_predelete_callback(Fl_Text_Predelete_Cb predelCB, void* cbArg);
 
-    void call_predelete_callbacks() { call_predelete_callbacks(0, 0); }
+   /**
+     Calls the stored pre-delete callback procedure(s) for this buffer to update 
+     the changed area(s) on the screen and any other listeners.
+   */
+   void call_predelete_callbacks() { call_predelete_callbacks(0, 0); }
 
     char* line_text(int pos);
     int line_start(int pos);
@@ -185,9 +231,13 @@ class FL_EXPORT Fl_Text_Buffer {
 
     int substitute_null_characters(char* string, int length);
     void unsubstitute_null_characters(char* string);
+    /**    Returns the current nul substitution character.  */
     char null_substitution_character() { return mNullSubsChar; }
+    /**    Returns the primary selection.  */
     Fl_Text_Selection* primary_selection() { return &mPrimary; }
+    /**    Returns the secondary selection.  */
     Fl_Text_Selection* secondary_selection() { return &mSecondary; }
+    /**    Returns the current highlight selection.  */
     Fl_Text_Selection* highlight_selection() { return &mHighlight; }
 
   protected:
diff --git a/FL/Fl_Text_Display.H b/FL/Fl_Text_Display.H
index 0c99b1366..f95d6ff81 100644
--- a/FL/Fl_Text_Display.H
+++ b/FL/Fl_Text_Display.H
@@ -36,6 +36,13 @@
 #include "Fl_Scrollbar.H"
 #include "Fl_Text_Buffer.H"
 
+/**
+  This is the FLTK text display widget. It allows the user to
+  view multiple lines of text and supports highlighting and
+  scrolling. The buffer that is displayed in the widget is managed
+  by the Fl_Text_Buffer
+  class.
+*/
 class FL_EXPORT Fl_Text_Display: public Fl_Group {
   public:
     enum {
@@ -76,13 +83,22 @@ class FL_EXPORT Fl_Text_Display: public Fl_Group {
 
     virtual int handle(int e);
     void buffer(Fl_Text_Buffer* buf);
+  /**
+      Sets or gets the current text buffer associated with the text widget.
+    Multiple text widgets can be associated with the same text buffer.
+  */
     void buffer(Fl_Text_Buffer& buf) { buffer(&buf); }
+    /**
+      Gets the current text buffer associated with the text widget.
+      Multiple text widgets can be associated with the same text buffer.
+    */
     Fl_Text_Buffer* buffer() { return mBuffer; }
     void redisplay_range(int start, int end);
     void scroll(int topLineNum, int horizOffset);
     void insert(const char* text);
     void overstrike(const char* text);
     void insert_position(int newPos);
+    /** Gets the position of the text insertion cursor for text display */
     int insert_position() { return mCursorPos; }
     int in_selection(int x, int y);
     void show_insert_position();
@@ -98,15 +114,24 @@ class FL_EXPORT Fl_Text_Display: public Fl_Group {
     void next_word(void);
     void previous_word(void);
     void show_cursor(int b = 1);
+    /**    Hides the text cursor */
     void hide_cursor() { show_cursor(0); }
     void cursor_style(int style);
+    /**    Sets or gets the text cursor color.  */
     Fl_Color cursor_color() const {return mCursor_color;}
+    /**    Sets or gets the text cursor color.  */
     void cursor_color(Fl_Color n) {mCursor_color = n;}
+    /**    Sets or gets the width/height of the scrollbars.  */
     int scrollbar_width() { return scrollbar_width_; }
-    Fl_Align scrollbar_align() { return scrollbar_align_; }
+    /**    Sets or gets the width/height of the scrollbars.  */
     void scrollbar_width(int W) { scrollbar_width_ = W; }
+    /**    Gets the scrollbar alignment type */
+    Fl_Align scrollbar_align() { return scrollbar_align_; }
+    /**    Sets the scrollbar alignment type */
     void scrollbar_align(Fl_Align a) { scrollbar_align_ = a; }
+    /**    Moves the insert position to the beginning of the current word.  */
     int word_start(int pos) { return buffer()->word_start(pos); }
+    /**    Moves the insert position to the end of the current word.  */
     int word_end(int pos) { return buffer()->word_end(pos); }
 
     
@@ -118,15 +143,24 @@ class FL_EXPORT Fl_Text_Display: public Fl_Group {
 
     int position_style(int lineStartPos, int lineLen, int lineIndex,
                        int dispIndex);
-
+    /** \todo FIXME : get set methods pointing on shortcut_ 
+     have no effects as shortcut_ is unused in this class and derived! */
     int shortcut() const {return shortcut_;}
+    /** \todo FIXME : get set methods pointing on shortcut_ 
+     have no effects as shortcut_ is unused in this class and derived! */
     void shortcut(int s) {shortcut_ = s;}
 
+    /**    Gets the default font used when drawing text in the widget.  */
     Fl_Font textfont() const {return textfont_;}
+    /**    Sets the default font used when drawing text in the widget.  */
     void textfont(Fl_Font s) {textfont_ = s;}
+    /**    Gets the default size of text in the widget.  */
     Fl_Fontsize textsize() const {return textsize_;}
+    /**    Sets the default size of text in the widget.  */
     void textsize(Fl_Fontsize s) {textsize_ = s;}
+    /**    Gets the default color of text in the widget.  */
     Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+    /**    Sets the default color of text in the widget.  */
     void textcolor(unsigned n) {textcolor_ = n;}
 
     int wrapped_column(int row, int column);
diff --git a/FL/Fl_Text_Editor.H b/FL/Fl_Text_Editor.H
index 8b1902746..3457acbf7 100644
--- a/FL/Fl_Text_Editor.H
+++ b/FL/Fl_Text_Editor.H
@@ -36,6 +36,13 @@
 // key will match in any state
 #define FL_TEXT_EDITOR_ANY_STATE  (-1L)
 
+/**
+  This is the FLTK text editor widget. It allows the user to
+  edit multiple lines of text and supports highlighting and
+  scrolling. The buffer that is displayed in the widget is managed
+  by the Fl_Text_Buffer
+  class.
+*/
 class FL_EXPORT Fl_Text_Editor : public Fl_Text_Display {
   public:
     typedef int (*Key_Func)(int key, Fl_Text_Editor* editor);
@@ -50,21 +57,36 @@ class FL_EXPORT Fl_Text_Editor : public Fl_Text_Display {
     Fl_Text_Editor(int X, int Y, int W, int H, const char* l = 0);
     ~Fl_Text_Editor() { remove_all_key_bindings(); }
     virtual int handle(int e);
+    /**
+	Sets the current insert mode; if non-zero, new text
+	is inserted before the current cursor position. Otherwise, new
+	text replaces text at the current cursor position.
+    */
     void insert_mode(int b) { insert_mode_ = b; }
+    /**
+	Gets the current insert mode; if non-zero, new text
+	is inserted before the current cursor position. Otherwise, new
+	text replaces text at the current cursor position.
+    */
     int insert_mode() { return insert_mode_; }
 
     void add_key_binding(int key, int state, Key_Func f, Key_Binding** list);
+    /** Adds a key of state "state" with the function "function" */
     void add_key_binding(int key, int state, Key_Func f)
       { add_key_binding(key, state, f, &key_bindings); }
     void remove_key_binding(int key, int state, Key_Binding** list);
+    /** Removes the key binding associated with the key "key" of state "state". */
     void remove_key_binding(int key, int state)
       { remove_key_binding(key, state, &key_bindings); }
     void remove_all_key_bindings(Key_Binding** list);
+    /** Removes all of the key bindings associated with the text editor or list. */
     void remove_all_key_bindings() { remove_all_key_bindings(&key_bindings); }
     void add_default_key_bindings(Key_Binding** list);
     Key_Func bound_key_function(int key, int state, Key_Binding* list);
+    /**  Returns the function associated with a key binding. */
     Key_Func bound_key_function(int key, int state)
       { return bound_key_function(key, state, key_bindings); }
+    /**  Sets the default key function for unassigned keys. */
     void default_key_function(Key_Func f) { default_key_function_ = f; }
 
     // functions for the built in default bindings
diff --git a/FL/Fl_Tiled_Image.H b/FL/Fl_Tiled_Image.H
index 72db8212b..8e4bb40bf 100644
--- a/FL/Fl_Tiled_Image.H
+++ b/FL/Fl_Tiled_Image.H
@@ -31,7 +31,14 @@
 #  include "Fl_Image.H"
 
 
-// Tiled image class. 
+/**
+  This class supports tiling of images
+  over a specified area. The source (tile) image is <B>not</B>
+  copied unless you call the color_average(),
+  desaturate(),
+  or inactive()
+  methods.
+*/
 class FL_EXPORT Fl_Tiled_Image : public Fl_Image {
   protected:
 
@@ -49,6 +56,7 @@ class FL_EXPORT Fl_Tiled_Image : public Fl_Image {
   virtual void desaturate();
   virtual void draw(int X, int Y, int W, int H, int cx, int cy);
   void draw(int X, int Y) { draw(X, Y, w(), h(), 0, 0); }
+  /** Gets The image that is shared */ 
   Fl_Image *image() { return image_; }
 };
 
diff --git a/FL/Fl_Toggle_Button.H b/FL/Fl_Toggle_Button.H
index 755c1cec3..790d7361b 100644
--- a/FL/Fl_Toggle_Button.H
+++ b/FL/Fl_Toggle_Button.H
@@ -30,8 +30,22 @@
 
 #include "Fl_Button.H"
 
+/**
+  The toggle button is a push button that needs to be clicked once 
+  to toggle on, and one more time to toggle off.
+  The Fl_Toggle_Button subclass displays the &quot;on&quot; state by
+  drawing a pushed-in button.</P>
+  <P>Buttons generate callbacks when they are clicked by the user.  You
+  control exactly when and how by changing the values for type()
+  and when().
+*/
 class Fl_Toggle_Button : public Fl_Button {
 public:
+  /**
+    Creates a new Fl_Toggle_Button widget using the given
+    position, size, and label string.
+    <P>The inherited destructor deletes the toggle button.
+  */
     Fl_Toggle_Button(int X,int Y,int W,int H,const char *l=0)
 	: Fl_Button(X,Y,W,H,l) {type(FL_TOGGLE_BUTTON);}
 };
diff --git a/FL/Fl_Tooltip.H b/FL/Fl_Tooltip.H
index 3e26656d5..13c985efc 100644
--- a/FL/Fl_Tooltip.H
+++ b/FL/Fl_Tooltip.H
@@ -31,29 +31,55 @@
 #include <FL/Fl.H>
 #include <FL/Fl_Widget.H>
 
+/**
+  The Fl_Tooltip class provides tooltip support for
+  all FLTK widgets.
+*/
 class FL_EXPORT Fl_Tooltip {
 public:
-  static float delay() { return delay_; }
+  /**    Gets the tooltip delay. The default delay is 1.0 seconds.  */
+    static float delay() { return delay_; }
+  /**    Sets the tooltip delay. The default delay is 1.0 seconds.  */
   static void delay(float f) { delay_ = f; }
+  /**
+    Gets or sets the tooltip hover delay, the delay between tooltips.
+    The default delay is 0.2 seconds.
+  */
   static float hoverdelay() { return hoverdelay_; }
+  /**
+    Gets or sets the tooltip hover delay, the delay between tooltips.
+    The default delay is 0.2 seconds.
+  */
   static void hoverdelay(float f) { hoverdelay_ = f; }
+  /**    Returns non-zero if tooltips are enabled.  */
   static int enabled() { return enabled_; }
+  /**    Enables tooltips on all widgets (or disables if <i>b</i> is false).  */
   static void enable(int b = 1) { enabled_ = b;}
+  /**    Same as enable(0), disables tooltips on all widgets.  */
   static void disable() { enabled_ = 0; }
   static void (*enter)(Fl_Widget* w);
   static void enter_area(Fl_Widget* w, int X, int Y, int W, int H, const char* tip);
   static void (*exit)(Fl_Widget *w);
+  /** Gets the current widget target */
   static Fl_Widget* current() {return widget_;}
   static void current(Fl_Widget*);
 
+  /**    Gets the typeface for the tooltip text.  */
   static Fl_Font font() { return font_; }
-  static Fl_Fontsize size() { return size_; }
+  /**    Sets the typeface for the tooltip text.  */
   static void font(Fl_Font i) { font_ = i; }
+  /**    Gets the size of the tooltip text.  */
+  static Fl_Fontsize size() { return size_; }
+  /**    Sets the size of the tooltip text.  */
   static void size(Fl_Fontsize s) { size_ = s; }
-  static void color(unsigned c) { color_ = c; }
+  /** Gets the background color for tooltips. The default background color is a pale yellow.  */
   static Fl_Color color() { return (Fl_Color)color_; }
-  static void textcolor(unsigned c) { textcolor_ = c; }
+  /** Sets the background color for tooltips. The default background color is a pale yellow.  */
+  static void color(unsigned c) { color_ = c; }
+  /** Gets the color of the text in the tooltip. The default is  black. */
   static Fl_Color textcolor() { return (Fl_Color)textcolor_; }
+  /** Sets the color of the text in the tooltip. The default is  black. */
+  static void textcolor(unsigned c) { textcolor_ = c; }
 
   // These should not be public, but Fl_Widget::tooltip() needs them...
   static void enter_(Fl_Widget* w);
diff --git a/FL/Fl_Wizard.H b/FL/Fl_Wizard.H
index 1a37d3fb4..bec0b82c3 100644
--- a/FL/Fl_Wizard.H
+++ b/FL/Fl_Wizard.H
@@ -35,10 +35,15 @@
 #  include <FL/Fl_Group.H>
 
 
-//
-// Fl_Wizard class...
-//
+/**
+    This widget is based off the Fl_Tabs
+    widget, but instead of displaying tabs it only changes "tabs" under
+    program control. Its primary purpose is to support "wizards" that
+    step a user through configuration or troubleshooting tasks.
 
+    <P>As with Fl_Tabs, wizard panes are composed of child (usually
+    Fl_Group) widgets. Navigation buttons must be added separately.
+*/
 class FL_EXPORT Fl_Wizard : public Fl_Group
 {
   Fl_Widget *value_;