fix wxWindow::PushEventHandler and related wxWindow functions for the stack management; currently they don't work well when passing event handlers which are part of an event handler chain (see wx-dev thread 'wxWindow event handler stack'); implement wxEvtHandler Unlink() and IsUnlinked() functions and document them; revise docs of all involved functions of both wxEvtHandler and wxWindow, adding images for better explanations

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

include/wx/event.h

@@ -2668,14 +2668,27 @@ public:
     wxEvtHandler();
     virtual ~wxEvtHandler();
 
+
+    // Event handler chain
+    // -------------------
+
     wxEvtHandler *GetNextHandler() const { return m_nextHandler; }
     wxEvtHandler *GetPreviousHandler() const { return m_previousHandler; }
-    void SetNextHandler(wxEvtHandler *handler) { m_nextHandler = handler; }
-    void SetPreviousHandler(wxEvtHandler *handler) { m_previousHandler = handler; }
+    virtual void SetNextHandler(wxEvtHandler *handler) { m_nextHandler = handler; }
+    virtual void SetPreviousHandler(wxEvtHandler *handler) { m_previousHandler = handler; }
 
     void SetEvtHandlerEnabled(bool enabled) { m_enabled = enabled; }
     bool GetEvtHandlerEnabled() const { return m_enabled; }
 
+    void Unlink();
+    bool IsUnlinked() const;
+
+
+
+    // Event queuing and processing
+    // ----------------------------
+
+
     // Process an event right now: this can only be called from the main
     // thread, use QueueEvent() for scheduling the events for
     // processing from other threads.
@@ -2686,6 +2699,7 @@ public:
     // when called from C code (e.g. in GTK+ callback) when the exception
     // wouldn't correctly propagate to wxEventLoop.
     bool SafelyProcessEvent(wxEvent& event);
+        // NOTE: uses ProcessEvent()
 
     // Schedule the given event to be processed later. It takes ownership of
     // the event pointer, i.e. it will be deleted later. This is safe to call
@@ -2708,11 +2722,17 @@ public:
     }
 
     void ProcessPendingEvents();
+        // NOTE: uses ProcessEvent()
 
 #if wxUSE_THREADS
     bool ProcessThreadEvent(const wxEvent& event);
+        // NOTE: uses AddPendingEvent()
 #endif
 
+
+    // Connecting and disconnecting
+    // ----------------------------
+
     // Dynamic association of a member function handler with the event handler,
     // winid and event type
     void Connect(int winid,