Documentation updates on callbacks and Fl::readqueue().

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

2 files changed, 34 insertions, 9 deletions

diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index d3b4e1516..0738e6638 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -599,6 +599,8 @@ public:
   void user_data(void* v) {user_data_ = v;}
 
   /** Gets the current user data (long) argument that is passed to the callback function.
+      \todo The user data value must be implemented using \em intptr_t or similar
+      to avoid 64-bit machine incompatibilities.
    */
   long argument() const {return (long)(fl_intptr_t)user_data_;}
 
@@ -835,12 +837,20 @@ public:
    */
   unsigned int  visible_focus() { return flags_ & VISIBLE_FOCUS; }
 
-  /** Sets the default callback for all widgets.
-      Sets the default callback, which puts a pointer to the widget on the queue 
-      returned by Fl::readqueue(). You may want to call this from your own callback.
-      \param[in] cb the new callback
-      \param[in] d user data associated with that callback
-      \see callback(), do_callback(), Fl::readqueue()
+  /** The default callback for all widgets that don't set a callback.
+
+    This callback function puts a pointer to the widget on the queue
+    returned by Fl::readqueue().
+
+    Relying on the default callback and reading the callback queue with
+    Fl::readqueue() is not recommended. If you need a callback, you should
+    set one with Fl_Widget::callback(Fl_Callback *cb, void *data)
+    or one of its variants.
+
+    \param[in] cb the widget given to the callback
+    \param[in] d user data associated with that callback
+
+    \see callback(), do_callback(), Fl::readqueue()
    */
   static void default_callback(Fl_Widget *cb, void *d);
 
diff --git a/src/Fl_Widget.cxx b/src/Fl_Widget.cxx
index 924cc3688..3982055b9 100644
--- a/src/Fl_Widget.cxx
+++ b/src/Fl_Widget.cxx
@@ -54,9 +54,24 @@ void Fl_Widget::default_callback(Fl_Widget *o, void * /*v*/) {
   }
 }
 /**
-    All Fl_Widgets that don't have a callback defined use a
-    default callback that puts a pointer to the widget in this queue,
-    and this method reads the oldest widget out of this queue.
+    Reads the default callback queue and returns the first widget.
+
+    All Fl_Widgets that don't have a callback defined use the default
+    callback \p static Fl_Widget::default_callback() that puts a pointer
+    to the widget in a queue. This method reads the oldest widget out
+    of this queue.
+
+    The queue (FIFO) is limited (currently 20 items). If the queue
+    overflows, the oldest entry (Fl_Widget *) is discarded.
+
+    Relying on the default callback and reading the callback queue with
+    Fl::readqueue() is not recommended. If you need a callback, you should
+    set one with Fl_Widget::callback(Fl_Callback *cb, void *data)
+    or one of its variants.
+
+    \see Fl_Widget::callback()
+    \see Fl_Widget::callback(Fl_Callback *cb, void *data)
+    \see Fl_Widget::default_callback()
 */
 Fl_Widget *Fl::readqueue() {
   if (obj_tail==obj_head) return 0;