From e4b713a278375619150b76eebb04be1eae889564 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Mon, 8 Oct 2001 16:46:01 +0000
Subject: [PATCH] added and documented wxWS_EX_BLOCK_EVENTS flag

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@11887 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/tevent.tex | 26 ++++++++++++++++++++++----
 docs/latex/wx/window.tex |  6 ++++++
 include/wx/defs.h        |  7 +++++++
 src/common/dlgcmn.cpp    |  6 ++++++
 src/common/event.cpp     | 10 ++++++----
 5 files changed, 47 insertions(+), 8 deletions(-)

diff --git a/docs/latex/wx/tevent.tex b/docs/latex/wx/tevent.tex
index bc3b3607fb..ed4760d0fc 100644
--- a/docs/latex/wx/tevent.tex
+++ b/docs/latex/wx/tevent.tex
@@ -70,8 +70,9 @@ protected:
 
 \subsection{How events are processed}\label{eventprocessing}
 
-When an event is received from the windowing system, wxWindows calls \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on
-the first event handler object belonging to the window generating the event.
+When an event is received from the windowing system, wxWindows calls 
+\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on the first
+event handler object belonging to the window generating the event.
 
 It may be noted that wxWindows' event processing system implements something
 very close to virtual methods in normal C++, i.e. it is possible to alter
@@ -140,6 +141,23 @@ hierarchy from child to parent until an event handler is found that
 doesn't call event.Skip().  Events not derived from wxCommandEvent are
 sent only to the window they occurred in and then stop.
 
+Finally, there is another additional complication (which, in fact, simplifies
+life of wxWindows programmers significantly): when propagating the command
+events upwards to the parent window, the event propagation stops when it
+reaches the parent dialog, if any. This means that you don't risk to get
+unexpected events from the dialog controls (which might be left unprocessed by
+the dialog itself because it doesn't care about them) when a modal dialog is
+popped up. The events do propagate beyond the frames, however. The rationale
+for this choice is that there are only a few frames in a typical application
+and their parent-child relation are well understood by the programmer while it
+may be very difficult, if not impossible, to track down all the dialogs which
+may be popped up in a complex program (remember that some are created
+automatically by wxWindows). If you need to specify a different behaviour for
+some reason, you can use 
+\helpref{SetExtraStyle(wxWS\_EX\_BLOCK\_EVENTS)}{wxwindowsetextrastyle} 
+explicitly to prevent the events from being propagated beyond the given window
+or unset this flag for the dialogs which have it on by default.
+
 Typically events that deal with a window as a window (size, motion,
 paint, mouse, keyboard, etc.) are sent only to the window.  Events
 that have a higher level of meaning and/or are generated by the window
@@ -329,8 +347,8 @@ called via \helpref{wxWindow::Close}{wxwindowclose}.}
 file drop events.}
 \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.}
 \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keyboard focus events.}
-\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard
-input for any window.}
+\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR, EVT\_KEY\_DOWN and
+EVT\_KEY\_UP macros handle keyboard input for any window.}
 \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events
 (to process background tasks, for example).}
 \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used
diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index f35f9406a6..77e76e7270 100644
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -2062,6 +2062,12 @@ bits are:
 \twocolitem{\windowstyle{wxWS\_EX\_VALIDATE\_RECURSIVELY}}{TransferDataTo/FromWindow()
 and Validate() methods will recursively descend into all children of the
 window if it has this style flag set.}
+\twocolitem{\windowstyle{wxWS\_EX\_BLOCK\_EVENTS}}{Normally, the command
+events are propagared upwards to the window parent recursively until a handler
+for them is found. Using this style allows to prevent them from being
+propagated beyond this window. Notice that wxDialog has this style on by
+default for the reasons explained in the 
+\helpref{event processing overview}{eventprocessing}.}
 \end{twocollist}
 
 \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus}
diff --git a/include/wx/defs.h b/include/wx/defs.h
index 1438ff0cf9..7fbae0d9ed 100644
--- a/include/wx/defs.h
+++ b/include/wx/defs.h
@@ -970,6 +970,13 @@ enum wxBorder
 // descend into all subwindows
 #define wxWS_EX_VALIDATE_RECURSIVELY    0x00000001
 
+// wxCommandEvents and the objects of the derived classes are forwarded to the
+// parent window and so on recursively by default. Using this flag for the
+// given window allows to block this propagation at this window, i.e. prevent
+// the events from being propagated further upwards. The dialogs have this
+// flag on by default.
+#define wxWS_EX_BLOCK_EVENTS            0x00000002
+
 /*
  * wxFrame/wxDialog style flags
  */
diff --git a/src/common/dlgcmn.cpp b/src/common/dlgcmn.cpp
index 3688684b37..04ad2b6756 100644
--- a/src/common/dlgcmn.cpp
+++ b/src/common/dlgcmn.cpp
@@ -57,6 +57,12 @@ WX_DELEGATE_TO_CONTROL_CONTAINER(wxDialogBase)
 void wxDialogBase::Init()
 {
     m_returnCode = 0;
+
+    // the dialogs have this flag on by default to prevent the events from the
+    // dialog controls from reaching the parent frame which is usually
+    // undesirable and can lead to unexpected and hard to find bugs
+    SetExtraStyle(GetExtraStyle() | wxWS_EX_BLOCK_EVENTS);
+
 #ifdef wxTopLevelWindowNative // FIXME - temporary hack, should be always used!
     m_container.SetContainerWindow(this);
 #endif
diff --git a/src/common/event.cpp b/src/common/event.cpp
index e9a76b3fd2..02c63cc4fa 100644
--- a/src/common/event.cpp
+++ b/src/common/event.cpp
@@ -1001,12 +1001,14 @@ bool wxEvtHandler::ProcessEvent(wxEvent& event)
     {
         wxWindow *win = (wxWindow *)this;
 
-        // also, don't propagate events beyond the first top level window: it
-        // doesn't make sense to process dialogs events in the parent frame
-        if ( !win->IsTopLevel() )
+        // honour the requests to stop propagation at this window: this is
+        // used by the dialogs, for example, to prevent processing the events
+        // from the dialog controls in the parent frame which rarely, if ever,
+        // makes sense
+        if ( !(win->GetExtraStyle() & wxWS_EX_BLOCK_EVENTS) )
         {
             wxWindow *parent = win->GetParent();
-            if (parent && !parent->IsBeingDeleted())
+            if ( parent && !parent->IsBeingDeleted() )
                 return parent->GetEventHandler()->ProcessEvent(event);
         }
     }
-- 
2.50.0

