Documentation clarification for all menu oriented widgets

regarding callbacks.



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

5 files changed, 80 insertions, 15 deletions

diff --git a/FL/Fl_Choice.H b/FL/Fl_Choice.H
index 8146f9476..1f93fb40a 100644
--- a/FL/Fl_Choice.H
+++ b/FL/Fl_Choice.H
@@ -38,10 +38,17 @@
   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.
+  When the user clicks a menu item, value() is set to that item
+  and then:
+
+      - The item's callback is done if one has been set; the
+        Fl_Choice is passed as the Fl_Widget* argument, 
+        along with any userdata configured for the callback.
+
+      - If the item does not have a callback, the Fl_Choice widget's
+        callback is done instead, along with any userdata configured
+        for it.  The callback can determine which item was picked using
+        value(), mvalue(), item_pathname(), etc.
 
   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
diff --git a/FL/Fl_Input_Choice.H b/FL/Fl_Input_Choice.H
index fc307a9fe..efcbf8e9a 100644
--- a/FL/Fl_Input_Choice.H
+++ b/FL/Fl_Input_Choice.H
@@ -43,10 +43,54 @@
   The user can either type into the input area, or use the
   menu button chooser on the right to choose an item which loads
   the input area with the selected text.
-  <P>
+
   The application can directly access both the internal Fl_Input 
   and Fl_Menu_Button widgets respectively using the input() and menubutton()
   accessor methods.
+
+  The default behavior is to invoke the Fl_Input_Choice::callback()
+  if the user changes the input field's contents, either by typing,
+  pasting, or clicking a different item in the choice menu.
+  
+  The callback can determine if an item was picked vs. typing
+  into the input field by checking the value of menubutton()->changed(),
+  which will be:
+
+      - 1: the user picked a different item in the choice menu
+      - 0: the user typed or pasted directly into the input field
+
+  Example use:
+  \code
+  #include <stdio.h>
+  #include <FL/Fl.H>
+  #include <FL/Fl_Double_Window.H>
+  #include <FL/Fl_Input_Choice.H>
+  void choice_cb(Fl_Widget *w, void *userdata) {
+    // Show info about the picked item
+    Fl_Input_Choice *choice = (Fl_Input_Choice*)w;
+    const Fl_Menu_Item *item = choice->menubutton()->mvalue();
+    printf("*** Choice Callback:\n");
+    printf("    item label()='%s'\n", item ? item->label() : "(No item)");
+    printf("    item value()=%d\n", choice->menubutton()->value());
+    printf("    input value()='%s'\n", choice->input()->value());
+    printf("    The user %s\n", choice->menubutton()->changed()
+                                    ? "picked a menu item"
+                                    : "typed text");
+  }
+  int main() {
+    Fl_Double_Window win(200,100,"Input Choice");
+    win.begin();
+      Fl_Input_Choice choice(10,10,100,30);
+      choice.callback(choice_cb, 0);
+      choice.add("Red");
+      choice.add("Orange");
+      choice.add("Yellow");
+      //choice.value("Red");    // uncomment to make "Red" default
+    win.end();
+    win.show();
+    return Fl::run();
+  }
+  \endcode
 */
 class FL_EXPORT Fl_Input_Choice : public Fl_Group {
   // Private class to handle slightly 'special' behavior of menu button
@@ -66,6 +110,7 @@ class FL_EXPORT Fl_Input_Choice : public Fl_Group {
   Fl_Input *inp_;
   InputMenuButton *menu_;
 
+  // note: this is used by the Fl_Input_Choice ctor defined in Fl_Group.
   static void menu_cb(Fl_Widget*, void *data) { 
     Fl_Input_Choice *o=(Fl_Input_Choice *)data;
     Fl_Widget_Tracker wp(o);
@@ -95,6 +140,7 @@ class FL_EXPORT Fl_Input_Choice : public Fl_Group {
     }
   }
 
+  // note: this is used by the Fl_Input_Choice ctor defined in Fl_Group.
   static void inp_cb(Fl_Widget*, void *data) { 
     Fl_Input_Choice *o=(Fl_Input_Choice *)data;
     Fl_Widget_Tracker wp(o);
diff --git a/FL/Fl_Menu_.H b/FL/Fl_Menu_.H
index b6a4e1577..7eb37cda7 100644
--- a/FL/Fl_Menu_.H
+++ b/FL/Fl_Menu_.H
@@ -36,7 +36,8 @@
   array may either be supplied directly by the user program, or it may
   be "private": a dynamically allocated array managed by the Fl_Menu_.
 
-  When the user clicks a menu item:
+  When the user clicks a menu item, value() is set to that item
+  and then:
 
       - If the Fl_Menu_Item has a callback set, that callback
         is invoked with any userdata configured for it.
diff --git a/FL/Fl_Menu_Bar.H b/FL/Fl_Menu_Bar.H
index 45696a98d..98127e33c 100644
--- a/FL/Fl_Menu_Bar.H
+++ b/FL/Fl_Menu_Bar.H
@@ -41,14 +41,17 @@
   submenu, then it acts like a "button" in the menubar.  Clicking on it
   will pick it. </P>
 
-  When the user picks an item in the menu:
+  When the user clicks a menu item, value() is set to that item
+  and then:
 
-      - The item's callback is done; the menubar is passed as the
-        Fl_Widget* argument, along with any userdata configured
-	for the callback.
+      - The item's callback is done if one has been set; the
+        Fl_Menu_Bar is passed as the Fl_Widget* argument, 
+        along with any userdata configured for the callback.
 
-      - If the item does not have a callback, the menubar's callback
+      - If the item does not have a callback, the Fl_Menu_Bar's callback
         is done instead, along with any userdata configured for the callback.
+        The callback can determine which item was picked using
+        value(), mvalue(), item_pathname(), etc.
 
   <P>Submenus will also pop up in response to shortcuts indicated by
   putting a '&' character in the name field of the menu item. If you put a
diff --git a/FL/Fl_Menu_Button.H b/FL/Fl_Menu_Button.H
index 6a556aeb3..7f18eab66 100644
--- a/FL/Fl_Menu_Button.H
+++ b/FL/Fl_Menu_Button.H
@@ -42,10 +42,18 @@
   callbacks exactly the same as when you pick the item with the mouse.
   The '&' character in menu item names are only looked at when the menu is
   popped up, however. </P>
-  <P>When the user picks an item off the menu, the item's callback is
-  done with the menu_button as the Fl_Widget* argument.  If the
-  item does not have a callback the menu_button's callback is done
-  instead.
+
+  When the user clicks a menu item, value() is set to that item
+  and then:
+
+      - The item's callback is done if one has been set; the
+        Fl_Menu_Button is passed as the Fl_Widget* argument, 
+        along with any userdata configured for the callback.
+
+      - If the item does not have a callback, the Fl_Menu_Button's callback
+        is done instead, along with any userdata configured for it.
+        The callback can determine which item was picked using
+        value(), mvalue(), item_pathname(), etc.
 */
 class FL_EXPORT Fl_Menu_Button : public Fl_Menu_ {
 protected: