handler for key events using EVT\_KEY\_DOWN. This would indeed prevent
any key events from being sent to the native control - which might not be
what is desired. In this case the event handler function has to call Skip()
-so as to indicate that it did NOT handle the event at all.
+so as to indicate that the search for the event handler should continue.
+
+To summarize, instead of explicitly calling the base class version as you
+would have done with C++ virtual functions (i.e. {\it wxTextCtrl::OnChar()}),
+you should instead call \helpref{Skip}{wxeventskip}.
In practice, this would look like this if the derived text control only
accepts 'a' to 'z' and 'A' to 'Z':
// key code is within legal range. we call event.Skip() so the
// event can be processed either in the base wxWindows class
// or the native control.
-
- event.Skip();
+
+ event.Skip();
}
else
{
// illegal key hit. we don't call event.Skip() so the
// event is not processed anywhere else.
-
+
wxBell();
}
}
\item Finally, {\bf ProcessEvent} is called on the wxApp object.
\end{enumerate}
+{\bf Pay close attention to Step 5.} People often overlook or get
+confused by this powerful feature of the wxWindows event processing
+system. To put it a different way, events derived either directly or
+indirectly from wxCommandEvent will travel up the containment
+heirarchy 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.
+
+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
+itself, (button click, menu select, tree expand, etc.) are command
+events and are sent up to the parent to see if it is interested in the
+event.
+
Note that your application may wish to override ProcessEvent to redirect processing of
events. This is done in the document/view framework, for example, to allow event handlers
-to be defined in the document or view.
+to be defined in the document or view. To test for command events (which will probably
+be the only events you wish to redirect), you may use wxEvent::IsCommandEvent for
+efficiency, instead of using the slower run-time type system.
As mentioned above, only command events are recursively applied to the parents event
handler. As this quite often causes confusion for users, here is a list of system
\twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event}
\twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information}
\twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event}
+\twocolitem{\helpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)}
\twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}
\end{twocollist}
of system events in a parent window, for example all key events sent to, but not
used by, the native controls in a dialog. In this case, a special event handler
will have to be written that will override ProcessEvent() in order to pass
-all events (or any selection of them) to the parent window. See next section.
+all events (or any selection of them) to the parent window.
+
+\subsection{Redirection of command events to the window with the focus}
+
+The usual upward search through the window hierarchy for command event
+handlers does not always meet an application's requirements. Say you have two
+wxTextCtrl windows in a frame, plus a toolbar with Cut, Copy and Paste
+buttons. To avoid the need to define event handlers in the frame
+and redirect them explicitly to the window with the focus, command events
+are sent to the window with the focus first, for
+menu and toolbar command and UI update events only. This means that
+each window can handle its own commands and UI updates independently. In
+fact wxTextCtrl can handle Cut, Copy, Paste, Undo and Redo commands and UI update
+requests, so no extra coding is required to support them in your menus and
+toolbars.
\subsection{Pluggable event handlers}
\twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual
mouse events or all mouse events.}
\twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.}
-\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface
-update pseudo-events, which are generated to give the application the chance to update the visual state of menus,
-toolbars and controls.}
\twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.}
\twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from
-windows, \helpref{wxScrollBar}{wxscrollbar}, and \helpref{wxSpinButton}{wxspinbutton}.}
+\helpref{wxScrollBar}{wxscrollbar}, \helpref{wxSlider}{wxslider},and \helpref{wxSpinButton}{wxspinbutton}.}
\twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.}
+\twocolitem{\helpref{wxSplitterEvent}{wxsplitterevent}}{The EVT\_SPLITTER\_SASH\_POS\_CHANGED, EVT\_SPLITTER\_UNSPLIT
+and EVT\_SPLITTER\_DOUBLECLICKED macros are used to handle the various splitter window events.}
\twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle
events informing the application that the user has changed the system colours (Windows only).}
\twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{These macros handle \helpref{wxTreeCtrl}{wxtreectrl} events.}
+\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface
+update pseudo-events, which are generated to give the application the chance to update the visual state of menus,
+toolbars and controls.}
\end{twocollist}
projects / wxWidgets.git / blobdiff