Some work on GTK focus handling and events.

[wxWidgets.git] / docs / latex / wx / tevent.tex

diff --git a/docs/latex/wx/tevent.tex b/docs/latex/wx/tevent.tex
index 718f2eaae18d92ca97261fe82dbd1e06f9c38a56..ed4760d0fcdc1b87747d0a5aa0e293898d1d8159 100644 (file)
--- a/docs/latex/wx/tevent.tex
+++ b/docs/latex/wx/tevent.tex
@@ -12,7 +12,7 @@ From wxWindows 2.0, {\it event tables} are used instead, with a few exceptions.
 
 An event table is placed in an implementation file to tell wxWindows how to map
 events to member functions. These member functions are not virtual functions, but
 
 An event table is placed in an implementation file to tell wxWindows how to map
 events to member functions. These member functions are not virtual functions, but

-they all similar in form: they take a single wxEvent-derived argument, and have a void return
+they are all similar in form: they take a single wxEvent-derived argument, and have a void return

 type.
 
 Here's an example of an event table.
 type.
 
 Here's an example of an event table.


@@ -70,8 +70,9 @@ protected:
 
 \subsection{How events are processed}\label{eventprocessing}
 
 
 \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
 
 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


@@ -136,10 +137,27 @@ recursively applied to the parent window's event handler. If this returns TRUE,
 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
 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
+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.
 
 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
 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


@@ -184,19 +202,22 @@ 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.
 
 will have to be written that will override ProcessEvent() in order to pass
 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.
+% VZ: it doesn't work like this, but just in case we ever reenable this
+%     behaviour, I leave it here
+%
+% \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}
 
 
 \subsection{Pluggable event handlers}
 


@@ -235,7 +256,7 @@ in, such as a frame and its children. You may use the wxID\_OK identifier, for e
 any number of dialogs so long as you don't have several within the same dialog.
 
 If you pass -1 to a window constructor, an identifier will be generated for you, but beware:
 any number of dialogs so long as you don't have several within the same dialog.
 
 If you pass -1 to a window constructor, an identifier will be generated for you, but beware:

-if things don't respond in the way they should, it could be because of an id conflict. It's safer
+if things don't respond in the way they should, it could be because of an id conflict. It is safer

 to supply window ids at all times. Automatic generation of identifiers starts at 1 so may well conflict
 with your own identifiers.
 
 to supply window ids at all times. Automatic generation of identifiers starts at 1 so may well conflict
 with your own identifiers.
 


@@ -325,9 +346,9 @@ called via \helpref{wxWindow::Close}{wxwindowclose}.}
 \twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles
 file drop events.}
 \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.}
 \twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles
 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 keybaord focus events.}
-\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard
-input for any window.}
+\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, 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{\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


@@ -338,7 +359,7 @@ to handle dialog initialisation.}
 mouse events or all mouse events.}
 \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.}
 \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.}
 mouse events or all mouse events.}
 \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.}
 \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
+\twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from 

 \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
 \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