Added comments about removing widgets from their parent group or window

before deleting them with delete or Fl_Widget::delete_widget(). This is not
necessary any more, but it was necessary in FLTK 1.1.


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

1 files changed, 14 insertions, 4 deletions

diff --git a/src/Fl.cxx b/src/Fl.cxx
index 663e38630..1c39c0323 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -1493,13 +1493,23 @@ static Fl_Widget	**dwidgets = 0;
 
 /** 
   Schedules a widget for deletion at the next call to the event loop.
-  Use this method to delete a widget inside a callback function. 
-  To avoid early deletion of widgets, this function
-  should be called toward the end of a callback and only after any call 
-  to the event loop (Fl:wait(), Fl::flush(), fl_ask(), etc).
+  Use this method to delete a widget inside a callback function.
+
+  To avoid early deletion of widgets, this function should be called
+  toward the end of a callback and only after any call to the event
+  loop (Fl::wait(), Fl::flush(), Fl::check(), fl_ask(), etc.).
 
   When deleting groups or windows, you must only delete the group or
   window widget and not the individual child widgets.
+
+  \since FLTK 1.3 it is not necessary to remove widgets from their parent
+  groups or windows before calling this, because it will be done in the
+  widget's destructor, but it is not a failure to do this nevertheless.
+
+  \note In FLTK 1.1 you \b must remove widgets from their parent group
+  (or window) before deleting them.
+
+  \see Fl_Widget::~Fl_Widget()
 */
 void Fl::delete_widget(Fl_Widget *wi) {
   if (!wi) return;