| 1 | \section{Event handling overview}\label{eventhandlingoverview} |
| 2 | |
| 3 | Classes: \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow}, \helpref{wxEvent}{wxevent} |
| 4 | |
| 5 | \subsection{Introduction}\label{eventintroduction} |
| 6 | |
| 7 | Before version 2.0 of wxWidgets, events were handled by the application |
| 8 | either by supplying callback functions, or by overriding virtual member |
| 9 | functions such as {\bf OnSize}. |
| 10 | |
| 11 | From wxWidgets 2.0, {\it event tables} are used instead, with a few exceptions. |
| 12 | |
| 13 | An event table is placed in an implementation file to tell wxWidgets how to map |
| 14 | events to member functions. These member functions are not virtual functions, but |
| 15 | they are all similar in form: they take a single wxEvent-derived argument, and have a void return |
| 16 | type. |
| 17 | |
| 18 | Here's an example of an event table. |
| 19 | |
| 20 | \begin{verbatim} |
| 21 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) |
| 22 | EVT_MENU (wxID_EXIT, MyFrame::OnExit) |
| 23 | EVT_MENU (DO_TEST, MyFrame::DoTest) |
| 24 | EVT_SIZE ( MyFrame::OnSize) |
| 25 | EVT_BUTTON (BUTTON1, MyFrame::OnButton1) |
| 26 | END_EVENT_TABLE() |
| 27 | \end{verbatim} |
| 28 | |
| 29 | The first two entries map menu commands to two different member functions. The |
| 30 | EVT\_SIZE macro doesn't need a window identifier, since normally you are only |
| 31 | interested in the current window's size events. |
| 32 | |
| 33 | The EVT\_BUTTON macro demonstrates that the originating event does not have to |
| 34 | come from the window class implementing the event table -- if the event source |
| 35 | is a button within a panel within a frame, this will still work, because event |
| 36 | tables are searched up through the hierarchy of windows for the command events. |
| 37 | In this case, the button's event table will be searched, then the parent |
| 38 | panel's, then the frame's. |
| 39 | |
| 40 | As mentioned before, the member functions that handle events do not have to be |
| 41 | virtual. Indeed, the member functions should not be virtual as the event |
| 42 | handler ignores that the functions are virtual, i.e. overriding a virtual |
| 43 | member function in a derived class will not have any effect. These member |
| 44 | functions take an event argument, and the class of event differs according to |
| 45 | the type of event and the class of the originating window. For size events, |
| 46 | \helpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most |
| 47 | control commands (such as button presses), |
| 48 | \helpref{wxCommandEvent}{wxcommandevent} is used. When controls get more |
| 49 | complicated, then specific event classes are used, such as |
| 50 | \helpref{wxTreeEvent}{wxtreeevent} for events from |
| 51 | \helpref{wxTreeCtrl}{wxtreectrl} windows. |
| 52 | |
| 53 | As well as the event table in the implementation file, there must also be a |
| 54 | DECLARE\_EVENT\_TABLE macro somewhere in the class declaration. For example: |
| 55 | |
| 56 | {\small% |
| 57 | \begin{verbatim} |
| 58 | class MyFrame : public wxFrame |
| 59 | { |
| 60 | public: |
| 61 | ... |
| 62 | void OnExit(wxCommandEvent& event); |
| 63 | void OnSize(wxSizeEvent& event); |
| 64 | |
| 65 | protected: |
| 66 | int m_count; |
| 67 | ... |
| 68 | |
| 69 | DECLARE_EVENT_TABLE() |
| 70 | }; |
| 71 | \end{verbatim} |
| 72 | }% |
| 73 | |
| 74 | Note that this macro may occur in any section of the class (public, protected |
| 75 | or private) but that it is probably better to insert it at the end, as shown, |
| 76 | because this macro implicitly changes the access to protected which may be |
| 77 | quite unexpected if there is anything following it. |
| 78 | |
| 79 | Finally, if you don't like using macros for static initialization of the event |
| 80 | tables you may also use \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} to |
| 81 | connect the events to the handlers dynamically, during run-time. See the |
| 82 | \helpref{event sample}{sampleevent} for an example of doing it. |
| 83 | |
| 84 | |
| 85 | \subsection{How events are processed}\label{eventprocessing} |
| 86 | |
| 87 | When an event is received from the windowing system, wxWidgets calls |
| 88 | \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on the first |
| 89 | event handler object belonging to the window generating the event. |
| 90 | |
| 91 | It may be noted that wxWidgets' event processing system implements something |
| 92 | very close to virtual methods in normal C++, i.e. it is possible to alter |
| 93 | the behaviour of a class by overriding its event handling functions. In |
| 94 | many cases this works even for changing the behaviour of native controls. |
| 95 | For example it is possible to filter out a number of key events sent by the |
| 96 | system to a native text control by overriding wxTextCtrl and defining a |
| 97 | handler for key events using EVT\_KEY\_DOWN. This would indeed prevent |
| 98 | any key events from being sent to the native control - which might not be |
| 99 | what is desired. In this case the event handler function has to call Skip() |
| 100 | so as to indicate that the search for the event handler should continue. |
| 101 | |
| 102 | To summarize, instead of explicitly calling the base class version as you |
| 103 | would have done with C++ virtual functions (i.e. {\it wxTextCtrl::OnChar()}), |
| 104 | you should instead call \helpref{Skip}{wxeventskip}. |
| 105 | |
| 106 | In practice, this would look like this if the derived text control only |
| 107 | accepts 'a' to 'z' and 'A' to 'Z': |
| 108 | |
| 109 | {\small% |
| 110 | \begin{verbatim} |
| 111 | void MyTextCtrl::OnChar(wxKeyEvent& event) |
| 112 | { |
| 113 | if ( isalpha( event.KeyCode() ) ) |
| 114 | { |
| 115 | // key code is within legal range. we call event.Skip() so the |
| 116 | // event can be processed either in the base wxWidgets class |
| 117 | // or the native control. |
| 118 | |
| 119 | event.Skip(); |
| 120 | } |
| 121 | else |
| 122 | { |
| 123 | // illegal key hit. we don't call event.Skip() so the |
| 124 | // event is not processed anywhere else. |
| 125 | |
| 126 | wxBell(); |
| 127 | } |
| 128 | } |
| 129 | \end{verbatim} |
| 130 | }% |
| 131 | |
| 132 | |
| 133 | The normal order of event table searching by ProcessEvent is as follows: |
| 134 | |
| 135 | \begin{enumerate}\itemsep=0pt |
| 136 | \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) |
| 137 | the function skips to step (6). |
| 138 | \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp |
| 139 | \helpref{wxValidator}{wxvalidator}. If this returns true, the function exits. |
| 140 | \item {\bf SearchEventTable} is called for this event handler. If this fails, the base |
| 141 | class table is tried, and so on until no more tables exist or an appropriate function was found, |
| 142 | in which case the function exits. |
| 143 | \item The search is applied down the entire chain of event handlers (usually the chain has a length |
| 144 | of one). If this succeeds, the function exits. |
| 145 | \item If the object is a wxWindow and the event is set to set to propagate (in the library only |
| 146 | wxCommandEvent based events are set to propagate), {\bf ProcessEvent} is recursively applied |
| 147 | to the parent window's event handler. If this returns true, the function exits. |
| 148 | \item Finally, {\bf ProcessEvent} is called on the wxApp object. |
| 149 | \end{enumerate} |
| 150 | |
| 151 | {\bf Pay close attention to Step 5.} People often overlook or get |
| 152 | confused by this powerful feature of the wxWidgets event processing |
| 153 | system. To put it a different way, events set to propagate |
| 154 | (\helpref{See: wxEvent::ShouldPropagate}{wxeventshouldpropagate}) |
| 155 | (most likely derived either directly or indirectly from wxCommandEvent) |
| 156 | will travel up the containment hierarchy from child to parent until the |
| 157 | maximal propagation level is reached or an event handler is found that |
| 158 | doesn't call \helpref{event.Skip()}{wxeventskip}. |
| 159 | |
| 160 | Finally, there is another additional complication (which, in fact, simplifies |
| 161 | life of wxWidgets programmers significantly): when propagating the command |
| 162 | events upwards to the parent window, the event propagation stops when it |
| 163 | reaches the parent dialog, if any. This means that you don't risk to get |
| 164 | unexpected events from the dialog controls (which might be left unprocessed by |
| 165 | the dialog itself because it doesn't care about them) when a modal dialog is |
| 166 | popped up. The events do propagate beyond the frames, however. The rationale |
| 167 | for this choice is that there are only a few frames in a typical application |
| 168 | and their parent-child relation are well understood by the programmer while it |
| 169 | may be very difficult, if not impossible, to track down all the dialogs which |
| 170 | may be popped up in a complex program (remember that some are created |
| 171 | automatically by wxWidgets). If you need to specify a different behaviour for |
| 172 | some reason, you can use |
| 173 | \helpref{SetExtraStyle(wxWS\_EX\_BLOCK\_EVENTS)}{wxwindowsetextrastyle} |
| 174 | explicitly to prevent the events from being propagated beyond the given window |
| 175 | or unset this flag for the dialogs which have it on by default. |
| 176 | |
| 177 | Typically events that deal with a window as a window (size, motion, |
| 178 | paint, mouse, keyboard, etc.) are sent only to the window. Events |
| 179 | that have a higher level of meaning and/or are generated by the window |
| 180 | itself, (button click, menu select, tree expand, etc.) are command |
| 181 | events and are sent up to the parent to see if it is interested in the |
| 182 | event. |
| 183 | |
| 184 | Note that your application may wish to override ProcessEvent to redirect processing of |
| 185 | events. This is done in the document/view framework, for example, to allow event handlers |
| 186 | to be defined in the document or view. To test for command events (which will probably |
| 187 | be the only events you wish to redirect), you may use |
| 188 | \helpref{wxEvent::IsCommandEvent}{wxeventiscommandevent} for efficiency, |
| 189 | instead of using the slower run-time type system. |
| 190 | |
| 191 | As mentioned above, only command events are recursively applied to the parents event |
| 192 | handler in the library itself. As this quite often causes confusion for users, |
| 193 | here is a list of system events which will NOT get sent to the parent's event handler: |
| 194 | |
| 195 | \begin{twocollist}\itemsep=0pt |
| 196 | \twocolitem{\helpref{wxEvent}{wxevent}}{The event base class} |
| 197 | \twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event} |
| 198 | \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event} |
| 199 | \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{An erase background event} |
| 200 | \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{A window focus event} |
| 201 | \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{A keypress event} |
| 202 | \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{An idle event} |
| 203 | \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event} |
| 204 | \twocolitem{\helpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event} |
| 205 | \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{A menu event} |
| 206 | \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{A mouse event} |
| 207 | \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{A move event} |
| 208 | \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event} |
| 209 | \twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information} |
| 210 | \twocolitem{\helpref{wxSetCursorEvent}{wxsetcursorevent}}{Used for special cursor processing based on current mouse position} |
| 211 | \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event} |
| 212 | \twocolitem{\helpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)} |
| 213 | \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event} |
| 214 | \end{twocollist} |
| 215 | |
| 216 | In some cases, it might be desired by the programmer to get a certain number |
| 217 | of system events in a parent window, for example all key events sent to, but not |
| 218 | used by, the native controls in a dialog. In this case, a special event handler |
| 219 | will have to be written that will override ProcessEvent() in order to pass |
| 220 | all events (or any selection of them) to the parent window. |
| 221 | |
| 222 | % VZ: it doesn't work like this, but just in case we ever reenable this |
| 223 | % behaviour, I leave it here |
| 224 | % |
| 225 | % \subsection{Redirection of command events to the window with the focus} |
| 226 | % |
| 227 | % The usual upward search through the window hierarchy for command event |
| 228 | % handlers does not always meet an application's requirements. Say you have two |
| 229 | % wxTextCtrl windows in a frame, plus a toolbar with Cut, Copy and Paste |
| 230 | % buttons. To avoid the need to define event handlers in the frame |
| 231 | % and redirect them explicitly to the window with the focus, command events |
| 232 | % are sent to the window with the focus first, for |
| 233 | % menu and toolbar command and UI update events only. This means that |
| 234 | % each window can handle its own commands and UI updates independently. In |
| 235 | % fact wxTextCtrl can handle Cut, Copy, Paste, Undo and Redo commands and UI update |
| 236 | % requests, so no extra coding is required to support them in your menus and |
| 237 | % toolbars. |
| 238 | |
| 239 | \subsection{Pluggable event handlers}\label{pluggablehandlers} |
| 240 | |
| 241 | In fact, you don't have to derive a new class from a window class |
| 242 | if you don't want to. You can derive a new class from wxEvtHandler instead, |
| 243 | defining the appropriate event table, and then call |
| 244 | \rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably, |
| 245 | \rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this |
| 246 | event handler the object that responds to events. This way, you can avoid |
| 247 | a lot of class derivation, and use the same event handler object to |
| 248 | handle events from instances of different classes. If you ever have to call a window's event handler |
| 249 | manually, use the GetEventHandler function to retrieve the window's event handler and use that |
| 250 | to call the member function. By default, GetEventHandler returns a pointer to the window itself |
| 251 | unless an application has redirected event handling using SetEventHandler or PushEventHandler. |
| 252 | |
| 253 | One use of PushEventHandler is to temporarily or permanently change the |
| 254 | behaviour of the GUI. For example, you might want to invoke a dialog editor |
| 255 | in your application that changes aspects of dialog boxes. You can |
| 256 | grab all the input for an existing dialog box, and edit it `in situ', |
| 257 | before restoring its behaviour to normal. So even if the application |
| 258 | has derived new classes to customize behaviour, your utility can indulge |
| 259 | in a spot of body-snatching. It could be a useful technique for on-line |
| 260 | tutorials, too, where you take a user through a serious of steps and |
| 261 | don't want them to diverge from the lesson. Here, you can examine the events |
| 262 | coming from buttons and windows, and if acceptable, pass them through to |
| 263 | the original event handler. Use PushEventHandler/PopEventHandler |
| 264 | to form a chain of event handlers, where each handler processes a different |
| 265 | range of events independently from the other handlers. |
| 266 | |
| 267 | \subsection{Window identifiers}\label{windowids} |
| 268 | |
| 269 | \index{identifiers}\index{wxID}Window identifiers are integers, and are used to |
| 270 | uniquely determine window identity in the event system (though you can use it |
| 271 | for other purposes). In fact, identifiers do not need to be unique |
| 272 | across your entire application just so long as they are unique within a |
| 273 | particular context you're interested in, such as a frame and its children. You |
| 274 | may use the {\tt wxID\_OK} identifier, for example, on any number of dialogs so |
| 275 | long as you don't have several within the same dialog. |
| 276 | |
| 277 | If you pass {\tt wxID\_ANY} to a window constructor, an identifier will be |
| 278 | generated for you automatically by wxWidgets. This is useful when you don't |
| 279 | care about the exact identifier either because you're not going to process the |
| 280 | events from the control being created at all or because you process the events |
| 281 | from all controls in one place (in which case you should specify {\tt wxID\_ANY} |
| 282 | in the event table or \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} call |
| 283 | as well. The automatically generated identifiers are always negative and so |
| 284 | will never conflict with the user-specified identifiers which must be always |
| 285 | positive. |
| 286 | |
| 287 | The following standard identifiers are supplied. You can use wxID\_HIGHEST to |
| 288 | determine the number above which it is safe to define your own identifiers. Or, |
| 289 | you can use identifiers below wxID\_LOWEST. |
| 290 | |
| 291 | \begin{verbatim} |
| 292 | #define wxID_ANY -1 |
| 293 | |
| 294 | #define wxID_LOWEST 4999 |
| 295 | |
| 296 | #define wxID_OPEN 5000 |
| 297 | #define wxID_CLOSE 5001 |
| 298 | #define wxID_NEW 5002 |
| 299 | #define wxID_SAVE 5003 |
| 300 | #define wxID_SAVEAS 5004 |
| 301 | #define wxID_REVERT 5005 |
| 302 | #define wxID_EXIT 5006 |
| 303 | #define wxID_UNDO 5007 |
| 304 | #define wxID_REDO 5008 |
| 305 | #define wxID_HELP 5009 |
| 306 | #define wxID_PRINT 5010 |
| 307 | #define wxID_PRINT_SETUP 5011 |
| 308 | #define wxID_PREVIEW 5012 |
| 309 | #define wxID_ABOUT 5013 |
| 310 | #define wxID_HELP_CONTENTS 5014 |
| 311 | #define wxID_HELP_COMMANDS 5015 |
| 312 | #define wxID_HELP_PROCEDURES 5016 |
| 313 | #define wxID_HELP_CONTEXT 5017 |
| 314 | |
| 315 | #define wxID_CUT 5030 |
| 316 | #define wxID_COPY 5031 |
| 317 | #define wxID_PASTE 5032 |
| 318 | #define wxID_CLEAR 5033 |
| 319 | #define wxID_FIND 5034 |
| 320 | #define wxID_DUPLICATE 5035 |
| 321 | #define wxID_SELECTALL 5036 |
| 322 | #define wxID_DELETE 5037 |
| 323 | #define wxID_REPLACE 5038 |
| 324 | #define wxID_REPLACE_ALL 5039 |
| 325 | #define wxID_PROPERTIES 5040 |
| 326 | |
| 327 | #define wxID_VIEW_DETAILS 5041 |
| 328 | #define wxID_VIEW_LARGEICONS 5042 |
| 329 | #define wxID_VIEW_SMALLICONS 5043 |
| 330 | #define wxID_VIEW_LIST 5044 |
| 331 | #define wxID_VIEW_SORTDATE 5045 |
| 332 | #define wxID_VIEW_SORTNAME 5046 |
| 333 | #define wxID_VIEW_SORTSIZE 5047 |
| 334 | #define wxID_VIEW_SORTTYPE 5048 |
| 335 | |
| 336 | #define wxID_FILE1 5050 |
| 337 | #define wxID_FILE2 5051 |
| 338 | #define wxID_FILE3 5052 |
| 339 | #define wxID_FILE4 5053 |
| 340 | #define wxID_FILE5 5054 |
| 341 | #define wxID_FILE6 5055 |
| 342 | #define wxID_FILE7 5056 |
| 343 | #define wxID_FILE8 5057 |
| 344 | #define wxID_FILE9 5058 |
| 345 | |
| 346 | #define wxID_OK 5100 |
| 347 | #define wxID_CANCEL 5101 |
| 348 | #define wxID_APPLY 5102 |
| 349 | #define wxID_YES 5103 |
| 350 | #define wxID_NO 5104 |
| 351 | #define wxID_STATIC 5105 |
| 352 | |
| 353 | #define wxID_HIGHEST 5999 |
| 354 | \end{verbatim} |
| 355 | |
| 356 | \subsection{Event macros summary}\label{eventmacros} |
| 357 | |
| 358 | \wxheading{Macros listed by event class} |
| 359 | |
| 360 | The documentation for specific event macros is organised by event class. Please refer |
| 361 | to these sections for details. |
| 362 | |
| 363 | \twocolwidtha{8cm}% |
| 364 | \begin{twocollist}\itemsep=0pt |
| 365 | \twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept |
| 366 | activation and deactivation events.} |
| 367 | \twocolitem{\helpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.} |
| 368 | \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure |
| 369 | called via \helpref{wxWindow::Close}{wxwindowclose}.} |
| 370 | \twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles |
| 371 | file drop events.} |
| 372 | \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.} |
| 373 | \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keyboard focus events.} |
| 374 | \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR, EVT\_KEY\_DOWN and |
| 375 | EVT\_KEY\_UP macros handle keyboard input for any window.} |
| 376 | \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events |
| 377 | (to process background tasks, for example).} |
| 378 | \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used |
| 379 | to handle dialog initialisation.} |
| 380 | \twocolitem{\helpref{wxListEvent}{wxlistevent}}{These macros handle \helpref{wxListCtrl}{wxlistctrl} events.} |
| 381 | \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).} |
| 382 | \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual |
| 383 | mouse events or all mouse events.} |
| 384 | \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.} |
| 385 | \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.} |
| 386 | \twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from |
| 387 | \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxSlider}{wxslider},and \helpref{wxSpinButton}{wxspinbutton}.} |
| 388 | \twocolitem{\helpref{wxSetCursorEvent}{wxsetcursorevent}}{The EVT\_SET\_CURSOR macro is used for special cursor processing.} |
| 389 | \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.} |
| 390 | \twocolitem{\helpref{wxSplitterEvent}{wxsplitterevent}}{The EVT\_SPLITTER\_SASH\_POS\_CHANGED, EVT\_SPLITTER\_UNSPLIT |
| 391 | and EVT\_SPLITTER\_DCLICK macros are used to handle the various splitter window events.} |
| 392 | \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle |
| 393 | events informing the application that the user has changed the system colours (Windows only).} |
| 394 | \twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{These macros handle \helpref{wxTreeCtrl}{wxtreectrl} events.} |
| 395 | \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface |
| 396 | update pseudo-events, which are generated to give the application the chance to update the visual state of menus, |
| 397 | toolbars and controls.} |
| 398 | \end{twocollist} |
| 399 | |
| 400 | \subsection{Custom event summary}\label{customevents} |
| 401 | |
| 402 | \wxheading{General approach} |
| 403 | |
| 404 | Since version 2.2.x of wxWidgets, each event type is identified by ID which |
| 405 | is given to the event type {\it at runtime} which makes it possible to add |
| 406 | new event types to the library or application without risking ID clashes |
| 407 | (two different event types mistakingly getting the same event ID). This |
| 408 | event type ID is stored in a struct of type {\bf const wxEventType}. |
| 409 | |
| 410 | In order to define a new event type, there are principally two choices. |
| 411 | One is to define a entirely new event class (typically deriving from |
| 412 | \helpref{wxEvent}{wxevent} or \helpref{wxCommandEvent}{wxcommandevent}. |
| 413 | The other is to use the existing event classes and give them an new event |
| 414 | type. You'll have to define and declare a new event type using either way, |
| 415 | and this is done using the following macros: |
| 416 | |
| 417 | \begin{verbatim} |
| 418 | // in the header of the source file |
| 419 | DECLARE_EVENT_TYPE(name, value) |
| 420 | |
| 421 | // in the implementation |
| 422 | DEFINE_EVENT_TYPE(name) |
| 423 | \end{verbatim} |
| 424 | |
| 425 | You can ignore the {\it value} parameter of the DECLARE\_EVENT\_TYPE macro |
| 426 | since it used only for backwards compatibility with wxWidgets 2.0.x based |
| 427 | applications where you have to give the event type ID an explicit value. |
| 428 | |
| 429 | \wxheading{Using existing event classes} |
| 430 | |
| 431 | If you just want to use a \helpref{wxCommandEvent}{wxcommandevent} with |
| 432 | a new event type, you can then use one of the generic event table macros |
| 433 | listed below, without having to define a new macro yourself. This also |
| 434 | has the advantage that you won't have to define a new \helpref{wxEvent::Clone()}{wxeventclone} |
| 435 | method for posting events between threads etc. This could look like this |
| 436 | in your code: |
| 437 | |
| 438 | {\small% |
| 439 | \begin{verbatim} |
| 440 | DECLARE_EVENT_TYPE(wxEVT_MY_EVENT, -1) |
| 441 | |
| 442 | DEFINE_EVENT_TYPE(wxEVT_MY_EVENT) |
| 443 | |
| 444 | // user code intercepting the event |
| 445 | |
| 446 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) |
| 447 | EVT_MENU (wxID_EXIT, MyFrame::OnExit) |
| 448 | // .... |
| 449 | EVT_COMMAND (ID_MY_WINDOW, wxEVT_MY_EVENT, MyFrame::OnMyEvent) |
| 450 | END_EVENT_TABLE() |
| 451 | |
| 452 | void MyFrame::OnMyEvent( wxCommandEvent &event ) |
| 453 | { |
| 454 | // do something |
| 455 | wxString text = event.GetText(); |
| 456 | } |
| 457 | |
| 458 | |
| 459 | // user code sending the event |
| 460 | |
| 461 | void MyWindow::SendEvent() |
| 462 | { |
| 463 | wxCommandEvent event( wxEVT_MY_EVENT, GetId() ); |
| 464 | event.SetEventObject( this ); |
| 465 | // Give it some contents |
| 466 | event.SetText( wxT("Hallo") ); |
| 467 | // Send it |
| 468 | GetEventHandler()->ProcessEvent( event ); |
| 469 | } |
| 470 | \end{verbatim} |
| 471 | }% |
| 472 | |
| 473 | |
| 474 | \wxheading{Generic event table macros} |
| 475 | |
| 476 | \twocolwidtha{8cm}% |
| 477 | \begin{twocollist}\itemsep=0pt |
| 478 | \twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table |
| 479 | entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier, |
| 480 | and a member function to call.} |
| 481 | \twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM, |
| 482 | but responds to a range of window identifiers.} |
| 483 | \twocolitem{\windowstyle{EVT\_COMMAND(id, event, func)}}{The same as EVT\_CUSTOM, but |
| 484 | expects a member function with a wxCommandEvent argument.} |
| 485 | \twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but |
| 486 | expects a member function with a wxCommandEvent argument.} |
| 487 | \twocolitem{\windowstyle{EVT\_NOTIFY(id, event, func)}}{The same as EVT\_CUSTOM, but |
| 488 | expects a member function with a wxNotifyEvent argument.} |
| 489 | \twocolitem{\windowstyle{EVT\_NOTIFY\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but |
| 490 | expects a member function with a wxNotifyEvent argument.} |
| 491 | \end{twocollist} |
| 492 | |
| 493 | |
| 494 | \wxheading{Defining your own event class} |
| 495 | |
| 496 | Under certain circumstances, it will be required to define your own event |
| 497 | class e.g. for sending more complex data from one place to another. Apart |
| 498 | from defining your event class, you will also need to define your own |
| 499 | event table macro (which is quite long). Watch out to put in enough |
| 500 | casts to the inherited event function. Here is an example, taken mostly |
| 501 | from the {\it wxPlot} library, which is in the {\it contrib} section of |
| 502 | the wxWidgets sources. |
| 503 | |
| 504 | {\small% |
| 505 | \begin{verbatim} |
| 506 | |
| 507 | // code defining event |
| 508 | |
| 509 | class wxPlotEvent: public wxNotifyEvent |
| 510 | { |
| 511 | public: |
| 512 | wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 ); |
| 513 | |
| 514 | // accessors |
| 515 | wxPlotCurve *GetCurve() |
| 516 | { return m_curve; } |
| 517 | |
| 518 | // required for sending with wxPostEvent() |
| 519 | wxEvent* Clone(); |
| 520 | |
| 521 | private: |
| 522 | wxPlotCurve *m_curve; |
| 523 | }; |
| 524 | |
| 525 | DECLARE_EVENT_MACRO( wxEVT_PLOT_ACTION, -1 ) |
| 526 | |
| 527 | typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&); |
| 528 | |
| 529 | #define EVT_PLOT(id, fn) \ |
| 530 | DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \ |
| 531 | (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \ |
| 532 | wxStaticCastEvent( wxPlotEventFunction, & fn ), (wxObject *) NULL ), |
| 533 | |
| 534 | |
| 535 | // code implementing the event type and the event class |
| 536 | |
| 537 | DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION ) |
| 538 | |
| 539 | wxPlotEvent::wxPlotEvent( ... |
| 540 | |
| 541 | |
| 542 | // user code intercepting the event |
| 543 | |
| 544 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) |
| 545 | EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot) |
| 546 | END_EVENT_TABLE() |
| 547 | |
| 548 | void MyFrame::OnPlot( wxPlotEvent &event ) |
| 549 | { |
| 550 | wxPlotCurve *curve = event.GetCurve(); |
| 551 | } |
| 552 | |
| 553 | |
| 554 | // user code sending the event |
| 555 | |
| 556 | void MyWindow::SendEvent() |
| 557 | { |
| 558 | wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() ); |
| 559 | event.SetEventObject( this ); |
| 560 | event.SetCurve( m_curve ); |
| 561 | GetEventHandler()->ProcessEvent( event ); |
| 562 | } |
| 563 | |
| 564 | \end{verbatim} |
| 565 | }% |
| 566 | |