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

FL/Fl_Button.H

@@ -3,10 +3,10 @@
 //
 // Button header file 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
@@ -27,7 +27,7 @@
 #endif
 
 // values for type()
-#define FL_NORMAL_BUTTON	0   /**< value() will be set to 1 during the press of the button and 
+#define FL_NORMAL_BUTTON	0   /**< value() will be set to 1 during the press of the button and
                                          reverts back to 0 when the button is released */
 #define FL_TOGGLE_BUTTON	1   ///< value() toggles between 0 and 1 at every click of the button
 #define FL_RADIO_BUTTON		(FL_RESERVED_TYPE+2) /**< is set to 1 at button press, and all other
@@ -42,7 +42,7 @@ class Fl_Widget_Tracker;
 /**
   \class Fl_Button
   \brief Buttons generate callbacks when they are clicked by the user.
-  
+
   You control exactly when and how by changing the values for type() and
   when().  Buttons can also generate callbacks in response to \c FL_SHORTCUT
   events.  The button can either have an explicit shortcut(int s) value or a
@@ -72,6 +72,7 @@ class Fl_Widget_Tracker;
          (when the user pushes and releases the button, and as the mouse is
 	 dragged around in and out of the button).
 */
+
 class FL_EXPORT Fl_Button : public Fl_Widget {
 
   int shortcut_;
@@ -84,7 +85,7 @@ protected:
   static Fl_Widget_Tracker *key_release_tracker;
   static void key_release_timeout(void*);
   void simulate_key_action();
-  
+
   virtual void draw();
 
 public:
@@ -150,6 +151,10 @@ public:
   /**
     Sets the down box type. The default value of 0 causes FLTK to figure out
     the correct matching down version of box().
+
+    Some derived classes (e.g. Fl_Round_Button and Fl_Light_Button use
+    down_box() for special purposes. See docs of these classes.
+
     \param[in] b down box type
    */
   void down_box(Fl_Boxtype b) {down_box_ = b;}

FL/Fl_Check_Button.H

@@ -3,10 +3,10 @@
 //
 // Check button header file 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
@@ -16,29 +16,17 @@
 //     http://www.fltk.org/str.php
 //
 
-/* \file
-   Fl_Check_Button widget . */
-
 #ifndef Fl_Check_Button_H
 #define Fl_Check_Button_H
 
 #include "Fl_Light_Button.H"
 
-/**
+/*
-  \class Fl_Check_Button
+  class: Fl_Check_Button.
-  \brief A button with an "checkmark" to show its status.
 
-  \image html Fl_Check_Button.png
+  A button with a "checkmark" to show its status.
-  \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.
-  
-  \todo Refactor Fl_Check_Button doxygen comments (add color() info etc?)
-  \todo Generate Fl_Check_Button.gif with visible checkmark.
- */
 class FL_EXPORT Fl_Check_Button : public Fl_Light_Button {
 public:
   Fl_Check_Button(int X, int Y, int W, int H, const char *L = 0);

FL/Fl_Radio_Button.H

@@ -3,10 +3,10 @@
 //
 // Radio button header file 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

FL/Fl_Radio_Light_Button.H

@@ -3,10 +3,10 @@
 //
 // Radio light button header file 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

FL/Fl_Radio_Round_Button.H

@@ -3,10 +3,10 @@
 //
 // Radio round button header file 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

FL/Fl_Round_Button.H

@@ -3,10 +3,10 @@
 //
 // Round button header file 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
@@ -16,9 +16,6 @@
 //     http://www.fltk.org/str.php
 //
 
-/* \file
-   Fl_Round_Button widget . */
-
 #ifndef Fl_Round_Button_H
 #define Fl_Round_Button_H
 

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.
 
-Fl_Toggle_Button::Fl_Toggle_Button(int X,int Y,int W,int H,const char *l)
+  The Button type() is set to FL_TOGGLE_BUTTON.
-: 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);
 }

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
+  \class Fl_Check_Button
-// diamond is smaller than the widget size and can be surchecked by
+  \brief A button with a "checkmark" to show its status.
-// another box type, for compatibility with Forms.
+
+  \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
+  Creates a new Fl_Check_Button widget using the given position, size, and label string.
-  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
  */

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
+  Creates a new Fl_Round_Button widget using the given position, size, and label string.
-  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_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_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);
 }