check in the 'selective yield' patch (see ticket #10320):

- implements YieldFor() with event filtering for wxMSW and wxGTK,
  adds TODO markers in other ports;
- replaces wxYield() in GTK's clipboard code with a wxTheApp->YieldFor() call, thus fixing possible reentrancies 
(and modifies clipboard sample to test synchronous IsSupported calls)
- replaces wxYieldIfNeeded() calls in wxProgressDialog with wxTheApp->YieldFor() calls, so that it processes only 
UI/user-input events, thus fixing the race condition visible in the "thread" sample
- documents the new functions


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

interface/wx/event.h

@@ -7,6 +7,64 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    The predefined constants for the number of times we propagate event
+    upwards window child-parent chain.
+*/
+enum wxEventPropagation
+{
+    /// don't propagate it at all
+    wxEVENT_PROPAGATE_NONE = 0,
+
+    /// propagate it until it is processed
+    wxEVENT_PROPAGATE_MAX = INT_MAX
+};
+
+/**
+    The different categories for a wxEvent; see wxEvent::GetEventCategory.
+
+    @note They are used as OR-combinable flags by wxApp::Yield.
+*/
+enum wxEventCategory
+{
+    /**
+        This is the category for those events which are generated to update
+        the appearance of the GUI but which (usually) do not comport data
+        processing, i.e. which do not provide input or output data
+        (e.g. size events, scroll events, etc).
+        They are events NOT directly generated by the user's input devices.
+    */
+    wxEVT_CATEGORY_UI = 1,
+
+    /**
+        This category groups those events which are generated directly from the
+        user through input devices like mouse and keyboard and usually result in
+        data to be processed from the application
+        (e.g. mouse clicks, key presses, etc).
+    */
+    wxEVT_CATEGORY_USER_INPUT = 2,
+
+    /// This category is for wxSocketEvent
+    wxEVT_CATEGORY_SOCKET = 4,
+
+    /// This category is for wxTimerEvent
+    wxEVT_CATEGORY_TIMER = 8,
+
+    /**
+        This category is for any event used to send notifications from the
+        secondary threads to the main one or in general for notifications among
+        different threads (which may or may not be user-generated).
+    */
+    wxEVT_CATEGORY_THREAD = 16,
+
+    /**
+        This mask is used in wxApp::Yield to specify that all event categories should
+        be processed.
+    */
+    wxEVT_CATEGORY_ALL =
+        wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT|wxEVT_CATEGORY_SOCKET| \
+        wxEVT_CATEGORY_TIMER|wxEVT_CATEGORY_THREAD
+};
 
 /**
     @class wxEvent
@@ -87,6 +145,13 @@ public:
     */
     wxEventType GetEventType() const;
 
+    /**
+        Returns a generic category for this event.
+
+        This function is used to selectively process events in wxApp::Yield.
+    */
+    virtual wxEventCategory GetEventCategory() const;
+
     /**
         Returns the identifier associated with this event, such as a button command id.
     */
@@ -2463,18 +2528,45 @@ public:
 };
 
 
+/**
+    @class wxThreadEvent
 
+    This class adds some simple functionalities to wxCommandEvent coinceived
+    for inter-threads communications.
 
-enum wxHelpEventOrigin
+    @library{wxcore}
+    @category{events}
+
+    @see @ref overview_thread, wxApp::YieldFor
+*/
+class wxThreadEvent : public wxCommandEvent
 {
-    wxHE_ORIGIN_UNKNOWN = -1,
-    wxHE_ORIGIN_KEYBOARD,
+public:
+    /**
+        Constructor.
 
-    /** event generated by wxContextHelp or from the [?] button on
-        the title bar (Windows). */
-    wxHE_ORIGIN_HELPBUTTON
+        Initializes the event type to @c wxEVT_THREAD (but you can change it
+        using wxEvent::SetEventType.
+    */
+    wxThreadEvent(int id = wxID_ANY);
+
+    /**
+        Clones this event making sure that all internal members which use
+        COW (only @c m_commandString for now; see @ref overview_refcount)
+        are unshared (see wxObject::UnShare).
+    */
+    virtual wxEvent *Clone() const;
+
+    /**
+        Returns @c wxEVT_CATEGORY_THREAD.
+
+        This is important to avoid that calling wxApp::Yield() thread events
+        gets processed when this is unwanted:
+    */
+    virtual wxEventCategory GetEventCategory() const;
 };
 
+
 /**
     @class wxHelpEvent