X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/397f14ce524d02bef903c3f186f1554e630467c2..cc4a1ce1f58b46cb4c4d6a1319192062140b9373:/docs/latex/book/chap_basic_events.tex diff --git a/docs/latex/book/chap_basic_events.tex b/docs/latex/book/chap_basic_events.tex index f4ef86d94d..dfa56b2b77 100644 --- a/docs/latex/book/chap_basic_events.tex +++ b/docs/latex/book/chap_basic_events.tex @@ -3,5 +3,351 @@ \setheader{{\it CHAPTER \thechapter: BASIC EVENT HANDLING}}{}{}{}{}{{\it CHAPTER \thechapter: BASIC EVENT HANDLING}}% \setfooter{\thepage}{}{}{}{}{\thepage}% -In which Pooh and Piglet come upon the sticky topic of event handling, and ask Owl to help. +\section{Introduction} + +In most cases, wxWindows uses the concept of {\it event tables} to catch user input. + +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 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. + +\begin{verbatim} +BEGIN_EVENT_TABLE(MyFrame, wxFrame) + EVT_MENU (wxID_EXIT, MyFrame::OnExit) + EVT_MENU (DO_TEST, MyFrame::DoTest) + EVT_SIZE ( MyFrame::OnSize) + EVT_BUTTON (BUTTON1, MyFrame::OnButton1) +END_EVENT_TABLE() +\end{verbatim} + +The first two entries map menu commands to two different member functions. The EVT\_SIZE macro +doesn't need a window identifier, since normally you are only interested in the +current window's size events. (In fact you could intercept a particular window's size event +by using EVT\_CUSTOM(wxEVT\_SIZE, id, func).) + +The EVT\_BUTTON macro demonstrates that the originating event does not have to come from +the window class implementing the event table - if the event source is a button within a panel within a frame, this will still +work, because event tables are searched up through the hierarchy of windows. In this +case, the button's event table will be searched, then the parent panel's, then the frame's. + +As mentioned before, the member functions that handle events do not have to be virtual. +Indeed, the member functions should not be virtual as the event handler ignores that +the functions are virtual, i.e. overriding a virtual member function in a derived class +will not have any effect. +These member functions take an event argument, and the class of event differs according +to the type of event and the class of the originating window. For size +events, \wxhelpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most control +commands (such as button presses), \wxhelpref{wxCommandEvent}{wxcommandevent} is used. +When controls get more complicated, then specific event classes are used, such +as \wxhelpref{wxTreeEvent}{wxtreeevent} for events from \wxhelpref{wxTreeCtrl}{wxtreectrl} windows. + +As well as the event table in the implementation file, there must be a DECLARE\_EVENT\_TABLE +macro in the class definition. For example: + +{\small% +\begin{verbatim} +class MyFrame: public wxFrame { + + DECLARE_DYNAMIC_CLASS(MyFrame) + +public: + ... + void OnExit(wxCommandEvent& event); + void OnSize(wxSizeEvent& event); +protected: + int m_count; + ... + DECLARE_EVENT_TABLE() +}; +\end{verbatim} +}% + +\section{How events are processed}\label{eventprocessing} + +When an event is received from the windowing system, wxWindows calls \wxhelpref{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 +the behaviour of a class by overriding its event handling functions. In +many cases this works even for changing the behaviour of native controls. +For example it is possible to filter out a number of key events sent by the +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() +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 \wxhelpref{wxEvent::Skip}{wxeventskip}. + +In practice, this would look like the following if the derived text control only +accepts 'a' to 'z' and 'A' to 'Z': + +{\small% +\begin{verbatim} +void MyTextCtrl::OnChar(wxKeyEvent& event) +{ + if ( isalpha( event.KeyCode() ) ) + { + // 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(); + } + else + { + // illegal key hit. we don't call event.Skip() so the + // event is not processed anywhere else. + + wxBell(); + } +} +\end{verbatim} +}% + + +The normal order of event table searching by ProcessEvent is as follows: + +\begin{enumerate}\itemsep=0pt +\item If the object is disabled (via a call to \wxhelpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) +the function skips to step (6). +\item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp +\wxhelpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits. +\item {\bf SearchEventTable} is called for this event handler. If this fails, the base +class table is tried, and so on until no more tables exist or an appropriate function was found, +in which case the function exits. +\item The search is applied down the entire chain of event handlers (usually the chain has a length +of one). If this succeeds, the function exits. +\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is +recursively applied to the parent window's event handler. If this returns TRUE, the function exits. +\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 +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 +events which will {\it not} get sent to the parent's event handler: + +\begin{twocollist}\itemsep=0pt +\twocolitem{\wxhelpref{wxEvent}{wxevent}}{The event base class} +\twocolitem{\wxhelpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event} +\twocolitem{\wxhelpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event} +\twocolitem{\wxhelpref{wxEraseEvent}{wxeraseevent}}{An erase background event} +\twocolitem{\wxhelpref{wxFocusEvent}{wxfocusevent}}{A window focus event} +\twocolitem{\wxhelpref{wxKeyEvent}{wxkeyevent}}{A keypress event} +\twocolitem{\wxhelpref{wxIdleEvent}{wxidleevent}}{An idle event} +\twocolitem{\wxhelpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event} +\twocolitem{\wxhelpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event} +\twocolitem{\wxhelpref{wxMenuEvent}{wxmenuevent}}{A menu event} +\twocolitem{\wxhelpref{wxMouseEvent}{wxmouseevent}}{A mouse event} +\twocolitem{\wxhelpref{wxMoveEvent}{wxmoveevent}}{A move event} +\twocolitem{\wxhelpref{wxPaintEvent}{wxpaintevent}}{A paint event} +\twocolitem{\wxhelpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information} +\twocolitem{\wxhelpref{wxSizeEvent}{wxsizeevent}}{A size event} +\twocolitem{\wxhelpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)} +\twocolitem{\wxhelpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event} +\twocolitem{\wxhelpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event} +\end{twocollist} + +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 +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 +% +% \section{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. + +\section{Pluggable event handlers} + +In fact, you don't have to derive a new class from a window class +if you don't want to. You can derive a new class from wxEvtHandler instead, +defining the appropriate event table, and then call +\rtfsp\wxhelpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably, +\rtfsp\wxhelpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this +event handler the object that responds to events. This way, you can avoid +a lot of class derivation, and use the same event handler object to +handle events from instances of different classes. If you ever have to call a window's event handler +manually, use the GetEventHandler function to retrieve the window's event handler and use that +to call the member function. By default, GetEventHandler returns a pointer to the window itself +unless an application has redirected event handling using SetEventHandler or PushEventHandler. + +One use of PushEventHandler is to temporarily or permanently change the +behaviour of the GUI. For example, you might want to invoke a dialog editor +in your application that changes aspects of dialog boxes. You can +grab all the input for an existing dialog box, and edit it `in situ', +before restoring its behaviour to normal. So even if the application +has derived new classes to customize behaviour, your utility can indulge +in a spot of body-snatching. It could be a useful technique for on-line +tutorials, too, where you take a user through a serious of steps and +don't want them to diverge from the lesson. Here, you can examine the events +coming from buttons and windows, and if acceptable, pass them through to +the original event handler. Use PushEventHandler/PopEventHandler +to form a chain of event handlers, where each handler processes a different +range of events independently from the other handlers. + +\section{Window identifiers}\label{windowids} + +\index{identifiers}\index{wxID}Window identifiers are integers, and are used to uniquely determine window identity in the +event system (though you can use it for other purposes). In fact, identifiers do not need +to be unique across your entire application just so long as they are unique within a particular context you're interested +in, such as a frame and its children. You may use the wxID\_OK identifier, for example, on +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 is safer +to supply window ids at all times. Automatic generation of identifiers starts at 1 so may well conflict +with your own identifiers. + +The following standard identifiers are supplied. You can use wxID\_HIGHEST to determine the +number above which it is safe to define your own identifiers. Or, you can use identifiers below +wxID\_LOWEST. + +\begin{verbatim} +#define wxID_LOWEST 4999 + +#define wxID_OPEN 5000 +#define wxID_CLOSE 5001 +#define wxID_NEW 5002 +#define wxID_SAVE 5003 +#define wxID_SAVEAS 5004 +#define wxID_REVERT 5005 +#define wxID_EXIT 5006 +#define wxID_UNDO 5007 +#define wxID_REDO 5008 +#define wxID_HELP 5009 +#define wxID_PRINT 5010 +#define wxID_PRINT_SETUP 5011 +#define wxID_PREVIEW 5012 +#define wxID_ABOUT 5013 +#define wxID_HELP_CONTENTS 5014 +#define wxID_HELP_COMMANDS 5015 +#define wxID_HELP_PROCEDURES 5016 +#define wxID_HELP_CONTEXT 5017 + +#define wxID_CUT 5030 +#define wxID_COPY 5031 +#define wxID_PASTE 5032 +#define wxID_CLEAR 5033 +#define wxID_FIND 5034 +#define wxID_DUPLICATE 5035 +#define wxID_SELECTALL 5036 + +#define wxID_FILE1 5050 +#define wxID_FILE2 5051 +#define wxID_FILE3 5052 +#define wxID_FILE4 5053 +#define wxID_FILE5 5054 +#define wxID_FILE6 5055 +#define wxID_FILE7 5056 +#define wxID_FILE8 5057 +#define wxID_FILE9 5058 + +#define wxID_OK 5100 +#define wxID_CANCEL 5101 +#define wxID_APPLY 5102 +#define wxID_YES 5103 +#define wxID_NO 5104 +#define wxID_STATIC 5105 + +#define wxID_HIGHEST 5999 +\end{verbatim} + +\section{Event macros summary}\label{eventmacros} + +\wxheading{Generic event table macros} + +\twocolwidtha{8cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table +entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier, +and a member function to call.} +\twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM, +but responds to a range of window identifiers.} +\twocolitem{\windowstyle{EVT\_COMMAND(id, event, func)}}{The same as EVT\_CUSTOM, but +expects a member function with a wxCommandEvent argument.} +\twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but +expects a member function with a wxCommandEvent argument.} +\end{twocollist} + +\wxheading{Macros listed by event class} + +The documentation for specific event macros is organised by event class. Please refer +to these sections for details. + +\twocolwidtha{8cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{\wxhelpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept +activation and deactivation events.} +\twocolitem{\wxhelpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.} +\twocolitem{\wxhelpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure +called via \wxhelpref{wxWindow::Close}{wxwindowclose}.} +\twocolitem{\wxhelpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles +file drop events.} +\twocolitem{\wxhelpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.} +\twocolitem{\wxhelpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keyboard focus events.} +\twocolitem{\wxhelpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard +input for any window.} +\twocolitem{\wxhelpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events +(to process background tasks, for example).} +\twocolitem{\wxhelpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used +to handle dialog initialisation.} +\twocolitem{\wxhelpref{wxListEvent}{wxlistevent}}{These macros handle \wxhelpref{wxListCtrl}{wxlistctrl} events.} +\twocolitem{\wxhelpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).} +\twocolitem{\wxhelpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual +mouse events or all mouse events.} +\twocolitem{\wxhelpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.} +\twocolitem{\wxhelpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.} +\twocolitem{\wxhelpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from +\wxhelpref{wxScrollBar}{wxscrollbar}, \wxhelpref{wxSlider}{wxslider},and \wxhelpref{wxSpinButton}{wxspinbutton}.} +\twocolitem{\wxhelpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.} +\twocolitem{\wxhelpref{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{\wxhelpref{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{\wxhelpref{wxTreeEvent}{wxtreeevent}}{These macros handle \wxhelpref{wxTreeCtrl}{wxtreectrl} events.} +\twocolitem{\wxhelpref{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}