Add Fl::remove_next_timeout(...) to remove only one timeout (#992)

This method also returns the data pointer of the removed timeout.

This new method is generally useful for user code and particularly
necessary to fix issue #991.

Co-authored-by: Albrecht Schlosser <albrechts.fltk@online.de>

1 files changed, 55 insertions, 4 deletions

diff --git a/src/Fl_Timeout.cxx b/src/Fl_Timeout.cxx
index 3c04cae17..9aa89b839 100644
--- a/src/Fl_Timeout.cxx
+++ b/src/Fl_Timeout.cxx
@@ -210,7 +210,9 @@ void Fl_Timeout::insert() {
   \retval   0   not found
   \retval   1   found
 
-  Implements Fl::has_timeout(Fl_Timeout_Handler cb, void *data)
+  Implements:
+
+      int Fl::has_timeout(Fl_Timeout_Handler cb, void *data)
 
   \see Fl::has_timeout(Fl_Timeout_Handler cb, void *data)
 */
@@ -232,7 +234,9 @@ int Fl_Timeout::has_timeout(Fl_Timeout_Handler cb, void *data) {
   \param[in]  cb      callback function
   \param[in]  data    optional user data (default: \p NULL)
 
-  Implements Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *data)
+  Implements:
+
+      void Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *data)
 
   \see Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *data)
 */
@@ -250,7 +254,9 @@ void Fl_Timeout::add_timeout(double time, Fl_Timeout_Handler cb, void *data) {
   \param[in]  cb      callback function
   \param[in]  data    optional user data (default: \p NULL)
 
-  Implements Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)
+  Implements:
+
+      void Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)
 
   \see Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)
 */
@@ -276,7 +282,9 @@ void Fl_Timeout::repeat_timeout(double time, Fl_Timeout_Handler cb, void *data)
   \param[in]  cb    Timer callback to be removed (must match)
   \param[in]  data  Wildcard if NULL, must match otherwise
 
-  Implements Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)
+  Implements:
+
+      void Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)
 
   \see Fl::remove_timeout(Fl_Timeout_Handler cb, void *data)
 */
@@ -294,6 +302,49 @@ void Fl_Timeout::remove_timeout(Fl_Timeout_Handler cb, void *data) {
 }
 
 /**
+  Remove the next matching timeout callback and return its \p data pointer.
+
+  Implements:
+
+      int Fl::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return)
+
+  \param[in]    cb    Timer callback to be removed (must match)
+  \param[in]    data  Wildcard if NULL, must match otherwise
+  \param[inout] data_return  pointer to void * to receive the data value
+
+  \return       non-zero if a timer was found and removed
+  \retval   0   no matching timer was found
+  \retval   1   the last matching timeout was found and removed
+  \retval  N>1  a matching timeout was removed and there are\n
+                (N - 1) matching timeouts pending
+
+  For details
+  \see Fl::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return)
+*/
+int Fl_Timeout::remove_next_timeout(Fl_Timeout_Handler cb, void *data, void **data_return) {
+  int ret = 0;
+  for (Fl_Timeout** p = &first_timeout; *p;) { // scan all timeouts
+    Fl_Timeout* t = *p;
+    if (t->callback == cb && (t->data == data || !data)) { // timeout matches
+      ret++;
+      if (ret == 1) { // first timeout: remove
+        if (data_return)
+          *data_return = t->data;
+        *p = t->next;
+        t->next = free_timeout;
+        free_timeout = t;
+        continue;
+      }
+      p = &(t->next);
+    } // timeout matches
+    else { // no match
+      p = &(t->next);
+    }
+  } // scan all timeouts
+  return ret;
+}
+
+/**
   Remove the timeout from the active timer queue and push it onto
   the stack of currently running callbacks.