Update docs related to buttons and update Fl_Check_Button.png.

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

3 files changed, 89 insertions, 23 deletions

diff --git a/src/Fl_Button.cxx b/src/Fl_Button.cxx
index da851d205..5207234bd 100644
--- a/src/Fl_Button.cxx
+++ b/src/Fl_Button.cxx
@@ -3,10 +3,10 @@
 //
 // Button widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2014 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
-// the file "COPYING" which should have been included with this file.  If this
+// the file "COPYING" which should have been included with this file. If this
 // file is missing or damaged, see the license at:
 //
 //     http://www.fltk.org/COPYING.php
@@ -126,7 +126,7 @@ int Fl_Button::handle(int event) {
     return 1;
   case FL_SHORTCUT:
     if (!(shortcut() ?
-	  Fl::test_shortcut(shortcut()) : test_shortcut())) return 0;    
+	  Fl::test_shortcut(shortcut()) : test_shortcut())) return 0;
     if (Fl::visible_focus() && handle(FL_FOCUS)) Fl::focus(this);
     goto triggered_by_keyboard;
   case FL_FOCUS :
@@ -175,7 +175,7 @@ void Fl_Button::simulate_key_action()
     Fl::remove_timeout(key_release_timeout, key_release_tracker);
     key_release_timeout(key_release_tracker);
   }
-  value(1); 
+  value(1);
   redraw();
   key_release_tracker = new Fl_Widget_Tracker(this);
   Fl::add_timeout(0.15, key_release_timeout, key_release_tracker);
@@ -186,7 +186,7 @@ void Fl_Button::key_release_timeout(void *d)
   Fl_Widget_Tracker *wt = (Fl_Widget_Tracker*)d;
   if (!wt)
     return;
-  if (wt==key_release_tracker) 
+  if (wt==key_release_tracker)
     key_release_tracker = 0L;
   Fl_Button *btn = (Fl_Button*)wt->widget();
   if (btn) {
@@ -197,7 +197,16 @@ void Fl_Button::key_release_timeout(void *d)
 }
 
 /**
-  The constructor creates the button using the given position, size and label.
+  The constructor creates the button using the given position, size, and label.
+
+  The default box type is box(FL_UP_BOX).
+
+  You can control how the button is drawn when ON by setting down_box().
+  The default is FL_NO_BOX (0) which will select an appropriate box type
+  using the normal (OFF) box type by using fl_down(box()).
+
+  Derived classes may handle this differently.
+
   \param[in] X, Y, W, H position and size of the widget
   \param[in] L widget label, default is no label
  */
@@ -210,15 +219,29 @@ Fl_Button::Fl_Button(int X, int Y, int W, int H, const char *L)
   set_flag(SHORTCUT_LABEL);
 }
 
