now renaming restoring dir src_doc src.

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

1 files changed, 113 insertions, 0 deletions

diff --git a/documentation/src/advanced.dox b/documentation/src/advanced.dox
new file mode 100644
index 000000000..17afa9147
--- /dev/null
+++ b/documentation/src/advanced.dox
@@ -0,0 +1,113 @@
+/**
+
+ \page advanced 10 - Advanced FLTK
+
+This chapter explains advanced programming and design topics
+that will help you to get the most out of FLTK.
+
+<A NAME="multithreading"> </A> <!-- For old HTML links only ! -->
+\section advanced_multithreading Multithreading
+
+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>.
+
+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.
+
+In <TT>main()</TT>, call
+<a href="Fl.html#Fl.lock"><TT>Fl::lock()</TT></A> before
+<A HREF="Fl.html#Fl.run"><TT>Fl::run()</TT></A> or
+<A HREF="Fl.html#Fl.wait"><TT>Fl::wait()</TT></A>
+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:
+
+}
+
+\code
+    int main() {
+      Fl::lock();
+      /* run thread */
+      while (Fl::wait() &gt; 0) {
+        if (Fl::thread_message()) {
+          /* process your data */
+        }
+      }
+    }
+\endcode
+
+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>:
+
+\code
+    Fl::lock();      // avoid conflicting calls
+    ...              // your code here
+    Fl::unlock();    // allow other threads to access FLTK again
+\endcode
+
+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>
+
+\code
+    void *msg;       // "msg" is a pointer to your message
+    Fl::awake(msg);  // send "msg" to main thread
+\endcode
+
+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>
+
+\code
+    void do_something(void *userdata) {
+      // running with the main thread
+    }
+
+    // running in another thread
+    void *data;       // "data" is a pointer to your user data
+    Fl::awake(do_something, data);  // call something in main thread
+\endcode
+
+      
+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 rules for threads on all operating systems:
+
+
+\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 Don't call <tt>Fl::wait()</tt>, <tt>Fl::flush()</tt> or any 
+    related methods that will handle system messages
+
+\li Don't start or cancel timers
+
+\li Don't change window decorations or titles
+
+\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
+
+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.thread_message">void *thread_message()</A>,
+<a href="Fl.html#Fl.unlock">void unlock()</A>.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="fluid.html">[Previous]&nbsp; 9 - Programming with FLUID</a>&nbsp;
+<a class="el" href="unicode.html">[Next]&nbsp; 11 - Unicode and utf-8 Support</a>&nbsp;
+\endhtmlonly
+*/