Add handler for thread messages (STR #1536)

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

12 files changed, 53 insertions, 45 deletions

diff --git a/CHANGES b/CHANGES
index d120e1040..1b99f7472 100644
--- a/CHANGES
+++ b/CHANGES
@@ -2,6 +2,8 @@ CHANGES IN FLTK 1.1.8
 
 	- Documentation fixes (STR #1454, STR #1455, STR #1456,
 	  STR #1457, STR #1458, STR #1460, STR #1481, STR #1578)
+	- Added Fl::set_awake_cb() to set a handler for thread
+	  messages (STR #1536)
 	- Added "mute sound" option to Sudoku game.
 	- Updated the bundled zlib to v1.2.3.
 	- Updated the bundled libpng to v1.2.16.
diff --git a/FL/Fl.H b/FL/Fl.H
index 1d4f67995..8c07365e6 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -78,6 +78,7 @@ public: // should be private!
   static void damage(int d) {damage_ = d;}
 
   static void (*idle)();
+  static void (*awake_cb)(void *);
 
   static const char* scheme_;
   static Fl_Image* scheme_bg_;
@@ -266,6 +267,7 @@ public:
   static void lock();
   static void unlock();
   static void awake(void* message = 0);
+  static void set_awake_cb(void (*cb)(void *)) { awake_cb = cb; }
   static void* thread_message();
 
   // Widget deletion:
diff --git a/documentation/Fl.html b/documentation/Fl.html
index 281ef7b8a..24d5be118 100644
--- a/documentation/Fl.html
+++ b/documentation/Fl.html
@@ -126,6 +126,7 @@ 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>
@@ -390,17 +391,11 @@ 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 <TT>wait()</TT> call to
-terminate so that the main thread can retrieve the message and
-any pending redraws can be processed.
+<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>awake()</TT> will overwrite the same 
-message pointer. 
-<A HREF="#Fl.thread_message"><TT>thread_message()</TT></A> only returns 
-the last message stored by the last <TT>awake()</TT> call.
+<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>See also: <a href="advanced.html#multithreading">multithreading</a>
+<P>See also: <a href="advanced.html#multithreading">multithreading</a>.
 
 <H4><A NAME="Fl.background2">void background2(uchar, uchar, uchar);</A></H4>
 
@@ -1174,6 +1169,10 @@ 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>
 
diff --git a/documentation/advanced.html b/documentation/advanced.html
index 52c3009b6..51ea1895b 100644
--- a/documentation/advanced.html
+++ b/documentation/advanced.html
@@ -9,24 +9,13 @@
 <P>This chapter explains advanced programming and design topics
 that will help you to get the most out of FLTK.</P>
 
-<H2><A NAME="multithreading">10.1 Multithreading</H2>
+<H2><A NAME="multithreading">Multithreading</H2>
 
-<P>FLTK supports multithreaded application using a locking mechanism
-based on "pthreads". We do not provide a threading interface 
-as part of the library. However a simple example how threads can 
-be implemented for all supported platforms can be found in 
-<tt>test/threads.h</tt> and <tt>test/threads.cxx</tt>.
+<P>FLTK supports multithreaded application using a locking mechanism based on "pthreads". We do not provide a threading interface as part of the library. However a simple example how threads can be implemented for all supported platforms can be found in <tt>test/threads.h</tt> and <tt>test/threads.cxx</tt>.
 
-<P>To use the locking mechanism, the command line version of FLTK
-must be compiled with <tt>--enable-threads</tt> set during the 
-<tt>configure</tt> process. IDE-based versions of FLTK are 
-automatically compiled with locking enabled if possible.
+<P>To use the locking mechanism, FLTK must be compiled with <tt>--enable-threads</tt> set during the <tt>configure</tt> process. IDE-based versions of FLTK are automatically compiled with locking enabled if possible.
 
-<P>In <TT>main()</TT>, before calling <TT>Fl::run()</TT>, call 
-<TT>Fl::lock()</TT>. This will startup the runtime multithreading 
-support for your program. All callbacks and derived functions 
-like <tt>handle()</tt> and <tt>draw()</tt> will now be properly
-locked.
+<P>In <TT>main()</TT>, call <TT>Fl::lock()</TT> before <TT>Fl::run()</TT> to start the runtime multithreading support for your program. All callbacks and derived functions like <tt>handle()</tt> and <tt>draw()</tt> will now be properly locked.
 
 <pre>
   main() {
@@ -56,34 +45,31 @@ in the following code:
 <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 
-following rulesi for threads on all operating systems.
+following rules for threads on all operating systems:
 
 <ul>
 
-<li>don't <tt>show()</tt> or <tt>hide()</tt>anything that contains 
+<li>Don't <tt>show()</tt> or <tt>hide()</tt>anything that contains 
 widgets derived from <tt>Fl_Window</tt>, including dialogs, file
 choosers, subwindows or <tt>Fl_GL_Window</tt>s</li>
 
-<li>don't call <tt>Fl::wait()</tt>, <tt>Fl::flush()</tt> or any 
+<li>Don't call <tt>Fl::wait()</tt>, <tt>Fl::flush()</tt> or any 
 related methods that will handle system messages</li>
 
-<li>don't start or cancel timers</li>
+<li>Don't start or cancel timers</li>
 
-<li>don't change window decorations or titles</li>
+<li>Don't change window decorations or titles</li>
 
-<li><tt>make_current()</tt> may or may not work well for regular
-windows, but should always work for <tt>Fl_GL_Window</tt>s to 
-allow for high speed rendering on graphics cards with multiple 
-pipelines</li>
+<li>The <tt>make_current()</tt> method may or may not work well for regular windows, but should always work for <tt>Fl_GL_Window</tt>s to allow for high speed rendering on graphics cards with multiple pipelines</li>
 
 </ul>
 
 <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.unlock">void unlock()</A>, 
-<a href="Fl.html#Fl.awake">void awake(void *message)</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>.
 
-
 </BODY>
 </HTML>
diff --git a/documentation/common.html b/documentation/common.html
index a759bd5ff..75a95092b 100644
--- a/documentation/common.html
+++ b/documentation/common.html
@@ -533,7 +533,7 @@ around the origin. This function is then linked into the symbols
 table using <tt>fl_add_symbol</tt>:</P>
 
 <UL><PRE>
-int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)
+<A NAME="fl_add_symbol">int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)</A>
 </PRE></UL>
 
 <P><i>name</i> is the name of the symbol without the "@"; <i>scalable</I>
@@ -541,7 +541,7 @@ must be set to 1 if the symbol is generated using scalable vector drawing
 functions.</P>
 
 <UL><PRE>
-int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col)
+<A NAME="fl_draw_symbol">int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col)</A>
 </PRE></UL>
 
 <P>This function draw a named symbol fitting the given rectangle.