+/**
+  The constructor creates the button using the given position, size, and label.
+
+  The Button type() is set to FL_RADIO_BUTTON.
 
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
 Fl_Radio_Button::Fl_Radio_Button(int X,int Y,int W,int H,const char *L)
 : Fl_Button(X, Y, W, H, L) {
   type(FL_RADIO_BUTTON);
 }
 
+/**
+  The constructor creates the button using the given position, size, and label.
+
+  The Button type() is set to FL_TOGGLE_BUTTON.
 
-Fl_Toggle_Button::Fl_Toggle_Button(int X,int Y,int W,int H,const char *l)
-: Fl_Button(X,Y,W,H,l) 
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Toggle_Button::Fl_Toggle_Button(int X,int Y,int W,int H,const char *L)
+: Fl_Button(X,Y,W,H,L)
 {
   type(FL_TOGGLE_BUTTON);
 }
diff --git a/src/Fl_Check_Button.cxx b/src/Fl_Check_Button.cxx
index 63dabddb8..56ef3160b 100644
--- a/src/Fl_Check_Button.cxx
+++ b/src/Fl_Check_Button.cxx
@@ -3,10 +3,10 @@
 //
 // Check button widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2014 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
-// the file "COPYING" which should have been included with this file.  If this
+// the file "COPYING" which should have been included with this file. If this
 // file is missing or damaged, see the license at:
 //
 //     http://www.fltk.org/COPYING.php
@@ -19,14 +19,32 @@
 #include <FL/Fl.H>
 #include <FL/Fl_Check_Button.H>
 
-// TODO Correct incorrect Fl_Check_Button comments.
-// A subclass of Fl_Button that always draws as a diamond box.  This
-// diamond is smaller than the widget size and can be surchecked by
-// another box type, for compatibility with Forms.
+/**
+  \class Fl_Check_Button
+  \brief A button with a "checkmark" to show its status.
+
+  \image html Fl_Check_Button.png
+  \image latex Fl_Check_Button.png  "Fl_Check_Button" width=4cm
+
+  Buttons generate callbacks when they are clicked by the user. You control
+  exactly when and how by changing the values for type() and when().
+
+  The Fl_Check_Button subclass displays its "ON" state by showing a "checkmark"
+  rather than drawing itself pushed in.
+ */
 
 /**
-  Creates a new Fl_Check_Button widget using the given position, size and
-  label string.
+  Creates a new Fl_Check_Button widget using the given position, size, and label string.
+
+  The default box type is FL_NO_BOX, which draws the label w/o a box
+  right of the checkmark.
+
+  The selection_color() sets the color of the checkmark.
+  Default is FL_FOREGROUND_COLOR (usually black).
+
+  You can use down_box() to change the box type of the checkmark.
+  Default is FL_DOWN_BOX.
+
   \param[in] X, Y, W, H position and size of the widget
   \param[in] L widget label, default is no label
  */
diff --git a/src/Fl_Round_Button.cxx b/src/Fl_Round_Button.cxx
index d3ba77e22..0f66396cd 100644
--- a/src/Fl_Round_Button.cxx
+++ b/src/Fl_Round_Button.cxx
@@ -3,10 +3,10 @@
 //
 // Round button for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2014 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
-// the file "COPYING" which should have been included with this file.  If this
+// the file "COPYING" which should have been included with this file. If this
 // file is missing or damaged, see the license at:
 //
 //     http://www.fltk.org/COPYING.php
@@ -25,19 +25,44 @@
 #include <FL/Fl_Radio_Round_Button.H>
 
 /**
-  Creates a new Fl_Round_Button widget using the given
-  position, size, and label string.
+  Creates a new Fl_Round_Button widget using the given position, size, and label string.
+
+  \image html Fl_Round_Button.png
+  \image latex Fl_Round_Button.png " Fl_Round_Button" width=4cm
+
+  The Fl_Round_Button subclass displays the "ON" state by
+  turning on a light, rather than drawing pushed in.
+
+  The default box type is FL_NO_BOX, which draws the label w/o a box
+  right of the checkmark.
+
+  The shape of the "light" is set with down_box() and its default
+  value is FL_ROUND_DOWN_BOX.
+
+  The color of the light when on is controlled with selection_color(),
+  which defaults to FL_FOREGROUND_COLOR (usually black).
+
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
 */
-Fl_Round_Button::Fl_Round_Button(int X,int Y,int W,int H, const char *l)
-: Fl_Light_Button(X,Y,W,H,l) {
+Fl_Round_Button::Fl_Round_Button(int X,int Y,int W,int H, const char *L)
+: Fl_Light_Button(X,Y,W,H,L) {
   box(FL_NO_BOX);
   down_box(FL_ROUND_DOWN_BOX);
   selection_color(FL_FOREGROUND_COLOR);
 }
 
+/**
+  Creates a new Fl_Radio_Button widget using the given position, size, and label string.
+
+  The button type() is set to FL_RADIO_BUTTON.
+
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+*/
 
 Fl_Radio_Round_Button::Fl_Radio_Round_Button(int X,int Y,int W,int H,const char *L)
-: Fl_Round_Button(X,Y,W,H,L) 
+: Fl_Round_Button(X,Y,W,H,L)
 {
   type(FL_RADIO_BUTTON);
 }