From 9b1379e6888abc7cc051a6c82d8b27ce454ceb5a Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Tue, 13 May 2025 21:04:56 +0200 Subject: 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. --- FL/Fl.H | 46 +++++++++++++++++++++++++++++++++++++++------- FL/forms.H | 2 +- 2 files changed, 40 insertions(+), 8 deletions(-) (limited to 'FL') 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(); -- cgit v1.2.3