fixed bug in mouse handling

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

diff --git a/docs/latex/wx/tevent.tex b/docs/latex/wx/tevent.tex
index 2b67f2cfa3e8808f2cd8ea71779bce27ed530915..d322a350fbb68d03a8f1bdbe272dcf63bda5fe92 100644 (file)
--- a/docs/latex/wx/tevent.tex
+++ b/docs/latex/wx/tevent.tex
@@ -82,7 +82,11 @@ system to a native text control by overriding wxTextCtrl and defining a
 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()
 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':
 
 In practice, this would look like this if the derived text control only
 accepts 'a' to 'z' and 'A' to 'Z':


@@ -96,14 +100,14 @@ void MyTextCtrl::OnChar(wxKeyEvent& event)
        // 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.
        // 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.
     }
     else
     {
        // illegal key hit. we don't call event.Skip() so the
        // event is not processed anywhere else.

-       
+

        wxBell();
     }
 }
        wxBell();
     }
 }


@@ -128,9 +132,26 @@ recursively applied to the parent window's event handler. If this returns TRUE,
 \item Finally, {\bf ProcessEvent} is called on the wxApp object.
 \end{enumerate}
 
 \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
+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.
+
+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
 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
 
 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


@@ -152,6 +173,7 @@ events which will NOT get sent to the parent's event handler:
 \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{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}
 \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
 \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}
 \end{twocollist}


@@ -160,7 +182,24 @@ In some cases, it might be desired by the programmer to get a certain number
 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
 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.
+
+% 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}
 


@@ -199,7 +238,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.
 


@@ -289,7 +328,7 @@ 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{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{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events
 \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard
 input for any window.}
 \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events


@@ -301,15 +340,17 @@ to handle dialog initialisation.}
 \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{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{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}.}
+\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{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{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}
 
 \end{twocollist}