\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
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
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
\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}
{
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);
}
}