Add handler for thread messages (STR #1536)

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

8 files changed, 31 insertions, 44 deletions

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>