Removed the Fl::set_awake_cb API and documented the Fl::awake(function, data) API.

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

CHANGES

@@ -4,9 +4,9 @@ CHANGES IN FLTK 1.1.8
 	  STR #1457, STR #1458, STR #1460, STR #1481, STR #1578)
 	- The sample RPM spec file now enables large file support
 	  and threading support (STR #1603)
-	- Changed minumu contrast between background and text to 
+	- Changed minimum contrast between background and text to 
 	  96 and added more weight to the blue component to improve
-	  readability (STR #1625)
+	  readability for certain color combinations (STR #1625)
 	- Fixed VCNet OpenGL project file (STR #1617)
 	- Fixed scrolling of clipped areas in MSWindows (STR
 	  #1601)
@@ -16,7 +16,7 @@ CHANGES IN FLTK 1.1.8
 	  avoid data loss (STR #1609)
 	- The Fl_File_Chooser constructor now saves and restores the
 	  current group (STR #1611)
-	- Added Fl::set_awake_cb() to set a handler for thread
+	- Added Fl::awake(fn*,void*) to set a handler for thread
 	  messages (STR #1536)
 	- Added "mute sound" option to Sudoku game.
 	- Updated the bundled zlib to v1.2.3.

FL/Fl.H

@@ -79,7 +79,6 @@ public: // should be private!
   static void damage(int d) {damage_ = d;}
 
   static void (*idle)();
-  static void (*awake_cb)(void *);
   static Fl_Awake_Handler *awake_ring_;
   static void **awake_data_;
   static int awake_ring_size_;
@@ -277,7 +276,6 @@ public:
   static void unlock();
   static void awake(void* message = 0);
   static int awake(Fl_Awake_Handler cb, void* message = 0);
-  static void set_awake_cb(void (*cb)(void *)) { awake_cb = cb; }
   static void* thread_message();
 
   // Widget deletion:

documentation/Fl.html

@@ -126,7 +126,6 @@ state information and global methods for the current application.</P>
 	<LI><A HREF="#Fl.selection_owner">selection_owner</A></LI>
 	<LI><A HREF="#Fl.set_abort">set_abort</A></LI>
 	<LI><A HREF="#Fl.set_atclose">set_atclose</A></LI>
-	<LI><A HREF="#Fl.set_awake_cb">set_awake_cb</A></LI>
 	<LI><A HREF="#Fl.set_boxtype">set_boxtype</A></LI>
 	<LI><A HREF="#Fl.set_color">set_color</A></LI>
 	<LI><A HREF="#Fl.set_font">set_font</A></LI>
@@ -391,9 +390,24 @@ argument on the command-line. You can change the message by setting the
 
 <H4><A NAME="Fl.awake">void awake(void *p);</A></H4>
 
-<P>The <TT>awake()</TT> method sends a message pointer to the main thread, causing any pending <A HREF="#Fl.wait"><TT>Fl::wait()</TT></A> call to terminate so that the main thread can retrieve the message and any pending redraws can be processed.
+<H4><A NAME="Fl.awake">int awake(void (*callback)(void*), void *userdata);</A></H4>
 
-<P>Multiple calls to <TT>Fl::awake()</TT> will queue multiple pointers for the main thread to process, up to a system-defined (typically several thousand) depth. The default message handler saves the last message which can be accessed using the <A HREF="#Fl.thread_message"><TT>Fl::thread_message()</TT></A> function. Use the <A HREF="#Fl.set_awake_cb"><TT>Fl::set_awake_cb()</TT></A> function to register your own thread message handler that is called for every message received by the main thread.
+<P>The <TT>awake()</TT> method sends a message pointer to the main thread, 
+causing any pending <A HREF="#Fl.wait"><TT>Fl::wait()</TT></A> call to 
+terminate so that the main thread can retrieve the message and any pending 
+redraws can be processed.
+
+<P>Multiple calls to <TT>Fl::awake()</TT> will queue multiple pointers 
+for the main thread to process, up to a system-defined (typically several 
+thousand) depth. The default message handler saves the last message which 
+can be accessed using the <A HREF="#Fl.thread_message">
+<TT>Fl::thread_message()</TT></A> function.
+
+<P>The second form of <TT>awake()</TT> registers a function that will be 
+called by the main thread during the next message handling cycle. 
+<TT>awake()</TT> will return 0 if the callback function was registered, 
+and -1 if registration failed. Over a thousand awake callbacks can be
+registered simultaneously.
 
 <P>See also: <a href="advanced.html#multithreading">multithreading</a>.
 
@@ -1169,10 +1183,6 @@ of this.</I>
 
 <H4><A NAME="Fl.set_atclose">void set_atclose(void (*f)(Fl_Window*,void*));</A></H4>
 
-<H4><A NAME="Fl.set_awake_cb">void set_awake_cb(void (*cb)(void*));</A></H4>
-
-<P>Sets a function to handle thread messages sent via the <A HREF="#Fl.awake"><TT>Fl::awake()</TT></A> function.</P>
-
 <H4><A NAME="Fl.set_boxtype">void set_boxtype(Fl_Boxtype, Fl_Box_Draw_F*,uchar,uchar,uchar,uchar);<BR>
 void set_boxtype(Fl_Boxtype, Fl_Boxtype from);</A></H4>
 

documentation/advanced.html

@@ -31,7 +31,8 @@ that will help you to get the most out of FLTK.</P>
 
 <P>You can now start as many threads as you like. From within
 a thread (other than the main thread) FLTK calls must be wrapped
-with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> and <a href="Fl.html#Fl.unlock"><tt>Fl::unlock()</tt></a>:
+with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> 
+and <a href="Fl.html#Fl.unlock"><tt>Fl::unlock()</tt></a>:
 
 <pre>
     Fl::lock();      // avoid conflicting calls
@@ -39,28 +40,29 @@ with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> and <a href="Fl.
     Fl::unlock();    // allow other threads to access FLTK again
 </pre>
 
-<p>You can send messages from child threads to the main thread using <a href="Fl.html#Fl.awake"><tt>Fl::awake(msg)</tt></a>:</p>
+<p>You can send messages from child threads to the main thread 
+using <a href="Fl.html#Fl.awake"><tt>Fl::awake(msg)</tt></a>:</p>
 
 <pre>
     void *msg;       // "msg" is a pointer to your message
     Fl::awake(msg);  // send "msg" to main thread
 </pre>
 
-<p>These messages can be read by the main thread using <A HREF="Fl.html#Fl.thread_message"><TT>Fl::thread_message()</TT></A> or by registering a message callback with <A HREF="Fl.html#Fl.set_awake_cb"><TT>Fl::set_awake_cb()</TT></A>:</p>
+<p>You can also tell the main thread to call a function for you
+as soon as possible by using
+<a href="Fl.html#Fl.awake"><tt>Fl::awake(callback, userdata)</tt></a>:</p>
 
 <pre>
-    void message_cb(void *msg) {
+    void do_something(void *userdata) {
-      ... do something with "msg" ...
+      // running with the main thread
     }
 
-    int main() {
+    // running in another thread
-      Fl::lock();
+    void *data;       // "data" is a pointer to your user data
-      Fl::set_awake_cb(message_cb);
+    Fl::awake(do_something, data);  // call something in main thread
-      /* run thread */
-      return (Fl::run());
-    }
 </pre>
 
+      
 <P>FLTK supports multiple platforms, some of them which do not 
 allow any other but the main thread to handle system events and
 open or close windows. The safe thing to do is to adhere to the 
@@ -86,7 +88,6 @@ related methods that will handle system messages</li>
 <P>See also: 
 <a href="Fl.html#Fl.awake">void awake(void *message)</A>, 
 <a href="Fl.html#Fl.lock">void lock()</A>, 
-<a href="Fl.html#Fl.set_awake_cb">void set_awake_cb(void (*cb)(void *)</A>, 
 <a href="Fl.html#Fl.thread_message">void *thread_message()</A>,
 <a href="Fl.html#Fl.unlock">void unlock()</A>.
 

src/Fl_lock.cxx

@@ -58,9 +58,8 @@
    Fl::awake(void*) - Causes Fl::wait() to return (with the lock
    locked) even if there are no events ready.
 
-   Fl::set_awake_cb(void (*cb)(void *)) - Registers a function
+   Fl::awake(void (*cb)(void *), void*) - Call a function
-   to call for Fl::awake() messages that is called for each
+   in the main thread from within another thread of execution.
-   message received.
 
    Fl::thread_message() - returns an argument sent to an
    Fl::awake() call, or returns NULL if none.  WARNING: the
@@ -68,8 +67,6 @@
    returns the most recent value!
 */
 
-void	(*Fl::awake_cb)(void *);
-
 Fl_Awake_Handler *Fl::awake_ring_;
 void **Fl::awake_data_;
 int Fl::awake_ring_size_;
@@ -91,7 +88,7 @@ int Fl::add_awake_handler_(Fl_Awake_Handler func, void *data)
     awake_data_ = (void**)malloc(awake_ring_size_*sizeof(void*));
   }
   if (awake_ring_head_==awake_ring_tail_-1 || awake_ring_head_+1==awake_ring_tail_) {
-    // ring is full. Return -1 as ann error indicator.
+    // ring is full. Return -1 as an error indicator.
     ret = -1;
   } else {
     awake_ring_[awake_ring_head_] = func;
@@ -278,7 +275,6 @@ void* Fl::thread_message() {
 
 static void thread_awake_cb(int fd, void*) {
   read(fd, &thread_message_, sizeof(void*));
-  if (Fl::awake_cb) (*Fl::awake_cb)(thread_message_);
   Fl_Awake_Handler func;
   void *data;
   while (Fl::get_awake_handler_(func, data)==0) {

src/Fl_win32.cxx

@@ -299,7 +299,6 @@ int fl_wait(double time_to_wait) {
       if (fl_msg.message == fl_wake_msg) {
         // Used for awaking wait() from another thread
 	thread_message_ = (void*)fl_msg.wParam;
-        if (Fl::awake_cb) (*Fl::awake_cb)(thread_message_);
         Fl_Awake_Handler func;
         void *data;
         while (Fl::get_awake_handler_(func, data)==0) {

test/threads.cxx

@@ -111,12 +111,6 @@ void* prime_func(void* p)
   return 0;
 }
 
-void message_cb(void *m) {
-  if (m == (void *)browser1) putchar('1');
-  else putchar('2');
-  fflush(stdout);
-}
-
 int main(int argc, char **argv)
 {
   Fl_Window* w = new Fl_Window(200, 200, "Single Thread");
@@ -141,11 +135,6 @@ int main(int argc, char **argv)
   // when it is safe to do so...
   Fl::lock();
 
-  // Register a callback for Fl::awake() messages.  This allows
-  // you to get all thread messages even if you are in another
-  // run loop (say, with a modal dialog...)
-  Fl::set_awake_cb(message_cb);
-
   // Start threads...
 
   // One thread displaying in one browser