diff --git a/documentation/drawing.html b/documentation/drawing.html
index de68225e5..f734ce34a 100644
--- a/documentation/drawing.html
+++ b/documentation/drawing.html
@@ -229,7 +229,7 @@ widths. Full functionality is not available under Windows 95, 98,
 and Me due to the reduced drawing functionality these operating
 systems provide.
 
-<h4>void fl_line_style(int style, int width=0, char* dashes=0)</h4>
+<h4><A NAME="fl_line_style">void fl_line_style(int style, int width=0, char* dashes=0)</A></h4>
 
 <P>Set how to draw lines (the "pen").  If you change this it is your
 responsibility to set it back to the default with
diff --git a/documentation/examples.html b/documentation/examples.html
index bed27925d..53101d396 100644
--- a/documentation/examples.html
+++ b/documentation/examples.html
@@ -4,7 +4,7 @@
 </HEAD>
 <BODY>
 
-<H1 ALIGN="RIGHT"><A NAME="tests">I - Tests and Demo Source Code</A></H1>
+<H1 ALIGN="RIGHT"><A NAME="examples">I - Tests and Demo Source Code</A></H1>
 
 <P ALIGN="RIGHT">March 19, 2005</P>
 
diff --git a/documentation/fltk.book b/documentation/fltk.book
index 68c5a0226..acd4fcc0c 100644
--- a/documentation/fltk.book
+++ b/documentation/fltk.book
@@ -1,5 +1,5 @@
-#HTMLDOC 1.8.20
--t pdf13 -f fltk.pdf --book --toclevels 2 --no-numbered --toctitle "Table of Contents" --title --titleimage FL.gif --linkstyle underline --size Universal --left 1.00in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer h.1 --tocheader .t. --tocfooter ..i --duplex --portrait --color --no-pscommands --no-xrxcomments --compression=9 --jpeg=50 --no-embedfonts --fontsize 11.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset 8859-1 --links --no-truetype --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all  --owner-password ""  --user-password "" --browserwidth 680
+#HTMLDOC 1.8.27.1
+-t pdf13 -f "fltk.pdf" --book --toclevels 2 --no-numbered --toctitle "Table of Contents" --title --titleimage "FL.gif" --linkstyle underline --size Universal --left 1.00in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --header1 ... --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --duplex --portrait --color --no-pscommands --no-xrxcomments --compression=9 --jpeg=50 --fontsize 11.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all  --owner-password ""  --user-password "" --browserwidth 680 --strict --no-overflow
 preface.html
 intro.html
 basics.html
