applied Duncan Gibson's documentation patch (WP3).

Docs look good, compiles okay.


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

1 files changed, 95 insertions, 4 deletions

diff --git a/FL/Fl_Button.H b/FL/Fl_Button.H
index 460b851b0..dc594c1e1 100644
--- a/FL/Fl_Button.H
+++ b/FL/Fl_Button.H
@@ -3,7 +3,7 @@
 //
 // Button header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -40,6 +40,40 @@
 
 extern FL_EXPORT int fl_old_shortcut(const char*);
 
+/**
+  \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
+  letter shortcut can be indicated in the label() with an '\&' character
+  before it.  For the label shortcut it does not matter if \e Alt is held
+  down, but if you have an input field in the same window, the user will have
+  to hold down the \e Alt key so that the input field does not eat the event
+  first as an \c FL_KEYBOARD event.
+
+  \todo Refactor the doxygen comments for Fl_Button type() documentation.
+
+  For an Fl_Button object, the type() call returns one of:
+  \li \c FL_NORMAL_BUTTON (0): value() remains unchanged after button press.
+  \li \c FL_TOGGLE_BUTTON: value() is inverted after button press.
+  \li \c FL_RADIO_BUTTON: value() is set to 1 after button press, and all other
+         buttons in the current group with <tt>type() == FL_RADIO_BUTTON</tt>
+	 are set to zero.
+
+  \todo Refactor the doxygen comments for Fl_Button when() documentation.
+
+  For an Fl_Button object, the following when() values are useful, the default
+  being \c FL_WHEN_RELEASE:
+  \li \c 0: The callback is not done, instead changed() is turned on.
+  \li \c FL_WHEN_RELEASE: The callback is done after the user successfully
+         clicks the button, or when a shortcut is typed.
+  \li \c FL_WHEN_CHANGED: The callback is done each time the value() changes
+         (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_;
@@ -54,20 +88,77 @@ protected:
 public:
 
   virtual int handle(int);
-  Fl_Button(int,int,int,int,const char * = 0);
-  int value(int);
+
+  Fl_Button(int X, int Y, int W, int H, const char *L = 0);
+
+  int value(int v);
+
+  /**
+    Returns the current value of the button (0 or 1).
+   */
   char value() const {return value_;}
+
+  /**
+    Same as \c value(1).
+    \see value(int v)
+   */
   int set() {return value(1);}
+
+  /**
+    Same as \c value(0).
+    \see value(int v)
+   */
   int clear() {return value(0);}
+
   void setonly(); // this should only be called on FL_RADIO_BUTTONs
+
+  /**
+    Returns the current shortcut key for the button.
+    \retval int
+   */
   int shortcut() const {return shortcut_;}
+
+  /**
+    Sets the shortcut key to \c s.
+    Setting this overrides the use of '\&' in the label().
+    The value is a bitwise OR of a key and a set of shift flags, for example:
+    <tt>FL_ALT | 'a'</tt>, or
+    <tt>FL_ALT | (FL_F + 10)</tt>, or just
+    <tt>'a'</tt>.
+    A value of 0 disables the shortcut.
+
+    The key can be any value returned by Fl::event_key(), but will usually be
+    an ASCII letter.  Use a lower-case letter unless you require the shift key
+    to be held down.
+
+    The shift flags can be any set of values accepted by Fl::event_state().
+    If the bit is on, that shift key must be pushed.  Meta, Alt, Ctrl, and
+    Shift must be off if they are not in the shift flags (zero for the other
+    bits indicates a "don't care" setting).
+    \param[in] s bitwise OR of key and shift flags
+   */
   void shortcut(int s) {shortcut_ = s;}
+
+  /**
+    Returns the current down box type, which is drawn when value() is non-zero.
+    \retval Fl_Boxtype
+   */
   Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;}
+
+  /**
+    Sets the down box type. The default value of 0 causes FLTK to figure out
+    the correct matching down version of box().
+    \param[in] b down box type
+   */
   void down_box(Fl_Boxtype b) {down_box_ = b;}
 
-  // back compatibility:
+  /// (for backwards compatibility)
   void shortcut(const char *s) {shortcut(fl_old_shortcut(s));}
+
+  /// (for backwards compatibility)
   Fl_Color down_color() const {return selection_color();}
+
+  /// (for backwards compatibility)
   void down_color(unsigned c) {selection_color(c);}
 };