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.

1 files changed, 5 insertions, 4 deletions

diff --git a/src/Fl_System_Driver.cxx b/src/Fl_System_Driver.cxx
index 7cac84faf..5a01d6534 100644
--- a/src/Fl_System_Driver.cxx
+++ b/src/Fl_System_Driver.cxx
@@ -1,7 +1,7 @@
 //
 // A base class for platform specific system calls.
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-2025 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -360,9 +360,10 @@ double Fl_System_Driver::wait(double time_to_wait) {
   Fl::run_checks();
   Fl::run_idle();
 
-  // the idle function may turn off idle, we can then wait,
-  // or it leaves Fl::idle active and we set time_to_wait to 0
-  if (Fl::idle) {
+  // The idle function may turn off idle() if *all* idle callbacks
+  // are removed from the callback queue (ring), we can then wait.
+  // Or it leaves Fl::idle() active and we set time_to_wait to 0.
+  if (Fl::idle()) {
     time_to_wait = 0.0;
   } else {
     // limit time by next timer interval