Remove deprecated function Fl::set_idle()

This turned out to be more complicated than just to delete a function
because it was used internally, and the callback signatures were a bit
flaky. I also added a lot of documentation to clarify matters.

FL/Fl.H: document idle callback signatures, make some internal
  functions of class Fl private, add public Fl::idle() accessor (read-
  only), add Fl::add_idle(Fl_Old_Idle_Handler cb) to enable using
  old-style idle callbacks w/o 'data' argument.

FL/forms.H: replace Fl::set_idle() with Fl::add_idle().

src/Fl.cxx: rename private Fl::idle_ with trailing underscore.

src/Fl_System_Driver.cxx: use new public accessor Fl::idle() to access
  Fl::idle_ which is now private.

src/Fl_add_idle.cxx: improve documentation, clarify idle callback
  matching, add example code in docs, rename methods,  add overloaded
  Fl::add_idle(Fl_Old_Idle_Handler cb).

src/Fl_win32.cxx: use public Fl::idle() rather than private member.
src/drivers/Unix/Fl_Unix_System_Driver.cxx: same as above.
src/Fl_cocoa.mm: same as above.

2 files changed, 40 insertions, 8 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 578971348..245d9a562 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -99,10 +99,17 @@ typedef void (*Fl_Timeout_Handler)(void *data);
 /** Signature of some wakeup callback functions passed as parameters */
 typedef void (*Fl_Awake_Handler)(void *data);
 
-/** Signature of add_idle callback functions passed as parameters */
+/** Signature of add_idle callback function passed as parameter.
+  This signature allows an idle callback to use one parameter as an
+  arbitrary `data` value.
+*/
 typedef void (*Fl_Idle_Handler)(void *data);
 
-/** Signature of set_idle callback functions passed as parameters */
+/** Signature of add_idle callback function passed as parameter.
+  This signature allows an idle callback without parameters.
+  When the callback is called it is called with an additional
+  parameter (set to nullptr) which is not used by the callback.
+*/
 typedef void (*Fl_Old_Idle_Handler)();
 
 /** Signature of add_fd functions passed as parameters */
@@ -312,6 +319,8 @@ public:
    */
   static void option(Fl_Option opt, bool val);
 
+private:
+
   /**
     The currently executing idle callback function: DO NOT USE THIS DIRECTLY!
 
@@ -319,7 +328,22 @@ public:
     idle callback functions to be called.
     \see add_idle(), remove_idle()
   */
-  static void (*idle)();
+  static void (*idle_)();
+
+public:
+  /**
+    Returns whether at least one idle callback is currently set.
+
+    \c true means that at least one callback is currently queued, but
+    not necessarily active. While a callback is being executed, it is
+    also counted as "set" unless (i.e. before) it removes itself from
+    the idle callback queue (ring).
+
+    \return  whether an idle callback is currently set
+    \retval true  At least one idle callback is currently set.
+    \retval false No idle callback is currently set.
+   */
+  static bool idle() { return (idle_ != nullptr); }
 
 #ifndef FL_DOXYGEN
 private:
@@ -491,9 +515,10 @@ public:
   static long ticks_since(Fl_Timestamp& then);
   static long ticks_between(Fl_Timestamp& back, Fl_Timestamp& further_back);
 
-  // private
+private:
   static void run_idle();
   static void run_checks();
+public:
   static void add_fd(int fd, int when, Fl_FD_Handler cb, void* = 0); // platform dependent
   static void add_fd(int fd, Fl_FD_Handler cb, void* = 0); // platform dependent
   /** Removes a file descriptor handler. */
@@ -504,6 +529,7 @@ public:
   static void add_idle(Fl_Idle_Handler cb, void* data = 0);
   static int  has_idle(Fl_Idle_Handler cb, void* data = 0);
   static void remove_idle(Fl_Idle_Handler cb, void* data = 0);
+  static void add_idle(Fl_Old_Idle_Handler cb);
   /** If true then flush() will do something. */
   static int damage() {return damage_;}
   static void redraw();
@@ -1292,12 +1318,18 @@ public:
   static int event_button5() {return e_state & FL_BUTTON5;}
   /**   @} */
 
+private:
   /**
-    Sets an idle callback.
+    Sets an idle callback (internal use only).
+
+    This method is now private and is used to store the idle callback.
+    The old, public set_idle() method was deprecated since 1.3.x and
+    is no longer available in FLTK 1.5.
 
-    \deprecated This method is obsolete - use the add_idle() method instead.
+    See documentation: use Fl::add_idle() instead.
   */
-  static void set_idle(Fl_Old_Idle_Handler cb) {idle = cb;}
+  static void set_idle_(Fl_Old_Idle_Handler cb) {idle_ = cb;}
+public:
   /** See grab(Fl_Window*) */
   static void grab(Fl_Window& win) {grab(&win);}
   /** Releases the current grabbed window, equals grab(0).
diff --git a/FL/forms.H b/FL/forms.H
index 9523b4da5..076c54d6f 100644
--- a/FL/forms.H
+++ b/FL/forms.H
@@ -170,7 +170,7 @@ inline void fl_add_timeout(long msec, void (*cb)(void*), void* v) {
 inline void fl_remove_timeout(int) {}
 
 // type of callback is different!
-inline void fl_set_idle_callback(void (*cb)()) {Fl::set_idle(cb);}
+inline void fl_set_idle_callback(void (*cb)()) {Fl::add_idle(cb);}
 
 FL_EXPORT Fl_Widget* fl_do_forms(void);
 FL_EXPORT Fl_Widget* fl_check_forms();