@@ -11,6 +11,7 @@ subclassing.html
 opengl.html
 fluid.html
 widgets.html
+advanced.html
 Fl.html
 Fl_Adjuster.html
 Fl_Bitmap.html
@@ -75,6 +76,7 @@ Fl_Scroll.html
 Fl_Scrollbar.html
 Fl_Secret_Input.html
 Fl_Select_Browser.html
+Fl_Shared_Image.html
 Fl_Single_Window.html
 Fl_Slider.html
 Fl_Spinner.html
diff --git a/documentation/intro.html b/documentation/intro.html
index a3b464e6a..dac5355d3 100644
--- a/documentation/intro.html
+++ b/documentation/intro.html
@@ -335,8 +335,8 @@ make
 	<DD><A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for
 	reporting bugs]
 
-	<DT>News</DT>
-	<DD><A HREF="news://news.easysw.com">news.easysw.com</A></DD>
+	<DT>NNTP Newsgroups</DT>
+	<DD>news.easysw.com</DD>
 
 </DL>
 
diff --git a/documentation/osissues.html b/documentation/osissues.html
index ef3eb324c..a838b7a87 100644
--- a/documentation/osissues.html
+++ b/documentation/osissues.html
@@ -136,7 +136,7 @@ unsigned long fl_xpixel(uchar r, uchar g, uchar b)</A></H4>
 index or RGB color. This is the X pixel that <A
 href="drawing.html#fl_color"><TT>fl_color()</TT></A> would use.
 
-<H4><A name="fl_parse_color">int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b)</A></H4>
+<H4><A name="fl_parse_color">int fl_parse_color(const char* p, uchar&amp; r, uchar&amp; g, uchar&amp; b)</A></H4>
 
 <P>Convert a name into the red, green, and blue values of a color
 by parsing the X11 color names. On other systems, <tt>fl_parse_color</tt>
diff --git a/src/Fl_lock.cxx b/src/Fl_lock.cxx
index be52f78d1..31206c8e7 100644
--- a/src/Fl_lock.cxx
+++ b/src/Fl_lock.cxx
@@ -38,6 +38,14 @@
    another.  This file is an attempt to make minimal additions
    and make them self-contained in this source file.
 
+   From Mike:
+
+   Starting with 1.1.8, we now have a callback so that you can
+   process awake() messages as they come in.
+
+
+   The API:
+
    Fl::lock() - recursive lock.  You must call this before the
    first call to Fl::wait()/run() to initialize the thread
    system. The lock is locked all the time except when
@@ -48,12 +56,17 @@
    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
+   to call for Fl::awake() messages that is called for each
+   message received.
+
    Fl::thread_message() - returns an argument sent to an
    Fl::awake() call, or returns NULL if none.  WARNING: the
    current implementation only has a one-entry queue and only
    returns the most recent value!
 */
 
+void	(*Fl::awake_cb)(void *);
 
 ////////////////////////////////////////////////////////////////
 // Windows threading...
@@ -189,6 +202,7 @@ 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_);
 }
 
 // These pointers are in Fl_x.cxx:
diff --git a/src/Fl_win32.cxx b/src/Fl_win32.cxx
index 632c6cb42..a4660def8 100644
--- a/src/Fl_win32.cxx
+++ b/src/Fl_win32.cxx
@@ -291,8 +291,11 @@ int fl_wait(double time_to_wait) {
       }
 #endif
 
-      if (fl_msg.message == fl_wake_msg)  // Used for awaking wait() from another thread
+      if (fl_msg.message == fl_wake_msg) {
+        // Used for awaking wait() from another thread
 	thread_message_ = (void*)fl_msg.wParam;
+        if (awake_cb) (*awake_cb)(thread_message_);
+      }
 
       TranslateMessage(&fl_msg);
       DispatchMessage(&fl_msg);