1 files changed, 61 insertions, 4 deletions

diff --git a/FL/Fl_Choice.H b/FL/Fl_Choice.H
index cf9beae35..f3cfd8beb 100644
--- a/FL/Fl_Choice.H
+++ b/FL/Fl_Choice.H
@@ -3,7 +3,7 @@
 //
 // Choice 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
@@ -30,15 +30,72 @@
 
 #include "Fl_Menu_.H"
 
+/**
+  \class Fl_Choice
+  \brief A button that is used to pop up a menu.
+
+  This is a button that, when pushed, pops up a menu (or hierarchy of menus)
+  defined by an array of Fl_Menu_Item objects.
+  Motif calls this an OptionButton.
+
+  The only difference between this and a Fl_Menu_Button is that the name of
+  the most recent chosen menu item is displayed inside the box, while the
+  label is displayed outside the box. However, since the use of this is most
+  often to control a single variable rather than do individual callbacks,
+  some of the Fl_Menu_Button methods are redescribed here in those terms.
+
+  When the user picks an item off the menu the value() is set to that item
+  and then the item's callback is done with the menu_button as the
+  \c Fl_Widget* argument. If the item does not have a callback the
+  menu_button's callback is done instead.
+
+  All three mouse buttons pop up the menu. The Forms behavior of the first
+  two buttons to increment/decrement the choice is not implemented.  This
+  could be added with a subclass, however.
+
+  The menu will also pop up in response to shortcuts indicated by putting
+  a '\&' character in the label().  See Fl_Button::shortcut(int s) for a
+  description of this.
+
+  Typing the shortcut() of any of the items will do exactly the same as when
+  you pick the item with the mouse.  The '\&' character in item names are
+  only looked at when the menu is popped up, however.
+
+  \image html choice.gif
+
+  \todo Refactor the doxygen comments for Fl_Choice changed() documentation.
+
+  \li <tt>int Fl_Widget::changed() const</tt>
+      This value is true the user picks a different value. <em>It is turned
+      off by value() and just before doing a callback (the callback can turn
+      it back on if desired).</em>
+  \li <tt>void Fl_Widget::set_changed()</tt>
+      This method sets the changed() flag.
+  \li <tt>void Fl_Widget::clear_changed()</tt>
+      This method clears the changed() flag.
+  \li <tt>Fl_Boxtype Fl_Choice::down_box() const</tt>
+      Gets the current down box, which is used when the menu is popped up.
+      The default down box type is \c FL_DOWN_BOX.
+  \li <tt>void Fl_Choice::down_box(Fl_Boxtype b)</tt>
+      Sets the current down box type to \p b.
+ */
 class FL_EXPORT Fl_Choice : public Fl_Menu_ {
 protected:
   void draw();
 public:
   int handle(int);
-  Fl_Choice(int,int,int,int,const char * = 0);
-  int value(const Fl_Menu_Item*);
-  int value(int i);
+
+  Fl_Choice(int X, int Y, int W, int H, const char *L = 0);
+
+  /**
+    Gets the index of the last item chosen by the user.
+    The index is zero initially.
+   */
   int value() const {return Fl_Menu_::value();}
+
+  int value(int v);
+
+  int value(const Fl_Menu_Item* v);
 };
 
 #endif