Allow overriding print preview frame creation in docview.

[wxWidgets.git] / interface / wx / thread.h

diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index d0641dfe1745139621c7d8f71411350f12b03d0a..328879c901a8cea3018c917f51a0ea9e5a7b2456 100644 (file)
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -279,7 +279,7 @@ public:
 
     Example:
     @code
-        extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE;
+        wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent);
 
         class MyFrame : public wxFrame, public wxThreadHelper
         {
@@ -298,7 +298,7 @@ public:
 
             ...
             void DoStartALongTask();
-            void OnThreadUpdate(wxCommandEvent& evt);
+            void OnThreadUpdate(wxThreadEvent& evt);
             void OnClose(wxCloseEvent& evt);
             ...
 
@@ -312,7 +312,7 @@ public:
             DECLARE_EVENT_TABLE()
         };
 
-        DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE)
+        wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
         BEGIN_EVENT_TABLE(MyFrame, wxFrame)
             EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate)
             EVT_CLOSE(MyFrame::OnClose)
@@ -364,7 +364,7 @@ public:
 
                 // VERY IMPORTANT: do not call any GUI function inside this
                 //                 function; rather use wxQueueEvent():
-                wxQueueEvent(this, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
+                wxQueueEvent(this, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
                     // we used pointer 'this' assuming it's safe; see OnClose()
             }
 
@@ -386,7 +386,7 @@ public:
             Destroy();
         }
 
-        void MyFrame::OnThreadUpdate(wxCommandEvent&evt)
+        void MyFrame::OnThreadUpdate(wxThreadEvent& evt)
         {
             // ...do something... e.g. m_pGauge->Pulse();
 
@@ -399,7 +399,7 @@ public:
     @library{wxbase}
     @category{threading}
 
-    @see wxThread
+    @see wxThread, wxThreadEvent
 */
 class wxThreadHelper
 {
@@ -518,6 +518,10 @@ enum wxCriticalSectionType
     @library{wxbase}
     @category{threading}
 
+    @note Critical sections can be used before the wxWidgets library is fully
+          initialized. In particular, it's safe to create global
+          wxCriticalSection instances.
+
     @see wxThread, wxCondition, wxCriticalSectionLocker
 */
 class wxCriticalSection
@@ -535,11 +539,17 @@ public:
     ~wxCriticalSection();
 
     /**
-        Enter the critical section (same as locking a mutex).
-
+        Enter the critical section (same as locking a mutex): if another thread
+        has already entered it, this call will block until the other thread
+        calls Leave().
         There is no error return for this function.
-        After entering the critical section protecting some global
-        data the thread running in critical section may safely use/modify it.
+
+        After entering the critical section protecting a data variable,
+        the thread running inside the critical section may safely use/modify it.
+
+        Note that entering the same critical section twice or more from the same
+        thread doesn't result in a deadlock; in this case in fact this function will
+        immediately return.
     */
     void Enter();
 
@@ -631,8 +641,8 @@ enum
 
     @code
     // declare a new type of event, to be used by our MyThread class:
-    extern const wxEventType wxEVT_COMMAND_MYTHREAD_COMPLETED;
-    extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE;
+    wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent);
+    wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent);
     class MyFrame;
 
     class MyThread : public wxThread
@@ -669,7 +679,8 @@ enum
         // a resume routine would be nearly identic to DoPauseThread()
         void DoResumeThread() { ... }
 
-        void OnThreadCompletion(wxCommandEvent&);
+        void OnThreadUpdate(wxThreadEvent&);
+        void OnThreadCompletion(wxThreadEvent&);
         void OnClose(wxCloseEvent&);
 
     protected:
@@ -686,8 +697,8 @@ enum
         EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion)
     END_EVENT_TABLE()
 
-    DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_COMPLETED)
-    DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE)
+    wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent)
+    wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
 
     void MyFrame::DoStartThread()
     {
@@ -721,13 +732,13 @@ enum
         {
             // ... do a bit of work...
 
-            wxQueueEvent(m_pHandler, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
+            wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
         }
 
         // signal the event handler that this thread is going to be destroyed
         // NOTE: here we assume that using the m_pHandler pointer is safe,
         //       (in this case this is assured by the MyFrame destructor)
-        wxQueueEvent(m_pHandler, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED));
+        wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED));
 
         return (wxThread::ExitCode)0;     // success
     }
@@ -740,12 +751,12 @@ enum
         m_pHandler->m_pThread = NULL;
     }
 
-    void MyFrame::OnThreadCompletion(wxCommandEvent&)
+    void MyFrame::OnThreadCompletion(wxThreadEvent&)
     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
     }
 
-    void MyFrame::OnThreadUpdate(wxCommandEvent&)
+    void MyFrame::OnThreadUpdate(wxThreadEvent&)
     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
     }
@@ -982,7 +993,10 @@ public:
 
     /**
         Returns the platform specific thread ID of the current thread as a long.
+
         This can be used to uniquely identify threads, even if they are not wxThreads.
+
+        @see GetMainId()
     */
     static wxThreadIdType GetCurrentId();
 
@@ -1000,6 +1014,15 @@ public:
     */
     wxThreadKind GetKind() const;
 
+    /**
+        Returns the thread ID of the main thread.
+
+        @see IsMain()
+
+        @since 2.9.1
+     */
+    static wxThreadIdType GetMainId();
+
     /**
         Gets the priority of the thread, between zero and 100.
 
@@ -1028,6 +1051,11 @@ public:
 
     /**
         Returns @true if the calling thread is the main application thread.
+
+        Main thread in the context of wxWidgets is the one which initialized
+        the library.
+
+        @see GetMainId(), GetCurrentId()
     */
     static bool IsMain();
 
@@ -1505,6 +1533,9 @@ public:
         Locks the mutex object.
         This is equivalent to LockTimeout() with infinite timeout.
 
+        Note that if this mutex is already locked by the caller thread,
+        this function doesn't block but rather immediately returns.
+
         @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK.
     */
     wxMutexError Lock();