renamed class Fl_Watch to Fl_Widget_Tracker, as discussed in fltk.development.

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

5 files changed, 38 insertions, 34 deletions

diff --git a/CHANGES b/CHANGES
index 12a218610..bf9806fa9 100644
--- a/CHANGES
+++ b/CHANGES
@@ -3,7 +3,7 @@ CHANGES IN FLTK 1.3.0
 	- Added Fl_Scroll::bbox() documentation (STR #1893)
 	- Removed an XForms compatibility "feature" that prevented the down
 	  array of Fl_Menu_Button from drawing (STR #2141).
-	- New helper class Fl_Watch to simplify safe handling of widget
+	- New class Fl_Widget_Tracker to simplify safe handling of widget
 	  deletion in callbacks. This is used in Fl_Widget::do_callback()
 	  to prevent accessing widgets after deletion in the callback.
 	- Fl_Help_View handles HTML2 font color specification (STR #890) 
diff --git a/FL/Fl.H b/FL/Fl.H
index 2e5815687..476e775fb 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -856,7 +856,7 @@ public:
     callbacks.
 
     The other functions are intended for internal use. The preferred
-    way to use them is by using the helper class Fl_Watch.
+    way to use them is by using the helper class Fl_Widget_Tracker.
 
     The following is to show how it works ...
 
@@ -869,11 +869,11 @@ public:
 	- Fl::watch_widget_pointer() adds a widget pointer to the watch list
 	- Fl::release_widget_pointer() removes a widget pointer from the watch list
 	- Fl::clear_widget_pointer() clears a widget pointer \e in the watch list
-      -# the class Fl_Watch:
+      -# the class Fl_Widget_Tracker:
 	- the constructor calls Fl::watch_widget_pointer()
 	- the destructor calls Fl::release_widget_pointer()
 	- the access methods can be used to test, if a widget has been deleted
-	  \see Fl_Watch.
+	  \see Fl_Widget_Tracker.
 
    @{ */
   // Widget deletion:
@@ -936,7 +936,7 @@ public:
 /**
   This class should be used to control safe widget deletion.
 
-  You can use an Fl_Watch object to watch another widget, if you
+  You can use an Fl_Widget_Tracker object to watch another widget, if you
   need to know, if this widget has been deleted during a callback.
 
   This simplifies the use of the "safe widget deletion" methods
@@ -949,7 +949,7 @@ public:
   scope is left. This ensures that no stale widget pointers are
   left in the widget watch list (see example below).
   
-  You can also create Fl_Watch objects with \e \b new, but then it
+  You can also create Fl_Widget_Tracker objects with \e \b new, but then it
   is your responsibility to delete the object (and thus remove the
   widget pointer from the watch list) when it is not needed any more.
 
@@ -959,28 +959,28 @@ public:
     int MyClass::handle (int event) {
 
       if (...) {
-	Fl_Watch wp(this);	// watch myself
-	do_callback();		// call the callback
+	Fl_Widget_Tracker wp(this);	// watch myself
+	do_callback();			// call the callback
 
-	if (wp.deleted()) return 1; // exit, if deleted
+	if (wp.deleted()) return 1;	// exit, if deleted
 
 	// Now we are sure that the widget has not been deleted.
 	// It is safe to access the widget
 
-	clear_changed();	// access the widget
+	clear_changed();		// access the widget
       }
     }
   \endcode
 
 */
-class FL_EXPORT Fl_Watch {
+class FL_EXPORT Fl_Widget_Tracker {
 
   Fl_Widget* wp_;
 
 public:
 
-  Fl_Watch(Fl_Widget *wi);
-  ~Fl_Watch();
+  Fl_Widget_Tracker(Fl_Widget *wi);
+  ~Fl_Widget_Tracker();
 
   /**
     returns a pointer to the watched widget.
@@ -994,9 +994,9 @@ public:
 
     This is a convenience method. You can also use something like
 
-      if (watch.widget() == 0) // ...
+      if (wp.widget() == 0) // ...
 
-    where watch is an Fl_Watch object.
+    where \e \b wp is an Fl_Widget_Tracker object.
   */
   int deleted() {return wp_ == 0;}
 
@@ -1005,9 +1005,9 @@ public:
 
     This is a convenience method. You can also use something like
 
-      if (watch.widget() != 0) // ...
+      if (wp.widget() != 0) // ...
 
-    where watch is an Fl_Watch object.
+    where \e \b wp is an Fl_Widget_Tracker object.
   */
   int exists()  {return wp_ != 0;}
 
diff --git a/src/Fl.cxx b/src/Fl.cxx
index 0e5a1b251..de2b869e1 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -1519,7 +1519,7 @@ static int max_widget_watch = 0;
 /**
   Adds a widget pointer to the widget watch list.
   
-  \note Internal use only, please use class Fl_Watch instead.
+  \note Internal use only, please use class Fl_Widget_Tracker instead.
 
   This can be used, if it is possible that a widget might be deleted during
   a callback or similar function. The widget pointer must be added to the
@@ -1556,9 +1556,10 @@ static int max_widget_watch = 0;
    \see Fl::clear_widget_pointer()
 
    An easier and more convenient method to control widget deletion during
-   callbacks is to use the class Fl_Watch with a local (automatic) variable.
+   callbacks is to use the class Fl_Widget_Tracker with a local (automatic)
+   variable.
 
-   \see class Fl_Watch
+   \see class Fl_Widget_Tracker
 */
 void Fl::watch_widget_pointer(Fl_Widget *&w) 
 {
@@ -1585,7 +1586,7 @@ void Fl::watch_widget_pointer(Fl_Widget *&w)
   This is used to remove a widget pointer that has been added to the watch list
   with Fl::watch_widget_pointer(), when it is not needed anymore.
   
-  \note Internal use only, please use class Fl_Watch instead.
+  \note Internal use only, please use class Fl_Widget_Tracker instead.
 
   \see Fl::watch_widget_pointer()
 */
@@ -1617,14 +1618,16 @@ void Fl::release_widget_pointer(Fl_Widget *&w)
 
   This is called when a widget is destroyed (by its destructor). You should never
   call this directly.
-  
-  \note Internal use only, please use class Fl_Watch instead.
-  
-  This method searches the widget watch list for pointers to the widget and clears
-  all pointers that point to it. Widget pointers can be added to the widget
-  watch list by calling Fl::watch_widget_pointer().
-  
+
+  \note Internal use only !
+
+  This method searches the widget watch list for pointers to the widget and
+  clears each pointer that points to it. Widget pointers can be added to the
+  widget watch list by calling Fl::watch_widget_pointer() or by using the
+  helper class Fl_Widget_Tracker (recommended).
+
   \see Fl::watch_widget_pointer()
+  \see class Fl_Widget_Tracker
 */
 void Fl::clear_widget_pointer(Fl_Widget const *w) 
 {
@@ -1637,12 +1640,12 @@ void Fl::clear_widget_pointer(Fl_Widget const *w)
   }
 }
 
-// Helper class Fl_Watch
+// Helper class Fl_Widget_Tracker
 
 /**
   The constructor adds a widget to the watch list.
 */
-Fl_Watch::Fl_Watch(Fl_Widget *wi) {
+Fl_Widget_Tracker::Fl_Widget_Tracker(Fl_Widget *wi) {
 
   wp_ = wi;
   Fl::watch_widget_pointer(wp_); // add pointer to watch list
@@ -1651,7 +1654,7 @@ Fl_Watch::Fl_Watch(Fl_Widget *wi) {
 /**
   The destructor removes a widget from the watch list.
 */
-Fl_Watch::~Fl_Watch() {
+Fl_Widget_Tracker::~Fl_Widget_Tracker() {
 
   Fl::release_widget_pointer(wp_); // remove pointer from watch list
 }
diff --git a/src/Fl_Menu_Button.cxx b/src/Fl_Menu_Button.cxx
index 4c626ee5e..0ae69de51 100644
--- a/src/Fl_Menu_Button.cxx
+++ b/src/Fl_Menu_Button.cxx
@@ -58,7 +58,7 @@ const Fl_Menu_Item* Fl_Menu_Button::popup() {
   const Fl_Menu_Item* m;
   pressed_menu_button_ = this;
   redraw();
-  Fl_Watch mb(this);
+  Fl_Widget_Tracker mb(this);
   if (!box() || type()) {
     m = menu()->popup(Fl::event_x(), Fl::event_y(), label(), mvalue(), this);
   } else {
diff --git a/src/Fl_Widget.cxx b/src/Fl_Widget.cxx
index 740dad6fd..e1fa13b79 100644
--- a/src/Fl_Widget.cxx
+++ b/src/Fl_Widget.cxx
@@ -296,13 +296,14 @@ Fl_Widget::copy_label(const char *a) {
 /** Calls the widget callback.
 
   Causes a widget to invoke its callback function with arbitrary arguments.
+
   \param[in] o call the callback with \a o as the widget argument
-  \param[in] arg call the callback with \a arg as the user data argument
+  \param[in] arg use \a arg as the user data argument
   \see callback()
 */
 void
 Fl_Widget::do_callback(Fl_Widget* o,void* arg) {
-  Fl_Watch wp(o);
+  Fl_Widget_Tracker wp(o);
   callback_(o,arg); 
   if (wp.deleted()) return;
   if (callback_ != default_callback)