added and documented wxWindow::RemoveEventHandler()

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

docs/latex/wx/window.tex

@@ -1776,6 +1776,29 @@ functions so should not be required by the application programmer.
 
 \docparam{child}{Child window to remove.}
 
+\membersection{wxWindow::RemoveEventHandler}{wxwindowremoveeventhandler}
+
+\func{bool}{RemoveEventHandler}{\param{wxEvtHandler *}{handler}}
+
+Find the given {\it handler} in the windows event handler chain and remove (but
+not delete) it from it.
+
+\wxheading{Parameters}
+
+\docparam{handler}{The event handler to remove, must be non {\tt NULL} and
+must be present in this windows event handlers chain}
+
+\wxheading{Return value}
+
+Returns {\tt TRUE} if it was found and {\tt FALSE} otherwise (this also results
+in an assert failure so this function should only be called when the
+handler is supposed to be there).
+
+\wxheading{See also}
+
+\helpref{PushEventHandler}{wxwindowpusheventhandler},\rtfsp
+\helpref{PopEventHandler}{wxwindowpopeventhandler}
+
 \membersection{wxWindow::Reparent}\label{wxwindowreparent}
 
 \func{virtual bool}{Reparent}{\param{wxWindow* }{newParent}}

include/wx/window.h

@@ -403,6 +403,13 @@ public:
     void PushEventHandler( wxEvtHandler *handler );
     wxEvtHandler *PopEventHandler( bool deleteHandler = FALSE );
 
+        // find the given handler in the event handler chain and remove (but
+        // not delete) it from the event handler chain, return TRUE if it was
+        // found and FALSE otherwise (this also results in an assert failure so
+        // this function should only be called when the handler is supposed to
+        // be there)
+    bool RemoveEventHandler(wxEvtHandler *handler);
+
     // validators
     // ----------
 

src/common/wincmn.cpp

@@ -633,6 +633,41 @@ wxEvtHandler *wxWindowBase::PopEventHandler(bool deleteHandler)
     return handlerA;
 }
 
+bool wxWindowBase::RemoveEventHandler(wxEvtHandler *handler)
+{
+    wxCHECK_MSG( handler, FALSE, _T("RemoveEventHandler(NULL) called") );
+
+    wxEvtHandler *handlerPrev = NULL,
+                 *handlerCur = GetEventHandler();
+    while ( handlerCur )
+    {
+        wxEvtHandler *handlerNext = handlerCur->GetNextHandler();
+
+        if ( handlerCur == handler )
+        {
+            if ( handlerPrev )
+            {
+                handlerPrev->SetNextHandler(handlerNext);
+            }
+            else
+            {
+                SetEventHandler(handlerNext);
+            }
+
+            handler->SetNextHandler(NULL);
+
+            return TRUE;
+        }
+
+        handlerPrev = handlerCur;
+        handlerCur = handlerNext;
+    }
+
+    wxFAIL_MSG( _T("where has the event handler gone?") );
+
+    return FALSE;
+}
+
 // ----------------------------------------------------------------------------
 // cursors, fonts &c
 // ----------------------------------------------------------------------------