diff options
| -rw-r--r-- | FL/Fl_Widget.H | 22 | ||||
| -rw-r--r-- | src/Fl_Widget.cxx | 21 |
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; |