deprecate the old TryValidator/Parent() and replace them with the new and documented TryBefore/After()

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

include/wx/docmdi.h

@@ -44,7 +44,7 @@ public:
 protected:
     void Init();
 
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
     wxDocManager *m_docManager;
 
@@ -89,7 +89,7 @@ public:
 protected:
     void Init();
 
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
     wxDocument*       m_childDocument;
     wxView*           m_childView;

include/wx/docview.h

@@ -107,7 +107,7 @@ public:
     // modified to false)
     virtual bool OnSaveModified();
 
-    // if you override, remember to call the default 
+    // if you override, remember to call the default
     // implementation (wxDocument::OnChangeFilename)
     virtual void OnChangeFilename(bool notifyViews);
 
@@ -243,7 +243,7 @@ public:
 
 protected:
     // hook the document into event handlers chain here
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
     wxDocument*       m_viewDocument;
     wxString          m_viewTypeName;
@@ -467,7 +467,7 @@ public:
 
 protected:
     // hook the currently active view into event handlers chain here
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
     // return the command processor for the current document, if any
     wxCommandProcessor *GetCurrentCommandProcessor() const;
@@ -528,7 +528,7 @@ public:
 
 protected:
     // hook the child view into event handlers chain here
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
     wxDocument*       m_childDocument;
     wxView*           m_childView;
@@ -573,7 +573,7 @@ public:
 
 protected:
     // hook the document manager into event handling chain here
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
     wxDocManager *m_docManager;
 

include/wx/event.h

@@ -3067,7 +3067,7 @@ public:
     //
     // It is meant to be called from ProcessEvent() only and is not virtual,
     // additional event handlers can be hooked into the normal event processing
-    // logic using TryValidator() hook.
+    // logic using TryBefore() and TryAfter() hooks.
     bool ProcessEventHere(wxEvent& event);
 
 
@@ -3090,21 +3090,42 @@ protected:
     // hooks for wxWindow used by ProcessEvent()
     // -----------------------------------------
 
-    // This one is called before trying our own event table to allow plugging
-    // in the validators.
-    //
-    // NB: This method is intentionally *not* inside wxUSE_VALIDATORS!
-    //     It is part of wxBase which doesn't use validators and the code
-    //     is compiled out when building wxBase w/o GUI classes, which affects
-    //     binary compatibility and wxBase library can't be used by GUI
-    //     ports.
-    virtual bool TryValidator(wxEvent& WXUNUSED(event)) { return false; }
+    // this one is called before trying our own event table to allow plugging
+    // in the event handlers overriding the default logic, this is used by e.g.
+    // validators.
+    virtual bool TryBefore(wxEvent& event)
+    {
+#ifdef WXWIN_COMPATIBILITY_2_8
+        // call the old virtual function to keep the code overriding it working
+        return TryValidator(event);
+#else
+        wxUnusedVar(event);
+        return false;
+#endif
+    }
 
     // this one is called after failing to find the event handle in our own
     // table to give a chance to the other windows to process it
     //
     // base class implementation passes the event to wxTheApp
-    virtual bool TryParent(wxEvent& event);
+    virtual bool TryAfter(wxEvent& event)
+    {
+#ifdef WXWIN_COMPATIBILITY_2_8
+        // as above, call the old virtual function for compatibility
+        return TryParent(event);
+#else
+        return DoTryApp(event);
+#endif
+    }
+
+#ifdef WXWIN_COMPATIBILITY_2_8
+    // deprecated method: override TryBefore() instead of this one
+    wxDEPRECATED_BUT_USED_INTERNALLY_INLINE(
+        virtual bool TryValidator(wxEvent& WXUNUSED(event)), return false; )
+
+    wxDEPRECATED_BUT_USED_INTERNALLY_INLINE(
+        virtual bool TryParent(wxEvent& event), return DoTryApp(event); )
+#endif // WXWIN_COMPATIBILITY_2_8
 
 
     static const wxEventTable sm_eventTable;
@@ -3152,6 +3173,9 @@ protected:
     wxEventConnectionRef *FindRefInTrackerList(wxEvtHandler *eventSink);
 
 private:
+    // pass the event to wxTheApp instance, called from TryAfter()
+    bool DoTryApp(wxEvent& event);
+
     DECLARE_DYNAMIC_CLASS_NO_COPY(wxEvtHandler)
 };
 

include/wx/generic/mdig.h

@@ -172,7 +172,7 @@ public:
     virtual wxString GetTitle() const { return m_title; }
     virtual void SetTitle(const wxString& title);
 
-    virtual bool TryParent(wxEvent& event);
+    virtual bool TryAfter(wxEvent& event);
 
     // implementation only from now on
 

include/wx/msw/mdi.h

@@ -109,7 +109,7 @@ public:
 
 protected:
     // override to pass menu/toolbar events to the active child first
-    virtual bool TryValidator(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
 
 #if wxUSE_MENUS_NATIVE
     virtual void InternalSetMenuBar();

include/wx/window.h

@@ -1408,8 +1408,8 @@ public:
 
 protected:
     // event handling specific to wxWindow
-    virtual bool TryValidator(wxEvent& event);
-    virtual bool TryParent(wxEvent& event);
+    virtual bool TryBefore(wxEvent& event);
+    virtual bool TryAfter(wxEvent& event);
 
     enum WindowOrder
     {