Documented wxMutexGuiEnter etc and thread sample.

Also found out that you cannot create top-level windows
    in a GUI thread other than the main one. No idea why.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@5181 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/function.tex

@@ -4,6 +4,58 @@
 
 The functions defined in wxWindows are described here.
 
+\section{Thread functions}\label{threadfunctions}
+
+\wxheading{Include files}
+
+<wx/thread.h>
+
+\wxheading{See also}
+
+\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, \helpref{Multithreading overview}{wxthreadoverview}
+
+\membersection{::wxMutexGuiEnter}\label{wxmutexguienter}
+
+\func{void}{wxMutexGuiEnter}{\void}
+
+This function must be called when any thread other than the main GUI thread
+wants to get access to the GUI library. This function will block the execution
+of the calling thread until the main thread (or any other thread holding the
+main GUI lock) leaves the GUI library and no other other thread will enter
+the GUI library until the calling thread calls \helpref{::wxMutexGuiLeave()}{wxmutexguileave}.
+
+Typically, these functions are used like this:
+
+\begin{verbatim}
+void MyThread::Foo(void)
+{
+    // before doing any GUI calls we must ensure that this thread is the only
+    // one doing it!
+
+    wxMutexGuiEnter();
+
+    // Call GUI here:
+    my_window->DrawSomething();
+    
+    wxMutexGuiLeave();
+}
+\end{verbatim}
+
+Note that under GTK, no creation of top-level windows is allowed in any
+thread but the main one.
+
+This function is only defined on platforms which support preemptive
+threads. 
+
+\membersection{::wxMutexGuiLeave}\label{wxmutexguileave}
+
+\func{void}{wxMutexGuiLeave}{\void}
+
+See \helpref{::wxMutexGuiEnter()}{wxmutexguienter}.
+
+This function is only defined on platforms which support preemptive
+threads.
+
 \section{File functions}\label{filefunctions}
 
 \wxheading{Include files}

docs/latex/wx/tsamples.tex

@@ -129,6 +129,26 @@ documents without much work. In fact, only few function calls are sufficient.
 while {\it Helpview} is simple tool that only pops up help window and
 displays help books given at command line.
 
+\subsection{Thread sample}\label{samplethread}
+
+This sample demonstrates the use of threads in connection with GUI programs.
+There are two fundamentally different ways to use threads in GUI programs and
+either way has to take care of the fact that the GUI library itself usually
+is not multi-threading safe, i.e. that it might crash if two threads try to
+access the GUI class simultaneously. One way to prevent that is have a normal
+GUI program in the main thread and some worker threads which work in the 
+background. In order to make communication between the main thread and the
+worker threads possible, wxWindows offers the \helpref{wxPostEvent}{wxpostevent}
+function and this sample makes use of this function.
+
+The other way to use a so called Mutex (such as those offered in the \helpref{wxMutex}{wxmutex}
+class) that prevent threads from accessing the GUI classes as long as any other
+thread accesses them. For this, wxWindows has the \helpref{wxMutexGuiEnter}{wxmutexguienter}
+and \helpref{wxMutexGuiLeave}{wxmutexguileave} functions, both of which are
+used and tested in the sample as well.
+
+See also \helpref{Multithreading overview}{wxthreadoverview} and \helpref{wxThread}{wxthread}.
+
 \subsection{Toolbar sample}\label{sampletoolbar}
 
 The toolbar sample shows the \helpref{wxToolBar}{wxtoolbar} class in action.

samples/thread/test.cpp

@@ -155,7 +155,6 @@ void MyThread::WriteText(const wxString& text)
     wxMutexGuiEnter();
 
     msg << text;
-
     m_frame->WriteText(msg);
     
     wxMutexGuiLeave();