]> git.saurik.com Git - wxWidgets.git/blob - interface/event.h
further revision (done by me)
[wxWidgets.git] / interface / event.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: event.h
3 // Purpose: interface of wx*Event classes
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxKeyEvent
11 @wxheader{event.h}
12
13 This event class contains information about keypress (character) events.
14
15 Notice that there are three different kinds of keyboard events in wxWidgets:
16 key down and up events and char events. The difference between the first two
17 is clear - the first corresponds to a key press and the second to a key
18 release - otherwise they are identical. Just note that if the key is
19 maintained in a pressed state you will typically get a lot of (automatically
20 generated) down events but only one up so it is wrong to assume that there is
21 one up event corresponding to each down one.
22
23 Both key events provide untranslated key codes while the char event carries
24 the translated one. The untranslated code for alphanumeric keys is always
25 an upper case value. For the other keys it is one of @c WXK_XXX values
26 from the @ref page_keycodes.
27 The translated key is, in general, the character the user expects to appear
28 as the result of the key combination when typing the text into a text entry
29 zone, for example.
30
31 A few examples to clarify this (all assume that CAPS LOCK is unpressed
32 and the standard US keyboard): when the @c 'A' key is pressed, the key down
33 event key code is equal to @c ASCII A == 65. But the char event key code
34 is @c ASCII a == 97. On the other hand, if you press both SHIFT and
35 @c 'A' keys simultaneously , the key code in key down event will still be
36 just @c 'A' while the char event key code parameter will now be @c 'A'
37 as well.
38
39 Although in this simple case it is clear that the correct key code could be
40 found in the key down event handler by checking the value returned by
41 wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as
42 for non-alphanumeric keys the translation is keyboard-layout dependent and
43 can only be done properly by the system itself.
44
45 Another kind of translation is done when the control key is pressed: for
46 example, for CTRL-A key press the key down event still carries the
47 same key code @c 'a' as usual but the char event will have key code of 1,
48 the ASCII value of this key combination.
49
50 You may discover how the other keys on your system behave interactively by
51 running the @ref page_samples_text wxWidgets sample and pressing some keys
52 in any of the text controls shown in it.
53
54 @b Tip: be sure to call @c event.Skip() for events that you don't process in
55 key event function, otherwise menu shortcuts may cease to work under Windows.
56
57 @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
58 does not call @c event.Skip() then the corresponding char event
59 (@c EVT_CHAR) will not happen.
60 This is by design and enables the programs that handle both types of
61 events to be a bit simpler.
62
63 @note For Windows programmers: The key and char events in wxWidgets are
64 similar to but slightly different from Windows @c WM_KEYDOWN and
65 @c WM_CHAR events. In particular, Alt-x combination will generate a
66 char event in wxWidgets (unless it is used as an accelerator).
67
68
69 @beginEventTable{wxKeyEvent}
70 @event{EVT_KEY_DOWN(func)}:
71 Process a wxEVT_KEY_DOWN event (any key has been pressed).
72 @event{EVT_KEY_UP(func)}:
73 Process a wxEVT_KEY_UP event (any key has been released).
74 @event{EVT_CHAR(func)}:
75 Process a wxEVT_CHAR event.
76 @endEventTable
77
78 @library{wxcore}
79 @category{events}
80 */
81 class wxKeyEvent : public wxEvent
82 {
83 public:
84 /**
85 Constructor.
86 Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
87 */
88 wxKeyEvent(wxEventType keyEventType = wxEVT_NULL);
89
90 /**
91 Returns @true if the Alt key was down at the time of the key event.
92
93 Notice that GetModifiers() is easier to use correctly than this function
94 so you should consider using it in new code.
95 */
96 bool AltDown() const;
97
98 /**
99 CMD is a pseudo key which is the same as Control for PC and Unix
100 platforms but the special APPLE (a.k.a as COMMAND) key under Macs:
101 it makes often sense to use it instead of, say, ControlDown() because Cmd
102 key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still
103 exists, just not used for this purpose under Mac). So for non-Mac platforms
104 this is the same as ControlDown() and under Mac this is the same as MetaDown().
105 */
106 bool CmdDown() const;
107
108 /**
109 Returns @true if the control key was down at the time of the key event.
110
111 Notice that GetModifiers() is easier to use correctly than this function
112 so you should consider using it in new code.
113 */
114 bool ControlDown() const;
115
116 /**
117 Returns the virtual key code. ASCII events return normal ASCII values,
118 while non-ASCII events return values such as @b WXK_LEFT for the left cursor
119 key. See @ref page_keycodes for a full list of the virtual key codes.
120
121 Note that in Unicode build, the returned value is meaningful only if the
122 user entered a character that can be represented in current locale's default
123 charset. You can obtain the corresponding Unicode character using GetUnicodeKey().
124 */
125 int GetKeyCode() const;
126
127 /**
128 Return the bitmask of modifier keys which were pressed when this event
129 happened. See @ref page_keymodifiers for the full list of modifiers.
130
131 Notice that this function is easier to use correctly than, for example,
132 ControlDown() because when using the latter you also have to remember to
133 test that none of the other modifiers is pressed:
134
135 @code
136 if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
137 ... handle Ctrl-XXX ...
138 @endcode
139
140 and forgetting to do it can result in serious program bugs (e.g. program
141 not working with European keyboard layout where ALTGR key which is seen by
142 the program as combination of CTRL and ALT is used). On the other hand,
143 you can simply write:
144
145 @code
146 if ( GetModifiers() == wxMOD_CONTROL )
147 ... handle Ctrl-XXX ...
148 @endcode
149
150 with this function.
151 */
152 int GetModifiers() const;
153
154 //@{
155 /**
156 Obtains the position (in client coordinates) at which the key was pressed.
157 */
158 wxPoint GetPosition() const;
159 void GetPosition(long* x, long* y) const;
160 //@}
161
162 /**
163 Returns the raw key code for this event. This is a platform-dependent scan code
164 which should only be used in advanced applications.
165
166 @note Currently the raw key codes are not supported by all ports, use
167 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
168 */
169 wxUint32 GetRawKeyCode() const;
170
171 /**
172 Returns the low level key flags for this event. The flags are
173 platform-dependent and should only be used in advanced applications.
174
175 @note Currently the raw key flags are not supported by all ports, use
176 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
177 */
178 wxUint32 GetRawKeyFlags() const;
179
180 /**
181 Returns the Unicode character corresponding to this key event.
182
183 This function is only available in Unicode build, i.e. when
184 @c wxUSE_UNICODE is 1.
185 */
186 wxChar GetUnicodeKey() const;
187
188 /**
189 Returns the X position (in client coordinates) of the event.
190 */
191 wxCoord GetX() const;
192
193 /**
194 Returns the Y position (in client coordinates) of the event.
195 */
196 wxCoord GetY() const;
197
198 /**
199 Returns @true if either CTRL or ALT keys was down at the time of the
200 key event.
201
202 Note that this function does not take into account neither SHIFT nor
203 META key states (the reason for ignoring the latter is that it is
204 common for NUMLOCK key to be configured as META under X but the key
205 presses even while NUMLOCK is on should be still processed normally).
206 */
207 bool HasModifiers() const;
208
209 /**
210 Returns @true if the Meta key was down at the time of the key event.
211
212 Notice that GetModifiers() is easier to use correctly than this function
213 so you should consider using it in new code.
214 */
215 bool MetaDown() const;
216
217 /**
218 Returns @true if the shift key was down at the time of the key event.
219
220 Notice that GetModifiers() is easier to use correctly than this function
221 so you should consider using it in new code.
222 */
223 bool ShiftDown() const;
224 };
225
226
227
228 /**
229 @class wxJoystickEvent
230 @wxheader{event.h}
231
232 This event class contains information about joystick events, particularly
233 events received by windows.
234
235 @beginEventTable{wxJoystickEvent}
236 @style{EVT_JOY_BUTTON_DOWN(func)}:
237 Process a wxEVT_JOY_BUTTON_DOWN event.
238 @style{EVT_JOY_BUTTON_UP(func)}:
239 Process a wxEVT_JOY_BUTTON_UP event.
240 @style{EVT_JOY_MOVE(func)}:
241 Process a wxEVT_JOY_MOVE event.
242 @style{EVT_JOY_ZMOVE(func)}:
243 Process a wxEVT_JOY_ZMOVE event.
244 @style{EVT_JOYSTICK_EVENTS(func)}:
245 Processes all joystick events.
246 @endEventTable
247
248 @library{wxcore}
249 @category{events}
250
251 @see wxJoystick
252 */
253 class wxJoystickEvent : public wxEvent
254 {
255 public:
256 /**
257 Constructor.
258 */
259 wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0,
260 int joystick = wxJOYSTICK1,
261 int change = 0);
262
263 /**
264 Returns @true if the event was a down event from the specified button
265 (or any button).
266
267 @param button
268 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
269 indicate any button down event.
270 */
271 bool ButtonDown(int button = wxJOY_BUTTON_ANY) const;
272
273 /**
274 Returns @true if the specified button (or any button) was in a down state.
275
276 @param button
277 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
278 indicate any button down event.
279 */
280 bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const;
281
282 /**
283 Returns @true if the event was an up event from the specified button
284 (or any button).
285
286 @param button
287 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
288 indicate any button down event.
289 */
290 bool ButtonUp(int button = wxJOY_BUTTON_ANY) const;
291
292 /**
293 Returns the identifier of the button changing state.
294
295 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
296 */
297 int GetButtonChange() const;
298
299 /**
300 Returns the down state of the buttons.
301
302 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
303 */
304 int GetButtonState() const;
305
306 /**
307 Returns the identifier of the joystick generating the event - one of
308 wxJOYSTICK1 and wxJOYSTICK2.
309 */
310 int GetJoystick() const;
311
312 /**
313 Returns the x, y position of the joystick event.
314 */
315 wxPoint GetPosition() const;
316
317 /**
318 Returns the z position of the joystick event.
319 */
320 int GetZPosition() const;
321
322 /**
323 Returns @true if this was a button up or down event
324 (@e not 'is any button down?').
325 */
326 bool IsButton() const;
327
328 /**
329 Returns @true if this was an x, y move event.
330 */
331 bool IsMove() const;
332
333 /**
334 Returns @true if this was a z move event.
335 */
336 bool IsZMove() const;
337 };
338
339
340
341 /**
342 @class wxScrollWinEvent
343 @wxheader{event.h}
344
345 A scroll event holds information about events sent from scrolling windows.
346
347
348 @beginEventTable{wxScrollWinEvent}
349 You can use the EVT_SCROLLWIN* macros for intercepting scroll window events
350 from the receiving window.
351 @event{EVT_SCROLLWIN(func)}:
352 Process all scroll events.
353 @event{EVT_SCROLLWIN_TOP(func)}:
354 Process wxEVT_SCROLLWIN_TOP scroll-to-top events.
355 @event{EVT_SCROLLWIN_BOTTOM(func)}:
356 Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
357 @event{EVT_SCROLLWIN_LINEUP(func)}:
358 Process wxEVT_SCROLLWIN_LINEUP line up events.
359 @event{EVT_SCROLLWIN_LINEDOWN(func)}:
360 Process wxEVT_SCROLLWIN_LINEDOWN line down events.
361 @event{EVT_SCROLLWIN_PAGEUP(func)}:
362 Process wxEVT_SCROLLWIN_PAGEUP page up events.
363 @event{EVT_SCROLLWIN_PAGEDOWN(func)}:
364 Process wxEVT_SCROLLWIN_PAGEDOWN page down events.
365 @event{EVT_SCROLLWIN_THUMBTRACK(func)}:
366 Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
367 (frequent events sent as the user drags the thumbtrack).
368 @event{EVT_SCROLLWIN_THUMBRELEASE(func)}:
369 Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
370 @endEventTable
371
372
373 @library{wxcore}
374 @category{events}
375
376 @see wxScrollEvent, @ref overview_eventhandling
377 */
378 class wxScrollWinEvent : public wxEvent
379 {
380 public:
381 /**
382 Constructor.
383 */
384 wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0,
385 int orientation = 0);
386
387 /**
388 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
389 scrollbar.
390
391 @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
392 */
393 int GetOrientation() const;
394
395 /**
396 Returns the position of the scrollbar for the thumb track and release events.
397
398 Note that this field can't be used for the other events, you need to query
399 the window itself for the current position in that case.
400 */
401 int GetPosition() const;
402 };
403
404
405
406 /**
407 @class wxSysColourChangedEvent
408 @wxheader{event.h}
409
410 This class is used for system colour change events, which are generated
411 when the user changes the colour settings using the control panel.
412 This is only appropriate under Windows.
413
414 @remarks
415 The default event handler for this event propagates the event to child windows,
416 since Windows only sends the events to top-level windows.
417 If intercepting this event for a top-level window, remember to call the base
418 class handler, or to pass the event on to the window's children explicitly.
419
420 @beginEventTable{wxSysColourChangedEvent}
421 @event{EVT_SYS_COLOUR_CHANGED(func)}:
422 Process a wxEVT_SYS_COLOUR_CHANGED event.
423 @endEventTable
424
425 @library{wxcore}
426 @category{events}
427
428 @see @ref overview_eventhandling
429 */
430 class wxSysColourChangedEvent : public wxEvent
431 {
432 public:
433 /**
434 Constructor.
435 */
436 wxSysColourChangedEvent();
437 };
438
439
440
441 /**
442 @class wxWindowCreateEvent
443 @wxheader{event.h}
444
445 This event is sent just after the actual window associated with a wxWindow
446 object has been created.
447
448 Since it is derived from wxCommandEvent, the event propagates up
449 the window hierarchy.
450
451 @beginEventTable{wxWindowCreateEvent}
452 @event{EVT_WINDOW_CREATE(func)}:
453 Process a wxEVT_CREATE event.
454 @endEventTable
455
456 @library{wxcore}
457 @category{events}
458
459 @see @ref overview_eventhandling, wxWindowDestroyEvent
460 */
461 class wxWindowCreateEvent : public wxCommandEvent
462 {
463 public:
464 /**
465 Constructor.
466 */
467 wxWindowCreateEvent(wxWindow* win = NULL);
468 };
469
470
471
472 /**
473 @class wxPaintEvent
474 @wxheader{event.h}
475
476 A paint event is sent when a window's contents needs to be repainted.
477
478 Please notice that in general it is impossible to change the drawing of a
479 standard control (such as wxButton) and so you shouldn't attempt to handle
480 paint events for them as even if it might work on some platforms, this is
481 inherently not portable and won't work everywhere.
482
483 @remarks
484 Note that in a paint event handler, the application must always create a
485 wxPaintDC object, even if you do not use it. Otherwise, under MS Windows,
486 refreshing for this and other windows will go wrong.
487 For example:
488 @code
489 void MyWindow::OnPaint(wxPaintEvent& event)
490 {
491 wxPaintDC dc(this);
492
493 DrawMyDocument(dc);
494 }
495 @endcode
496 You can optimize painting by retrieving the rectangles that have been damaged
497 and only repainting these. The rectangles are in terms of the client area,
498 and are unscrolled, so you will need to do some calculations using the current
499 view position to obtain logical, scrolled units.
500 Here is an example of using the wxRegionIterator class:
501 @code
502 // Called when window needs to be repainted.
503 void MyWindow::OnPaint(wxPaintEvent& event)
504 {
505 wxPaintDC dc(this);
506
507 // Find Out where the window is scrolled to
508 int vbX,vbY; // Top left corner of client
509 GetViewStart(&vbX,&vbY);
510
511 int vX,vY,vW,vH; // Dimensions of client area in pixels
512 wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
513
514 while (upd)
515 {
516 vX = upd.GetX();
517 vY = upd.GetY();
518 vW = upd.GetW();
519 vH = upd.GetH();
520
521 // Alternatively we can do this:
522 // wxRect rect(upd.GetRect());
523
524 // Repaint this rectangle
525 ...some code...
526
527 upd ++ ;
528 }
529 }
530 @endcode
531
532
533 @beginEventTable{wxPaintEvent}
534 @event{EVT_PAINT(func)}:
535 Process a wxEVT_PAINT event.
536 @endEventTable
537
538 @library{wxcore}
539 @category{events}
540
541 @see @ref overview_eventhandling
542 */
543 class wxPaintEvent : public wxEvent
544 {
545 public:
546 /**
547 Constructor.
548 */
549 wxPaintEvent(int id = 0);
550 };
551
552
553
554 /**
555 @class wxMaximizeEvent
556 @wxheader{event.h}
557
558 An event being sent when a top level window is maximized. Notice that it is
559 not sent when the window is restored to its original size after it had been
560 maximized, only a normal wxSizeEvent is generated in this case.
561
562 @beginEventTable{wxMaximizeEvent}
563 @event{EVT_MAXIMIZE(func)}:
564 Process a wxEVT_MAXIMIZE event.
565 @endEventTable
566
567 @library{wxcore}
568 @category{events}
569
570 @see @ref overview_eventhandling, wxTopLevelWindow::Maximize,
571 wxTopLevelWindow::IsMaximized
572 */
573 class wxMaximizeEvent : public wxEvent
574 {
575 public:
576 /**
577 Constructor. Only used by wxWidgets internally.
578 */
579 wxMaximizeEvent(int id = 0);
580 };
581
582
583
584 /**
585 @class wxUpdateUIEvent
586 @wxheader{event.h}
587
588 This class is used for pseudo-events which are called by wxWidgets
589 to give an application the chance to update various user interface elements.
590
591 @remarks
592 Without update UI events, an application has to work hard to check/uncheck,
593 enable/disable, show/hide, and set the text for elements such as menu items
594 and toolbar buttons. The code for doing this has to be mixed up with the code
595 that is invoked when an action is invoked for a menu item or button.
596 With update UI events, you define an event handler to look at the state of the
597 application and change UI elements accordingly. wxWidgets will call your member
598 functions in idle time, so you don't have to worry where to call this code.
599 In addition to being a clearer and more declarative method, it also means you don't
600 have to worry whether you're updating a toolbar or menubar identifier. The same
601 handler can update a menu item and toolbar button, if the identifier is the same.
602 Instead of directly manipulating the menu or button, you call functions in the event
603 object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a
604 call has been made, and which UI element to update.
605 These events will work for popup menus as well as menubars. Just before a menu is
606 popped up, wxMenu::UpdateUI is called to process any UI events for the window that
607 owns the menu.
608 If you find that the overhead of UI update processing is affecting your application,
609 you can do one or both of the following:
610 @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED,
611 and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should
612 receive update events. No other windows will receive update events.
613 @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay
614 between updates. You may need to call wxWindow::UpdateWindowUI at critical points,
615 for example when a dialog is about to be shown, in case the user sees a slight
616 delay before windows are updated.
617 Note that although events are sent in idle time, defining a wxIdleEvent handler
618 for a window does not affect this because the events are sent from wxWindow::OnInternalIdle
619 which is always called in idle time.
620 wxWidgets tries to optimize update events on some platforms.
621 On Windows and GTK+, events for menubar items are only sent when the menu is about
622 to be shown, and not in idle time.
623
624 @beginEventTable{wxUpdateUIEvent}
625 @event{EVT_UPDATE_UI(id, func)}:
626 Process a wxEVT_UPDATE_UI event for the command with the given id.
627 @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}:
628 Process a wxEVT_UPDATE_UI event for any command with id included in the given range.
629 @endEventTable
630
631
632 @library{wxcore}
633 @category{events}
634
635 @see @ref overview_eventhandling
636 */
637 class wxUpdateUIEvent : public wxCommandEvent
638 {
639 public:
640 /**
641 Constructor.
642 */
643 wxUpdateUIEvent(wxWindowID commandId = 0);
644
645 /**
646 Returns @true if it is appropriate to update (send UI update events to)
647 this window.
648 This function looks at the mode used (see wxUpdateUIEvent::SetMode),
649 the wxWS_EX_PROCESS_UI_UPDATES flag in @e window,
650 the time update events were last sent in idle time, and
651 the update interval, to determine whether events should be sent to
652 this window now. By default this will always return @true because
653 the update mode is initially wxUPDATE_UI_PROCESS_ALL and
654 the interval is set to 0; so update events will be sent as
655 often as possible. You can reduce the frequency that events
656 are sent by changing the mode and/or setting an update interval.
657
658 @see ResetUpdateTime(), SetUpdateInterval(),
659 SetMode()
660 */
661 static bool CanUpdate(wxWindow* window);
662
663 /**
664 Check or uncheck the UI element.
665 */
666 void Check(bool check);
667
668 /**
669 Enable or disable the UI element.
670 */
671 void Enable(bool enable);
672
673 /**
674 Returns @true if the UI element should be checked.
675 */
676 bool GetChecked() const;
677
678 /**
679 Returns @true if the UI element should be enabled.
680 */
681 bool GetEnabled() const;
682
683 /**
684 Static function returning a value specifying how wxWidgets
685 will send update events: to all windows, or only to those which specify that
686 they
687 will process the events.
688 See SetMode().
689 */
690 static wxUpdateUIMode GetMode();
691
692 /**
693 Returns @true if the application has called Check(). For wxWidgets internal use
694 only.
695 */
696 bool GetSetChecked() const;
697
698 /**
699 Returns @true if the application has called Enable(). For wxWidgets internal use
700 only.
701 */
702 bool GetSetEnabled() const;
703
704 /**
705 Returns @true if the application has called Show(). For wxWidgets internal use
706 only.
707 */
708 bool GetSetShown() const;
709
710 /**
711 Returns @true if the application has called SetText(). For wxWidgets internal
712 use only.
713 */
714 bool GetSetText() const;
715
716 /**
717 Returns @true if the UI element should be shown.
718 */
719 bool GetShown() const;
720
721 /**
722 Returns the text that should be set for the UI element.
723 */
724 wxString GetText() const;
725
726 /**
727 Returns the current interval between updates in milliseconds.
728 -1 disables updates, 0 updates as frequently as possible.
729 See SetUpdateInterval().
730 */
731 static long GetUpdateInterval();
732
733 /**
734 Used internally to reset the last-updated time to the
735 current time. It is assumed that update events are
736 normally sent in idle time, so this is called at the end of
737 idle processing.
738
739 @see CanUpdate(), SetUpdateInterval(),
740 SetMode()
741 */
742 static void ResetUpdateTime();
743
744 /**
745 Specify how wxWidgets will send update events: to
746 all windows, or only to those which specify that they
747 will process the events.
748 @a mode may be one of the following values.
749 The default is wxUPDATE_UI_PROCESS_ALL.
750 */
751 static void SetMode(wxUpdateUIMode mode);
752
753 /**
754 Sets the text for this UI element.
755 */
756 void SetText(const wxString& text);
757
758 /**
759 Sets the interval between updates in milliseconds.
760 Set to -1 to disable updates, or to 0 to update as frequently as possible.
761 The default is 0.
762 Use this to reduce the overhead of UI update events if your application
763 has a lot of windows. If you set the value to -1 or greater than 0,
764 you may also need to call wxWindow::UpdateWindowUI
765 at appropriate points in your application, such as when a dialog
766 is about to be shown.
767 */
768 static void SetUpdateInterval(long updateInterval);
769
770 /**
771 Show or hide the UI element.
772 */
773 void Show(bool show);
774 };
775
776
777
778 /**
779 @class wxClipboardTextEvent
780 @wxheader{event.h}
781
782 This class represents the events generated by a control (typically a
783 wxTextCtrl but other windows can generate these events as
784 well) when its content gets copied or cut to, or pasted from the clipboard.
785 There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY,
786 wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE.
787
788 If any of these events is processed (without being skipped) by an event
789 handler, the corresponding operation doesn't take place which allows to
790 prevent the text from being copied from or pasted to a control. It is also
791 possible to examine the clipboard contents in the PASTE event handler and
792 transform it in some way before inserting in a control -- for example,
793 changing its case or removing invalid characters.
794
795 Finally notice that a CUT event is always preceded by the COPY event which
796 makes it possible to only process the latter if it doesn't matter if the
797 text was copied or cut.
798
799 @beginEventTable{wxClipboardTextEvent}
800 @event{EVT_TEXT_COPY(id, func)}:
801 Some or all of the controls content was copied to the clipboard.
802 @event{EVT_TEXT_CUT(id, func)}:
803 Some or all of the controls content was cut (i.e. copied and
804 deleted).
805 @event{EVT_TEXT_PASTE(id, func)}:
806 Clipboard content was pasted into the control.
807 @endEventTable
808
809 @note
810 These events are currently only generated by wxTextCtrl under GTK+. They
811 are generated by all controls under Windows.
812
813 @library{wxcore}
814 @category{events}
815
816 @see wxClipboard
817 */
818 class wxClipboardTextEvent : public wxCommandEvent
819 {
820 public:
821 /**
822 Constructor.
823 */
824 wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
825 };
826
827
828
829 /**
830 @class wxMouseEvent
831 @wxheader{event.h}
832
833 This event class contains information about the events generated by the mouse:
834 they include mouse buttons press and release events and mouse move events.
835
836 All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the
837 left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and
838 @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more
839 buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events
840 can also be generated. Note that not all mice have even a middle button so a
841 portable application should avoid relying on the events from it (but the right
842 button click can be emulated using the left mouse button with the control key
843 under Mac platforms with a single button mouse).
844
845 For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events
846 purposes, the mouse is considered to be inside the window if it is in the
847 window client area and not inside one of its children. In other words, the
848 parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
849 mouse leaves the window entirely but also when it enters one of its children.
850
851 @note Note that under Windows CE mouse enter and leave events are not natively
852 supported
853 by the system but are generated by wxWidgets itself. This has several
854 drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
855 left the window and the state variables for it may have changed during this
856 time.
857
858 @note Note the difference between methods like
859 wxMouseEvent::LeftDown and
860 wxMouseEvent::LeftIsDown: the former returns @true
861 when the event corresponds to the left mouse button click while the latter
862 returns @true if the left mouse button is currently being pressed. For
863 example, when the user is dragging the mouse you can use
864 wxMouseEvent::LeftIsDown to test
865 whether the left mouse button is (still) depressed. Also, by convention, if
866 wxMouseEvent::LeftDown returns @true,
867 wxMouseEvent::LeftIsDown will also return @true in
868 wxWidgets whatever the underlying GUI behaviour is (which is
869 platform-dependent). The same applies, of course, to other mouse buttons as
870 well.
871
872 @library{wxcore}
873 @category{events}
874
875 @see wxKeyEvent::CmdDown
876 */
877 class wxMouseEvent : public wxEvent
878 {
879 public:
880 /**
881 Constructor. Valid event types are:
882
883 @b wxEVT_ENTER_WINDOW
884 @b wxEVT_LEAVE_WINDOW
885 @b wxEVT_LEFT_DOWN
886 @b wxEVT_LEFT_UP
887 @b wxEVT_LEFT_DCLICK
888 @b wxEVT_MIDDLE_DOWN
889 @b wxEVT_MIDDLE_UP
890 @b wxEVT_MIDDLE_DCLICK
891 @b wxEVT_RIGHT_DOWN
892 @b wxEVT_RIGHT_UP
893 @b wxEVT_RIGHT_DCLICK
894 @b wxEVT_MOUSE_AUX1_DOWN
895 @b wxEVT_MOUSE_AUX1_UP
896 @b wxEVT_MOUSE_AUX1_DCLICK
897 @b wxEVT_MOUSE_AUX2_DOWN
898 @b wxEVT_MOUSE_AUX2_UP
899 @b wxEVT_MOUSE_AUX2_DCLICK
900 @b wxEVT_MOTION
901 @b wxEVT_MOUSEWHEEL
902 */
903 wxMouseEvent(wxEventType mouseEventType = 0);
904
905 /**
906 Returns @true if the Alt key was down at the time of the event.
907 */
908 bool AltDown() const;
909
910 /**
911 Returns @true if the event was a first extra button double click.
912 */
913 bool Aux1DClick() const;
914
915 /**
916 Returns @true if the first extra button mouse button changed to down.
917 */
918 bool Aux1Down() const;
919
920 /**
921 Returns @true if the first extra button mouse button is currently down,
922 independent
923 of the current event type.
924 */
925 bool Aux1IsDown() const;
926
927 /**
928 Returns @true if the first extra button mouse button changed to up.
929 */
930 bool Aux1Up() const;
931
932 /**
933 Returns @true if the event was a second extra button double click.
934 */
935 bool Aux2DClick() const;
936
937 /**
938 Returns @true if the second extra button mouse button changed to down.
939 */
940 bool Aux2Down() const;
941
942 /**
943 Returns @true if the second extra button mouse button is currently down,
944 independent
945 of the current event type.
946 */
947 bool Aux2IsDown() const;
948
949 /**
950 Returns @true if the second extra button mouse button changed to up.
951 */
952 bool Aux2Up() const;
953
954 /**
955 Returns @true if the identified mouse button is changing state. Valid
956 values of @a button are:
957
958 @c wxMOUSE_BTN_LEFT
959
960 check if left button was pressed
961
962 @c wxMOUSE_BTN_MIDDLE
963
964 check if middle button was pressed
965
966 @c wxMOUSE_BTN_RIGHT
967
968 check if right button was pressed
969
970 @c wxMOUSE_BTN_AUX1
971
972 check if the first extra button was pressed
973
974 @c wxMOUSE_BTN_AUX2
975
976 check if the second extra button was pressed
977
978 @c wxMOUSE_BTN_ANY
979
980 check if any button was pressed
981 */
982 bool Button(int button) const;
983
984 /**
985 If the argument is omitted, this returns @true if the event was a mouse
986 double click event. Otherwise the argument specifies which double click event
987 was generated (see Button() for the possible
988 values).
989 */
990 bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const;
991
992 /**
993 If the argument is omitted, this returns @true if the event was a mouse
994 button down event. Otherwise the argument specifies which button-down event
995 was generated (see Button() for the possible
996 values).
997 */
998 bool ButtonDown(int = wxMOUSE_BTN_ANY) const;
999
1000 /**
1001 If the argument is omitted, this returns @true if the event was a mouse
1002 button up event. Otherwise the argument specifies which button-up event
1003 was generated (see Button() for the possible
1004 values).
1005 */
1006 bool ButtonUp(int = wxMOUSE_BTN_ANY) const;
1007
1008 /**
1009 Same as MetaDown() under Mac, same as
1010 ControlDown() elsewhere.
1011
1012 @see wxKeyEvent::CmdDown
1013 */
1014 bool CmdDown() const;
1015
1016 /**
1017 Returns @true if the control key was down at the time of the event.
1018 */
1019 bool ControlDown() const;
1020
1021 /**
1022 Returns @true if this was a dragging event (motion while a button is depressed).
1023
1024 @see Moving()
1025 */
1026 bool Dragging() const;
1027
1028 /**
1029 Returns @true if the mouse was entering the window.
1030 See also Leaving().
1031 */
1032 bool Entering() const;
1033
1034 /**
1035 Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE
1036 if no button is involved (for mouse move, enter or leave event, for example).
1037 Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and
1038 double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT
1039 for the same events for the middle and the right buttons respectively.
1040 */
1041 int GetButton() const;
1042
1043 /**
1044 Returns the number of mouse clicks for this event: 1 for a simple click, 2
1045 for a double-click, 3 for a triple-click and so on.
1046 Currently this function is implemented only in wxMac and returns -1 for the
1047 other platforms (you can still distinguish simple clicks from double-clicks as
1048 they generate different kinds of events however).
1049
1050 @wxsince{2.9.0}
1051 */
1052 int GetClickCount() const;
1053
1054 /**
1055 Returns the configured number of lines (or whatever) to be scrolled per
1056 wheel action. Defaults to three.
1057 */
1058 int GetLinesPerAction() const;
1059
1060 /**
1061 Returns the logical mouse position in pixels (i.e. translated according to the
1062 translation set for the DC, which usually indicates that the window has been
1063 scrolled).
1064 */
1065 wxPoint GetLogicalPosition(const wxDC& dc) const;
1066
1067 //@{
1068 /**
1069 Sets *x and *y to the position at which the event occurred.
1070 Returns the physical mouse position in pixels.
1071 Note that if the mouse event has been artificially generated from a special
1072 keyboard combination (e.g. under Windows when the "menu'' key is pressed), the
1073 returned position is @c wxDefaultPosition.
1074 */
1075 wxPoint GetPosition() const;
1076 const void GetPosition(wxCoord* x, wxCoord* y) const;
1077 const void GetPosition(long* x, long* y) const;
1078 //@}
1079
1080 /**
1081 Get wheel delta, normally 120. This is the threshold for action to be
1082 taken, and one such action (for example, scrolling one increment)
1083 should occur for each delta.
1084 */
1085 int GetWheelDelta() const;
1086
1087 /**
1088 Get wheel rotation, positive or negative indicates direction of
1089 rotation. Current devices all send an event when rotation is at least
1090 +/-WheelDelta, but finer resolution devices can be created in the future.
1091 Because of this you shouldn't assume that one event is equal to 1 line, but you
1092 should be able to either do partial line scrolling or wait until several
1093 events accumulate before scrolling.
1094 */
1095 int GetWheelRotation() const;
1096
1097 /**
1098 Returns X coordinate of the physical mouse event position.
1099 */
1100 wxCoord GetX() const;
1101
1102 /**
1103 Returns Y coordinate of the physical mouse event position.
1104 */
1105 wxCoord GetY() const;
1106
1107 /**
1108 Returns @true if the event was a mouse button event (not necessarily a button
1109 down event -
1110 that may be tested using @e ButtonDown).
1111 */
1112 bool IsButton() const;
1113
1114 /**
1115 Returns @true if the system has been setup to do page scrolling with
1116 the mouse wheel instead of line scrolling.
1117 */
1118 bool IsPageScroll() const;
1119
1120 /**
1121 Returns @true if the mouse was leaving the window.
1122 See also Entering().
1123 */
1124 bool Leaving() const;
1125
1126 /**
1127 Returns @true if the event was a left double click.
1128 */
1129 bool LeftDClick() const;
1130
1131 /**
1132 Returns @true if the left mouse button changed to down.
1133 */
1134 bool LeftDown() const;
1135
1136 /**
1137 Returns @true if the left mouse button is currently down, independent
1138 of the current event type.
1139 Please notice that it is not the same as
1140 LeftDown() which returns @true if the event was
1141 generated by the left mouse button being pressed. Rather, it simply describes
1142 the state of the left mouse button at the time when the event was generated
1143 (so while it will be @true for a left click event, it can also be @true for
1144 a right click if it happened while the left mouse button was pressed).
1145 This event is usually used in the mouse event handlers which process "move
1146 mouse" messages to determine whether the user is (still) dragging the mouse.
1147 */
1148 bool LeftIsDown() const;
1149
1150 /**
1151 Returns @true if the left mouse button changed to up.
1152 */
1153 bool LeftUp() const;
1154
1155 /**
1156 Returns @true if the Meta key was down at the time of the event.
1157 */
1158 bool MetaDown() const;
1159
1160 /**
1161 Returns @true if the event was a middle double click.
1162 */
1163 bool MiddleDClick() const;
1164
1165 /**
1166 Returns @true if the middle mouse button changed to down.
1167 */
1168 bool MiddleDown() const;
1169
1170 /**
1171 Returns @true if the middle mouse button is currently down, independent
1172 of the current event type.
1173 */
1174 bool MiddleIsDown() const;
1175
1176 /**
1177 Returns @true if the middle mouse button changed to up.
1178 */
1179 bool MiddleUp() const;
1180
1181 /**
1182 Returns @true if this was a motion event and no mouse buttons were pressed.
1183 If any mouse button is held pressed, then this method returns @false and
1184 Dragging() returns @true.
1185 */
1186 bool Moving() const;
1187
1188 /**
1189 Returns @true if the event was a right double click.
1190 */
1191 bool RightDClick() const;
1192
1193 /**
1194 Returns @true if the right mouse button changed to down.
1195 */
1196 bool RightDown() const;
1197
1198 /**
1199 Returns @true if the right mouse button is currently down, independent
1200 of the current event type.
1201 */
1202 bool RightIsDown() const;
1203
1204 /**
1205 Returns @true if the right mouse button changed to up.
1206 */
1207 bool RightUp() const;
1208
1209 /**
1210 Returns @true if the shift key was down at the time of the event.
1211 */
1212 bool ShiftDown() const;
1213
1214 /**
1215 bool m_altDown
1216 @true if the Alt key is pressed down.
1217 */
1218
1219
1220 /**
1221 bool m_controlDown
1222 @true if control key is pressed down.
1223 */
1224
1225
1226 /**
1227 bool m_leftDown
1228 @true if the left mouse button is currently pressed down.
1229 */
1230
1231
1232 /**
1233 int m_linesPerAction
1234 The configured number of lines (or whatever) to be scrolled per wheel
1235 action.
1236 */
1237
1238
1239 /**
1240 bool m_metaDown
1241 @true if the Meta key is pressed down.
1242 */
1243
1244
1245 /**
1246 bool m_middleDown
1247 @true if the middle mouse button is currently pressed down.
1248 */
1249
1250
1251 /**
1252 bool m_rightDown
1253 @true if the right mouse button is currently pressed down.
1254 */
1255
1256
1257 /**
1258 bool m_shiftDown
1259 @true if shift is pressed down.
1260 */
1261
1262
1263 /**
1264 int m_wheelDelta
1265 The wheel delta, normally 120.
1266 */
1267
1268
1269 /**
1270 int m_wheelRotation
1271 The distance the mouse wheel is rotated.
1272 */
1273
1274
1275 /**
1276 long m_x
1277 X-coordinate of the event.
1278 */
1279
1280
1281 /**
1282 long m_y
1283 Y-coordinate of the event.
1284 */
1285 };
1286
1287
1288
1289 /**
1290 @class wxDropFilesEvent
1291 @wxheader{event.h}
1292
1293 This class is used for drop files events, that is, when files have been dropped
1294 onto the window. This functionality is currently only available under Windows.
1295 The window must have previously been enabled for dropping by calling
1296 wxWindow::DragAcceptFiles.
1297
1298 Important note: this is a separate implementation to the more general
1299 drag and drop implementation documented here(). It uses the
1300 older, Windows message-based approach of dropping files.
1301
1302 @library{wxcore}
1303 @category{events}
1304
1305 @see @ref overview_eventhandling
1306 */
1307 class wxDropFilesEvent : public wxEvent
1308 {
1309 public:
1310 /**
1311 Constructor.
1312 */
1313 wxDropFilesEvent(wxEventType id = 0, int noFiles = 0,
1314 wxString* files = NULL);
1315
1316 /**
1317 Returns an array of filenames.
1318 */
1319 wxString* GetFiles() const;
1320
1321 /**
1322 Returns the number of files dropped.
1323 */
1324 int GetNumberOfFiles() const;
1325
1326 /**
1327 Returns the position at which the files were dropped.
1328 Returns an array of filenames.
1329 */
1330 wxPoint GetPosition() const;
1331
1332 /**
1333 wxString* m_files
1334 An array of filenames.
1335 */
1336
1337
1338 /**
1339 int m_noFiles
1340 The number of files dropped.
1341 */
1342
1343
1344 /**
1345 wxPoint m_pos
1346 The point at which the drop took place.
1347 */
1348 };
1349
1350
1351
1352 /**
1353 @class wxCommandEvent
1354 @wxheader{event.h}
1355
1356 This event class contains information about command events, which originate
1357 from a variety of
1358 simple controls. More complex controls, such as wxTreeCtrl, have separate
1359 command event classes.
1360
1361 @library{wxcore}
1362 @category{events}
1363 */
1364 class wxCommandEvent : public wxEvent
1365 {
1366 public:
1367 /**
1368 Constructor.
1369 */
1370 wxCommandEvent(wxEventType commandEventType = 0, int id = 0);
1371
1372 /**
1373 Deprecated, use IsChecked() instead.
1374 */
1375 bool Checked() const;
1376
1377 /**
1378 Returns client data pointer for a listbox or choice selection event
1379 (not valid for a deselection).
1380 */
1381 void* GetClientData() const;
1382
1383 /**
1384 Returns client object pointer for a listbox or choice selection event
1385 (not valid for a deselection).
1386 */
1387 wxClientData* GetClientObject() const;
1388
1389 /**
1390 Returns extra information dependant on the event objects type.
1391 If the event comes from a listbox selection, it is a boolean
1392 determining whether the event was a selection (@true) or a
1393 deselection (@false). A listbox deselection only occurs for
1394 multiple-selection boxes, and in this case the index and string values
1395 are indeterminate and the listbox must be examined by the application.
1396 */
1397 long GetExtraLong() const;
1398
1399 /**
1400 Returns the integer identifier corresponding to a listbox, choice or
1401 radiobox selection (only if the event was a selection, not a
1402 deselection), or a boolean value representing the value of a checkbox.
1403 */
1404 int GetInt() const;
1405
1406 /**
1407 Returns item index for a listbox or choice selection event (not valid for
1408 a deselection).
1409 */
1410 int GetSelection() const;
1411
1412 /**
1413 Returns item string for a listbox or choice selection event (not valid for
1414 a deselection).
1415 */
1416 wxString GetString() const;
1417
1418 /**
1419 This method can be used with checkbox and menu events: for the checkboxes, the
1420 method returns @true for a selection event and @false for a
1421 deselection one. For the menu events, this method indicates if the menu item
1422 just has become checked or unchecked (and thus only makes sense for checkable
1423 menu items).
1424 Notice that this method can not be used with
1425 wxCheckListBox currently.
1426 */
1427 bool IsChecked() const;
1428
1429 /**
1430 For a listbox or similar event, returns @true if it is a selection, @false if it
1431 is a deselection.
1432 */
1433 bool IsSelection() const;
1434
1435 /**
1436 Sets the client data for this event.
1437 */
1438 void SetClientData(void* clientData);
1439
1440 /**
1441 Sets the client object for this event. The client object is not owned by the
1442 event
1443 object and the event object will not delete the client object in its destructor.
1444 The client object must be owned and deleted by another object (e.g. a control)
1445 that has longer life time than the event object.
1446 */
1447 void SetClientObject(wxClientData* clientObject);
1448
1449 /**
1450 Sets the @b m_extraLong member.
1451 */
1452 void SetExtraLong(long extraLong);
1453
1454 /**
1455 Sets the @b m_commandInt member.
1456 */
1457 void SetInt(int intCommand);
1458
1459 /**
1460 Sets the @b m_commandString member.
1461 */
1462 void SetString(const wxString& string);
1463 };
1464
1465
1466
1467 /**
1468 @class wxActivateEvent
1469 @wxheader{event.h}
1470
1471 An activate event is sent when a window or application is being activated
1472 or deactivated.
1473
1474 @library{wxcore}
1475 @category{events}
1476
1477 @see @ref overview_eventhandling, wxApp::IsActive
1478 */
1479 class wxActivateEvent : public wxEvent
1480 {
1481 public:
1482 /**
1483 Constructor.
1484 */
1485 wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true,
1486 int id = 0);
1487
1488 /**
1489 Returns @true if the application or window is being activated, @false otherwise.
1490 */
1491 bool GetActive() const;
1492 };
1493
1494
1495
1496 /**
1497 @class wxContextMenuEvent
1498 @wxheader{event.h}
1499
1500 This class is used for context menu events, sent to give
1501 the application a chance to show a context (popup) menu.
1502
1503 Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this
1504 means that the event originated
1505 from a keyboard context button event, and you should compute a suitable
1506 position yourself,
1507 for example by calling wxGetMousePosition().
1508
1509 When a keyboard context menu button is pressed on Windows, a right-click event
1510 with default position is sent first,
1511 and if this event is not processed, the context menu event is sent. So if you
1512 process mouse events and you find your context menu event handler
1513 is not being called, you could call wxEvent::Skip for mouse right-down events.
1514
1515 @library{wxcore}
1516 @category{events}
1517
1518 @see @ref overview_wxcommandevent "Command events", @ref
1519 overview_eventhandling
1520 */
1521 class wxContextMenuEvent : public wxCommandEvent
1522 {
1523 public:
1524 /**
1525 Constructor.
1526 */
1527 wxContextMenuEvent(wxEventType id = 0, int id = 0,
1528 const wxPoint& pos = wxDefaultPosition);
1529
1530 /**
1531 Returns the position in screen coordinates at which the menu should be shown.
1532 Use wxWindow::ScreenToClient to
1533 convert to client coordinates. You can also omit a position from
1534 wxWindow::PopupMenu in order to use
1535 the current mouse pointer position.
1536 If the event originated from a keyboard event, the value returned from this
1537 function will be wxDefaultPosition.
1538 */
1539 const wxPoint& GetPosition() const;
1540
1541 /**
1542 Sets the position at which the menu should be shown.
1543 */
1544 void SetPosition(const wxPoint& point);
1545 };
1546
1547
1548
1549 /**
1550 @class wxEraseEvent
1551 @wxheader{event.h}
1552
1553 An erase event is sent when a window's background needs to be repainted.
1554
1555 On some platforms, such as GTK+, this event is simulated (simply generated just
1556 before the
1557 paint event) and may cause flicker. It is therefore recommended that
1558 you set the text background colour explicitly in order to prevent flicker.
1559 The default background colour under GTK+ is grey.
1560
1561 To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
1562 definition.
1563
1564 You must call wxEraseEvent::GetDC and use the returned device context if it is
1565 non-@NULL.
1566 If it is @NULL, create your own temporary wxClientDC object.
1567
1568 @library{wxcore}
1569 @category{events}
1570
1571 @see @ref overview_eventhandling
1572 */
1573 class wxEraseEvent : public wxEvent
1574 {
1575 public:
1576 /**
1577 Constructor.
1578 */
1579 wxEraseEvent(int id = 0, wxDC* dc = NULL);
1580
1581 /**
1582 Returns the device context associated with the erase event to draw on.
1583 */
1584 wxDC* GetDC() const;
1585 };
1586
1587
1588
1589 /**
1590 @class wxFocusEvent
1591 @wxheader{event.h}
1592
1593 A focus event is sent when a window's focus changes. The window losing focus
1594 receives a "kill focus'' event while the window gaining it gets a "set
1595 focus'' one.
1596
1597 Notice that the set focus event happens both when the user gives focus to the
1598 window (whether using the mouse or keyboard) and when it is done from the
1599 program itself using wxWindow::SetFocus.
1600
1601 @library{wxcore}
1602 @category{events}
1603
1604 @see @ref overview_eventhandling
1605 */
1606 class wxFocusEvent : public wxEvent
1607 {
1608 public:
1609 /**
1610 Constructor.
1611 */
1612 wxFocusEvent(wxEventType eventType = 0, int id = 0);
1613
1614 /**
1615 Returns the window associated with this event, that is the window which had the
1616 focus before for the @c wxEVT_SET_FOCUS event and the window which is
1617 going to receive focus for the @c wxEVT_KILL_FOCUS one.
1618 Warning: the window pointer may be @NULL!
1619 */
1620 };
1621
1622
1623
1624 /**
1625 @class wxChildFocusEvent
1626 @wxheader{event.h}
1627
1628 A child focus event is sent to a (parent-)window when one of its child windows
1629 gains focus,
1630 so that the window could restore the focus back to its corresponding child
1631 if it loses it now and regains later.
1632
1633 Notice that child window is the direct child of the window receiving event.
1634 Use wxWindow::FindFocus to retreive the window which is actually getting focus.
1635
1636 @library{wxcore}
1637 @category{events}
1638
1639 @see @ref overview_eventhandling
1640 */
1641 class wxChildFocusEvent : public wxCommandEvent
1642 {
1643 public:
1644 /**
1645 Constructor.
1646
1647 @param win
1648 The direct child which is (or which contains the window which is) receiving
1649 the focus.
1650 */
1651 wxChildFocusEvent(wxWindow* win = NULL);
1652
1653 /**
1654 Returns the direct child which receives the focus, or a (grand-)parent of the
1655 control receiving the focus.
1656 To get the actually focused control use wxWindow::FindFocus.
1657 */
1658 };
1659
1660
1661
1662 /**
1663 @class wxMouseCaptureLostEvent
1664 @wxheader{event.h}
1665
1666 An mouse capture lost event is sent to a window that obtained mouse capture,
1667 which was subsequently loss due to "external" event, for example when a dialog
1668 box is shown or if another application captures the mouse.
1669
1670 If this happens, this event is sent to all windows that are on capture stack
1671 (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is
1672 not sent if the capture changes because of a call to CaptureMouse or
1673 ReleaseMouse.
1674
1675 This event is currently emitted under Windows only.
1676
1677 @library{wxcore}
1678 @category{events}
1679
1680 @see wxMouseCaptureChangedEvent, @ref overview_eventhandling,
1681 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
1682 */
1683 class wxMouseCaptureLostEvent : public wxEvent
1684 {
1685 public:
1686 /**
1687 Constructor.
1688 */
1689 wxMouseCaptureLostEvent(wxWindowID windowId = 0);
1690 };
1691
1692
1693
1694 /**
1695 @class wxNotifyEvent
1696 @wxheader{event.h}
1697
1698 This class is not used by the event handlers by itself, but is a base class
1699 for other event classes (such as wxNotebookEvent).
1700
1701 It (or an object of a derived class) is sent when the controls state is being
1702 changed and allows the program to wxNotifyEvent::Veto this
1703 change if it wants to prevent it from happening.
1704
1705 @library{wxcore}
1706 @category{events}
1707
1708 @see wxNotebookEvent
1709 */
1710 class wxNotifyEvent : public wxCommandEvent
1711 {
1712 public:
1713 /**
1714 Constructor (used internally by wxWidgets only).
1715 */
1716 wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0);
1717
1718 /**
1719 This is the opposite of Veto(): it explicitly
1720 allows the event to be processed. For most events it is not necessary to call
1721 this method as the events are allowed anyhow but some are forbidden by default
1722 (this will be mentioned in the corresponding event description).
1723 */
1724 void Allow();
1725
1726 /**
1727 Returns @true if the change is allowed (Veto()
1728 hasn't been called) or @false otherwise (if it was).
1729 */
1730 bool IsAllowed() const;
1731
1732 /**
1733 Prevents the change announced by this event from happening.
1734 It is in general a good idea to notify the user about the reasons for vetoing
1735 the change because otherwise the applications behaviour (which just refuses to
1736 do what the user wants) might be quite surprising.
1737 */
1738 void Veto();
1739 };
1740
1741
1742
1743 /**
1744 @class wxHelpEvent
1745 @wxheader{event.h}
1746
1747 A help event is sent when the user has requested context-sensitive help.
1748 This can either be caused by the application requesting
1749 context-sensitive help mode via wxContextHelp, or
1750 (on MS Windows) by the system generating a WM_HELP message when the user
1751 pressed F1 or clicked
1752 on the query button in a dialog caption.
1753
1754 A help event is sent to the window that the user clicked on, and is propagated
1755 up the
1756 window hierarchy until the event is processed or there are no more event
1757 handlers.
1758 The application should call wxEvent::GetId to check the identity of the
1759 clicked-on window,
1760 and then either show some suitable help or call wxEvent::Skip if the identifier
1761 is unrecognised.
1762 Calling Skip is important because it allows wxWidgets to generate further
1763 events for ancestors
1764 of the clicked-on window. Otherwise it would be impossible to show help for
1765 container windows,
1766 since processing would stop after the first window found.
1767
1768 @library{wxcore}
1769 @category{events}
1770
1771 @see wxContextHelp, wxDialog, @ref overview_eventhandling
1772 */
1773 class wxHelpEvent : public wxCommandEvent
1774 {
1775 public:
1776 // how was this help event generated?
1777 enum Origin
1778 {
1779 Origin_Unknown, // unrecognized event source
1780 Origin_Keyboard, // event generated from F1 key press
1781 Origin_HelpButton // event from [?] button on the title bar (Windows)
1782 };
1783
1784 /**
1785 Constructor.
1786 */
1787 wxHelpEvent(wxEventType type = wxEVT_NULL,
1788 wxWindowID winid = 0,
1789 const wxPoint& pt = wxDefaultPosition,
1790 Origin origin = Origin_Unknown);
1791
1792 /**
1793 Returns the origin of the help event which is one of the following values:
1794
1795 @b Origin_Unknown
1796
1797 Unrecognized event source.
1798
1799 @b Origin_Keyboard
1800
1801 Event generated by @c F1 key press.
1802
1803 @b Origin_HelpButton
1804
1805 Event generated by
1806 wxContextHelp or using the "?" title bur button under
1807 MS Windows.
1808
1809 The application may handle events generated using the keyboard or mouse
1810 differently, e.g. by using wxGetMousePosition()
1811 for the mouse events.
1812
1813 @see SetOrigin()
1814 */
1815 Origin GetOrigin() const;
1816
1817 /**
1818 Returns the left-click position of the mouse, in screen coordinates. This allows
1819 the application to position the help appropriately.
1820 */
1821 const wxPoint& GetPosition() const;
1822
1823 /**
1824 Set the help event origin, only used internally by wxWidgets normally.
1825
1826 @see GetOrigin()
1827 */
1828 void SetOrigin(Origin);
1829
1830 /**
1831 Sets the left-click position of the mouse, in screen coordinates.
1832 */
1833 void SetPosition(const wxPoint& pt);
1834 };
1835
1836
1837
1838 /**
1839 @class wxScrollEvent
1840 @wxheader{event.h}
1841
1842 A scroll event holds information about events sent from stand-alone
1843 scrollbars() and sliders(). Note that
1844 starting from wxWidgets 2.1, scrolled windows send the
1845 wxScrollWinEvent which does not derive from
1846 wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of
1847 events and use the event table macros mentioned below only for the
1848 scrollbar-like controls.
1849
1850 @library{wxcore}
1851 @category{events}
1852
1853 @see wxScrollBar, wxSlider, wxSpinButton, , wxScrollWinEvent, @ref
1854 overview_eventhandling
1855 */
1856 class wxScrollEvent : public wxCommandEvent
1857 {
1858 public:
1859 /**
1860 Constructor.
1861 */
1862 wxScrollEvent(wxEventType commandType = 0, int id = 0, int pos = 0,
1863 int orientation = 0);
1864
1865 /**
1866 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
1867 scrollbar.
1868 */
1869 int GetOrientation() const;
1870
1871 /**
1872 Returns the position of the scrollbar.
1873 */
1874 int GetPosition() const;
1875 };
1876
1877
1878
1879 /**
1880 @class wxIdleEvent
1881 @wxheader{event.h}
1882
1883 This class is used for idle events, which are generated when the system becomes
1884 idle. Note that, unless you do something specifically, the idle events are not
1885 sent if the system remains idle once it has become it, e.g. only a single idle
1886 event will be generated until something else resulting in more normal events
1887 happens and only then is the next idle event sent again. If you need to ensure
1888 a continuous stream of idle events, you can either use
1889 wxIdleEvent::RequestMore method in your handler or call
1890 wxWakeUpIdle() periodically (for example from timer
1891 event), but note that both of these approaches (and especially the first one)
1892 increase the system load and so should be avoided if possible.
1893
1894 By default, idle events are sent to all windows (and also
1895 wxApp, as usual). If this is causing a significant
1896 overhead in your application, you can call wxIdleEvent::SetMode with
1897 the value wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra
1898 window style for every window which should receive idle events.
1899
1900 @library{wxbase}
1901 @category{events}
1902
1903 @see @ref overview_eventhandling, wxUpdateUIEvent,
1904 wxWindow::OnInternalIdle
1905 */
1906 class wxIdleEvent : public wxEvent
1907 {
1908 public:
1909 /**
1910 Constructor.
1911 */
1912 wxIdleEvent();
1913
1914 /**
1915 Returns @true if it is appropriate to send idle events to
1916 this window.
1917 This function looks at the mode used (see wxIdleEvent::SetMode),
1918 and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle
1919 events should be sent to
1920 this window now. By default this will always return @true because
1921 the update mode is initially wxIDLE_PROCESS_ALL. You can change the mode
1922 to only send idle events to windows with the wxWS_EX_PROCESS_IDLE extra window
1923 style set.
1924
1925 @see SetMode()
1926 */
1927 static bool CanSend(wxWindow* window);
1928
1929 /**
1930 Static function returning a value specifying how wxWidgets
1931 will send idle events: to all windows, or only to those which specify that they
1932 will process the events.
1933 See SetMode().
1934 */
1935 static wxIdleMode GetMode();
1936
1937 /**
1938 Returns @true if the OnIdle function processing this event requested more
1939 processing time.
1940
1941 @see RequestMore()
1942 */
1943 bool MoreRequested() const;
1944
1945 /**
1946 Tells wxWidgets that more processing is required. This function can be called
1947 by an OnIdle
1948 handler for a window or window event handler to indicate that wxApp::OnIdle
1949 should
1950 forward the OnIdle event once more to the application windows. If no window
1951 calls this function
1952 during OnIdle, then the application will remain in a passive event loop (not
1953 calling OnIdle) until a
1954 new event is posted to the application by the windowing system.
1955
1956 @see MoreRequested()
1957 */
1958 void RequestMore(bool needMore = true);
1959
1960 /**
1961 Static function for specifying how wxWidgets will send idle events: to
1962 all windows, or only to those which specify that they
1963 will process the events.
1964 @a mode can be one of the following values.
1965 The default is wxIDLE_PROCESS_ALL.
1966 */
1967 static void SetMode(wxIdleMode mode);
1968 };
1969
1970
1971
1972 /**
1973 @class wxInitDialogEvent
1974 @wxheader{event.h}
1975
1976 A wxInitDialogEvent is sent as a dialog or panel is being initialised.
1977 Handlers for this event can transfer data to the window.
1978 The default handler calls wxWindow::TransferDataToWindow.
1979
1980 @library{wxcore}
1981 @category{events}
1982
1983 @see @ref overview_eventhandling
1984 */
1985 class wxInitDialogEvent : public wxEvent
1986 {
1987 public:
1988 /**
1989 Constructor.
1990 */
1991 wxInitDialogEvent(int id = 0);
1992 };
1993
1994
1995
1996 /**
1997 @class wxWindowDestroyEvent
1998 @wxheader{event.h}
1999
2000 This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a
2001 window is destroyed.
2002
2003 When a class derived from wxWindow is destroyed its destructor will have
2004 already run by the time this event is sent. Therefore this event will not
2005 usually be received at all.
2006
2007 To receive this event wxEvtHandler::Connect
2008 must be used (using an event table macro will not work). Since it is
2009 received after the destructor has run, an object should not handle its
2010 own wxWindowDestroyEvent, but it can be used to get notification of the
2011 destruction of another window.
2012
2013 @library{wxcore}
2014 @category{events}
2015
2016 @see @ref overview_eventhandling, wxWindowCreateEvent
2017 */
2018 class wxWindowDestroyEvent : public wxCommandEvent
2019 {
2020 public:
2021 /**
2022 Constructor.
2023 */
2024 wxWindowDestroyEvent(wxWindow* win = NULL);
2025 };
2026
2027
2028
2029 /**
2030 @class wxNavigationKeyEvent
2031 @wxheader{event.h}
2032
2033 This event class contains information about navigation events,
2034 generated by navigation keys such as tab and page down.
2035
2036 This event is mainly used by wxWidgets implementations. A
2037 wxNavigationKeyEvent handler is automatically provided by wxWidgets
2038 when you make a class into a control container with the macro
2039 WX_DECLARE_CONTROL_CONTAINER.
2040
2041 @library{wxcore}
2042 @category{events}
2043
2044 @see wxWindow::Navigate, wxWindow::NavigateIn
2045 */
2046 class wxNavigationKeyEvent
2047 {
2048 public:
2049 //@{
2050 /**
2051 Constructor.
2052 */
2053 wxNavigationKeyEvent();
2054 wxNavigationKeyEvent(const wxNavigationKeyEvent& event);
2055 //@}
2056
2057 /**
2058 Returns the child that has the focus, or @NULL.
2059 */
2060 wxWindow* GetCurrentFocus() const;
2061
2062 /**
2063 Returns @true if the navigation was in the forward direction.
2064 */
2065 bool GetDirection() const;
2066
2067 /**
2068 Returns @true if the navigation event was from a tab key. This is required
2069 for proper navigation over radio buttons.
2070 */
2071 bool IsFromTab() const;
2072
2073 /**
2074 Returns @true if the navigation event represents a window change (for
2075 example, from Ctrl-Page Down
2076 in a notebook).
2077 */
2078 bool IsWindowChange() const;
2079
2080 /**
2081 Sets the current focus window member.
2082 */
2083 void SetCurrentFocus(wxWindow* currentFocus);
2084
2085 /**
2086 Sets the direction to forward if @a direction is @true, or backward if @c
2087 @false.
2088 */
2089 void SetDirection(bool direction);
2090
2091 /**
2092 Sets the flags.
2093 */
2094 void SetFlags(long flags);
2095
2096 /**
2097 Marks the navigation event as from a tab key.
2098 */
2099 void SetFromTab(bool fromTab);
2100
2101 /**
2102 Marks the event as a window change event.
2103 */
2104 void SetWindowChange(bool windowChange);
2105 };
2106
2107
2108
2109 /**
2110 @class wxMouseCaptureChangedEvent
2111 @wxheader{event.h}
2112
2113 An mouse capture changed event is sent to a window that loses its
2114 mouse capture. This is called even if wxWindow::ReleaseCapture
2115 was called by the application code. Handling this event allows
2116 an application to cater for unexpected capture releases which
2117 might otherwise confuse mouse handling code.
2118
2119 This event is implemented under Windows only.
2120
2121 @library{wxcore}
2122 @category{events}
2123
2124 @see wxMouseCaptureLostEvent, @ref overview_eventhandling,
2125 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
2126 */
2127 class wxMouseCaptureChangedEvent : public wxEvent
2128 {
2129 public:
2130 /**
2131 Constructor.
2132 */
2133 wxMouseCaptureChangedEvent(wxWindowID windowId = 0,
2134 wxWindow* gainedCapture = NULL);
2135
2136 /**
2137 Returns the window that gained the capture, or @NULL if it was a non-wxWidgets
2138 window.
2139 */
2140 wxWindow* GetCapturedWindow() const;
2141 };
2142
2143
2144
2145 /**
2146 @class wxCloseEvent
2147 @wxheader{event.h}
2148
2149 This event class contains information about window and session close events.
2150
2151 The handler function for EVT_CLOSE is called when the user has tried to close a
2152 a frame
2153 or dialog box using the window manager (X) or system menu (Windows). It can
2154 also be invoked by the application itself programmatically, for example by
2155 calling the wxWindow::Close function.
2156
2157 You should check whether the application is forcing the deletion of the window
2158 using wxCloseEvent::CanVeto. If this is @false,
2159 you @e must destroy the window using wxWindow::Destroy.
2160 If the return value is @true, it is up to you whether you respond by destroying
2161 the window.
2162
2163 If you don't destroy the window, you should call wxCloseEvent::Veto to
2164 let the calling code know that you did not destroy the window. This allows the
2165 wxWindow::Close function
2166 to return @true or @false depending on whether the close instruction was
2167 honoured or not.
2168
2169 @library{wxcore}
2170 @category{events}
2171
2172 @see wxWindow::Close, @ref overview_windowdeletionoverview "Window deletion
2173 overview"
2174 */
2175 class wxCloseEvent : public wxEvent
2176 {
2177 public:
2178 /**
2179 Constructor.
2180 */
2181 wxCloseEvent(wxEventType commandEventType = 0, int id = 0);
2182
2183 /**
2184 Returns @true if you can veto a system shutdown or a window close event.
2185 Vetoing a window close event is not possible if the calling code wishes to
2186 force the application to exit, and so this function must be called to check
2187 this.
2188 */
2189 bool CanVeto() const;
2190
2191 /**
2192 Returns @true if the user is just logging off or @false if the system is
2193 shutting down. This method can only be called for end session and query end
2194 session events, it doesn't make sense for close window event.
2195 */
2196 bool GetLoggingOff() const;
2197
2198 /**
2199 Sets the 'can veto' flag.
2200 */
2201 void SetCanVeto(bool canVeto);
2202
2203 /**
2204 Sets the 'force' flag.
2205 */
2206 void SetForce(bool force) const;
2207
2208 /**
2209 Sets the 'logging off' flag.
2210 */
2211 void SetLoggingOff(bool loggingOff);
2212
2213 /**
2214 Call this from your event handler to veto a system shutdown or to signal
2215 to the calling application that a window close did not happen.
2216 You can only veto a shutdown if CanVeto() returns
2217 @true.
2218 */
2219 void Veto(bool veto = true);
2220 };
2221
2222
2223
2224 /**
2225 @class wxMenuEvent
2226 @wxheader{event.h}
2227
2228 This class is used for a variety of menu-related events. Note that
2229 these do not include menu command events, which are
2230 handled using wxCommandEvent objects.
2231
2232 The default handler for wxEVT_MENU_HIGHLIGHT displays help
2233 text in the first field of the status bar.
2234
2235 @library{wxcore}
2236 @category{events}
2237
2238 @see @ref overview_wxcommandevent "Command events", @ref
2239 overview_eventhandling
2240 */
2241 class wxMenuEvent : public wxEvent
2242 {
2243 public:
2244 /**
2245 Constructor.
2246 */
2247 wxMenuEvent(wxEventType id = 0, int id = 0, wxMenu* menu = NULL);
2248
2249 /**
2250 Returns the menu which is being opened or closed. This method should only be
2251 used with the @c OPEN and @c CLOSE events and even for them the
2252 returned pointer may be @NULL in some ports.
2253 */
2254 wxMenu* GetMenu() const;
2255
2256 /**
2257 Returns the menu identifier associated with the event. This method should be
2258 only used with the @c HIGHLIGHT events.
2259 */
2260 int GetMenuId() const;
2261
2262 /**
2263 Returns @true if the menu which is being opened or closed is a popup menu,
2264 @false if it is a normal one.
2265 This method should only be used with the @c OPEN and @c CLOSE events.
2266 */
2267 bool IsPopup() const;
2268 };
2269
2270
2271
2272 /**
2273 @class wxEventBlocker
2274 @wxheader{event.h}
2275
2276 This class is a special event handler which allows to discard
2277 any event (or a set of event types) directed to a specific window.
2278
2279 Example:
2280
2281 @code
2282 {
2283 // block all events directed to this window while
2284 // we do the 1000 FuncWhichSendsEvents() calls
2285 wxEventBlocker blocker(this);
2286
2287 for ( int i = 0; i 1000; i++ )
2288 FuncWhichSendsEvents(i);
2289
2290 } // ~wxEventBlocker called, old event handler is restored
2291
2292 // the event generated by this call will be processed
2293 FuncWhichSendsEvents(0)
2294 @endcode
2295
2296 @library{wxcore}
2297 @category{events}
2298
2299 @see @ref overview_eventhandling, wxEvtHandler
2300 */
2301 class wxEventBlocker : public wxEvtHandler
2302 {
2303 public:
2304 /**
2305 Constructs the blocker for the given window and for the given event type.
2306 If @a type is @c wxEVT_ANY, then all events for that window are
2307 blocked. You can call Block() after creation to
2308 add other event types to the list of events to block.
2309 Note that the @a win window @b must remain alive until the
2310 wxEventBlocker object destruction.
2311 */
2312 wxEventBlocker(wxWindow* win, wxEventType = -0x000000001);
2313
2314 /**
2315 Destructor. The blocker will remove itself from the chain of event handlers for
2316 the window provided in the constructor, thus restoring normal processing of
2317 events.
2318 */
2319 virtual ~wxEventBlocker();
2320
2321 /**
2322 Adds to the list of event types which should be blocked the given @e eventType.
2323 */
2324 void Block(wxEventType eventType);
2325 };
2326
2327
2328
2329 /**
2330 @class wxEvtHandler
2331 @wxheader{event.h}
2332
2333 A class that can handle events from the windowing system.
2334 wxWindow (and therefore all window classes) are derived from
2335 this class.
2336
2337 When events are received, wxEvtHandler invokes the method listed in the
2338 event table using itself as the object. When using multiple inheritance
2339 it is imperative that the wxEvtHandler(-derived) class be the first
2340 class inherited such that the "this" pointer for the overall object
2341 will be identical to the "this" pointer for the wxEvtHandler portion.
2342
2343 @library{wxbase}
2344 @category{events}
2345
2346 @see @ref overview_eventhandling
2347 */
2348 class wxEvtHandler : public wxObject
2349 {
2350 public:
2351 /**
2352 Constructor.
2353 */
2354 wxEvtHandler();
2355
2356 /**
2357 Destructor. If the handler is part of a chain, the destructor will
2358 unlink itself and restore the previous and next handlers so that they point to
2359 each other.
2360 */
2361 virtual ~wxEvtHandler();
2362
2363 /**
2364 This function posts an event to be processed later.
2365
2366 @param event
2367 Event to add to process queue.
2368
2369 @remarks The difference between sending an event (using the ProcessEvent
2370 method) and posting it is that in the first case the
2371 event is processed before the function returns, while
2372 in the second case, the function returns immediately
2373 and the event will be processed sometime later (usually
2374 during the next event loop iteration).
2375 */
2376 virtual void AddPendingEvent(const wxEvent& event);
2377
2378 //@{
2379 /**
2380 Connects the given function dynamically with the event handler, id and event
2381 type. This
2382 is an alternative to the use of static event tables. See the 'event' or the old
2383 'dynamic' sample for usage.
2384
2385 @param id
2386 The identifier (or first of the identifier range) to be
2387 associated with the event handler function. For the version not taking this
2388 argument, it defaults to wxID_ANY.
2389 @param lastId
2390 The second part of the identifier range to be associated with the event
2391 handler function.
2392 @param eventType
2393 The event type to be associated with this event handler.
2394 @param function
2395 The event handler function. Note that this function should
2396 be explicitly converted to the correct type which can be done using a macro
2397 called wxFooEventHandler for the handler for any wxFooEvent.
2398 @param userData
2399 Data to be associated with the event table entry.
2400 @param eventSink
2401 Object whose member function should be called. If this is @NULL,
2402 this will be used.
2403 */
2404 void Connect(int id, int lastId, wxEventType eventType,
2405 wxObjectEventFunction function,
2406 wxObject* userData = NULL,
2407 wxEvtHandler* eventSink = NULL);
2408 void Connect(int id, wxEventType eventType,
2409 wxObjectEventFunction function,
2410 wxObject* userData = NULL,
2411 wxEvtHandler* eventSink = NULL);
2412 void Connect(wxEventType eventType,
2413 wxObjectEventFunction function,
2414 wxObject* userData = NULL,
2415 wxEvtHandler* eventSink = NULL);
2416 //@}
2417
2418 //@{
2419 /**
2420 Disconnects the given function dynamically from the event handler, using the
2421 specified
2422 parameters as search criteria and returning @true if a matching function has been
2423 found and removed. This method can only disconnect functions which have been
2424 added
2425 using the Connect() method. There is no way
2426 to disconnect functions connected using the (static) event tables.
2427
2428 @param id
2429 The identifier (or first of the identifier range) associated with the event
2430 handler function.
2431 @param lastId
2432 The second part of the identifier range associated with the event handler
2433 function.
2434 @param eventType
2435 The event type associated with this event handler.
2436 @param function
2437 The event handler function.
2438 @param userData
2439 Data associated with the event table entry.
2440 @param eventSink
2441 Object whose member function should be called.
2442 */
2443 bool Disconnect(wxEventType eventType = wxEVT_NULL,
2444 wxObjectEventFunction function = NULL,
2445 wxObject* userData = NULL,
2446 wxEvtHandler* eventSink = NULL);
2447 bool Disconnect(int id = wxID_ANY,
2448 wxEventType eventType = wxEVT_NULL,
2449 wxObjectEventFunction function = NULL,
2450 wxObject* userData = NULL,
2451 wxEvtHandler* eventSink = NULL);
2452 bool Disconnect(int id, int lastId = wxID_ANY,
2453 wxEventType eventType = wxEVT_NULL,
2454 wxObjectEventFunction function = NULL,
2455 wxObject* userData = NULL,
2456 wxEvtHandler* eventSink = NULL);
2457 //@}
2458
2459 /**
2460 Gets user-supplied client data.
2461
2462 @remarks Normally, any extra data the programmer wishes to associate with
2463 the object should be made available by deriving a new
2464 class with new data members.
2465
2466 @see SetClientData()
2467 */
2468 void* GetClientData() const;
2469
2470 /**
2471 Get a pointer to the user-supplied client data object.
2472
2473 @see SetClientObject(), wxClientData
2474 */
2475 wxClientData* GetClientObject() const;
2476
2477 /**
2478 Returns @true if the event handler is enabled, @false otherwise.
2479
2480 @see SetEvtHandlerEnabled()
2481 */
2482 bool GetEvtHandlerEnabled() const;
2483
2484 /**
2485 Gets the pointer to the next handler in the chain.
2486
2487 @see SetNextHandler(), GetPreviousHandler(),
2488 SetPreviousHandler(), wxWindow::PushEventHandler,
2489 wxWindow::PopEventHandler
2490 */
2491 wxEvtHandler* GetNextHandler() const;
2492
2493 /**
2494 Gets the pointer to the previous handler in the chain.
2495
2496 @see SetPreviousHandler(), GetNextHandler(),
2497 SetNextHandler(), wxWindow::PushEventHandler,
2498 wxWindow::PopEventHandler
2499 */
2500 wxEvtHandler* GetPreviousHandler() const;
2501
2502 /**
2503 Processes an event, searching event tables and calling zero or more suitable
2504 event handler function(s).
2505
2506 @param event
2507 Event to process.
2508
2509 @returns @true if a suitable event handler function was found and
2510 executed, and the function did not call wxEvent::Skip.
2511
2512 @remarks Normally, your application would not call this function: it is
2513 called in the wxWidgets implementation to dispatch
2514 incoming user interface events to the framework (and
2515 application).
2516
2517 @see SearchEventTable()
2518 */
2519 virtual bool ProcessEvent(wxEvent& event);
2520
2521 /**
2522 Processes an event by calling ProcessEvent()
2523 and handles any exceptions that occur in the process. If an exception is
2524 thrown in event handler, wxApp::OnExceptionInMainLoop
2525 is called.
2526
2527 @param event
2528 Event to process.
2529
2530 @returns @true if the event was processed, @false if no handler was found
2531 or an exception was thrown.
2532
2533 @see wxWindow::HandleWindowEvent
2534 */
2535 bool SafelyProcessEvent(wxEvent& event);
2536
2537 /**
2538 Searches the event table, executing an event handler function if an appropriate
2539 one
2540 is found.
2541
2542 @param table
2543 Event table to be searched.
2544 @param event
2545 Event to be matched against an event table entry.
2546
2547 @returns @true if a suitable event handler function was found and
2548 executed, and the function did not call wxEvent::Skip.
2549
2550 @remarks This function looks through the object's event table and tries
2551 to find an entry that will match the event.
2552
2553 @see ProcessEvent()
2554 */
2555 virtual bool SearchEventTable(wxEventTable& table,
2556 wxEvent& event);
2557
2558 /**
2559 Sets user-supplied client data.
2560
2561 @param data
2562 Data to be associated with the event handler.
2563
2564 @remarks Normally, any extra data the programmer wishes to associate with
2565 the object should be made available by deriving a new
2566 class with new data members. You must not call this
2567 method and SetClientObject on the same class - only one
2568 of them.
2569
2570 @see GetClientData()
2571 */
2572 void SetClientData(void* data);
2573
2574 /**
2575 Set the client data object. Any previous object will be deleted.
2576
2577 @see GetClientObject(), wxClientData
2578 */
2579 void SetClientObject(wxClientData* data);
2580
2581 /**
2582 Enables or disables the event handler.
2583
2584 @param enabled
2585 @true if the event handler is to be enabled, @false if it is to be disabled.
2586
2587 @remarks You can use this function to avoid having to remove the event
2588 handler from the chain, for example when implementing a
2589 dialog editor and changing from edit to test mode.
2590
2591 @see GetEvtHandlerEnabled()
2592 */
2593 void SetEvtHandlerEnabled(bool enabled);
2594
2595 /**
2596 Sets the pointer to the next handler.
2597
2598 @param handler
2599 Event handler to be set as the next handler.
2600
2601 @see GetNextHandler(), SetPreviousHandler(),
2602 GetPreviousHandler(), wxWindow::PushEventHandler,
2603 wxWindow::PopEventHandler
2604 */
2605 void SetNextHandler(wxEvtHandler* handler);
2606
2607 /**
2608 Sets the pointer to the previous handler.
2609
2610 @param handler
2611 Event handler to be set as the previous handler.
2612 */
2613 void SetPreviousHandler(wxEvtHandler* handler);
2614 };
2615
2616
2617
2618 /**
2619 @class wxIconizeEvent
2620 @wxheader{event.h}
2621
2622 An event being sent when the frame is iconized (minimized) or restored.
2623
2624 Currently only wxMSW and wxGTK generate such events.
2625
2626 @library{wxcore}
2627 @category{events}
2628
2629 @see @ref overview_eventhandling, wxTopLevelWindow::Iconize,
2630 wxTopLevelWindow::IsIconized
2631 */
2632 class wxIconizeEvent : public wxEvent
2633 {
2634 public:
2635 /**
2636 Constructor.
2637 */
2638 wxIconizeEvent(int id = 0, bool iconized = true);
2639
2640 /**
2641 Returns @true if the frame has been iconized, @false if it has been
2642 restored.
2643 */
2644 bool Iconized() const;
2645 };
2646
2647
2648
2649 /**
2650 @class wxMoveEvent
2651 @wxheader{event.h}
2652
2653 A move event holds information about move change events.
2654
2655 @library{wxcore}
2656 @category{events}
2657
2658 @see wxPoint, @ref overview_eventhandling
2659 */
2660 class wxMoveEvent : public wxEvent
2661 {
2662 public:
2663 /**
2664 Constructor.
2665 */
2666 wxMoveEvent(const wxPoint& pt, int id = 0);
2667
2668 /**
2669 Returns the position of the window generating the move change event.
2670 */
2671 wxPoint GetPosition() const;
2672 };
2673
2674
2675
2676 /**
2677 @class wxEvent
2678 @wxheader{event.h}
2679
2680 An event is a structure holding information about an event passed to a
2681 callback or member function. @b wxEvent used to be a multipurpose
2682 event object, and is an abstract base class for other event classes (see below).
2683
2684 For more information about events, see the @ref overview_eventhandling.
2685
2686 @b wxPerl note: In wxPerl custom event classes should be derived from
2687 @c Wx::PlEvent and @c Wx::PlCommandEvent.
2688
2689 @library{wxbase}
2690 @category{events}
2691
2692 @see wxCommandEvent, wxMouseEvent
2693 */
2694 class wxEvent : public wxObject
2695 {
2696 public:
2697 /**
2698 Constructor. Should not need to be used directly by an application.
2699 */
2700 wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL);
2701
2702 /**
2703 Returns a copy of the event.
2704 Any event that is posted to the wxWidgets event system for later action (via
2705 wxEvtHandler::AddPendingEvent or
2706 wxPostEvent()) must implement this method. All wxWidgets
2707 events fully implement this method, but any derived events implemented by the
2708 user should also implement this method just in case they (or some event
2709 derived from them) are ever posted.
2710 All wxWidgets events implement a copy constructor, so the easiest way of
2711 implementing the Clone function is to implement a copy constructor for
2712 a new event (call it MyEvent) and then define the Clone function like this:
2713 */
2714 virtual wxEvent* Clone() const = 0;
2715
2716 /**
2717 Returns the object (usually a window) associated with the
2718 event, if any.
2719 */
2720 wxObject* GetEventObject() const;
2721
2722 /**
2723 Returns the identifier of the given event type,
2724 such as @c wxEVT_COMMAND_BUTTON_CLICKED.
2725 */
2726 wxEventType GetEventType() const;
2727
2728 /**
2729 Returns the identifier associated with this event, such as a button command id.
2730 */
2731 int GetId() const;
2732
2733 /**
2734 Returns @true if the event handler should be skipped, @false otherwise.
2735 */
2736 bool GetSkipped() const;
2737
2738 /**
2739 Gets the timestamp for the event. The timestamp is the time in milliseconds
2740 since some fixed moment (not necessarily the standard Unix Epoch, so
2741 only differences between the timestamps and not their absolute values usually
2742 make sense).
2743 */
2744 long GetTimestamp() const;
2745
2746 /**
2747 Returns @true if the event is or is derived from
2748 wxCommandEvent else it returns @false.
2749 Note: Exists only for optimization purposes.
2750 */
2751 bool IsCommandEvent() const;
2752
2753 /**
2754 Sets the propagation level to the given value (for example returned from an
2755 earlier call to wxEvent::StopPropagation).
2756 */
2757 void ResumePropagation(int propagationLevel);
2758
2759 /**
2760 Sets the originating object.
2761 */
2762 void SetEventObject(wxObject* object);
2763
2764 /**
2765 Sets the event type.
2766 */
2767 void SetEventType(wxEventType type);
2768
2769 /**
2770 Sets the identifier associated with this event, such as a button command id.
2771 */
2772 void SetId(int id);
2773
2774 /**
2775 Sets the timestamp for the event.
2776 */
2777 void SetTimestamp(long = 0);
2778
2779 /**
2780 Test if this event should be propagated or not, i.e. if the propagation level
2781 is currently greater than 0.
2782 */
2783 bool ShouldPropagate() const;
2784
2785 /**
2786 This method can be used inside an event handler to control whether further
2787 event handlers bound to this event will be called after the current one
2788 returns. Without Skip() (or equivalently if Skip(@false) is used),
2789 the event will not be processed any more. If Skip(@true) is called, the event
2790 processing system continues searching for a further handler function for this
2791 event, even though it has been processed already in the current handler.
2792 In general, it is recommended to skip all non-command events to allow the
2793 default handling to take place. The command events are, however, normally not
2794 skipped as usually a single command such as a button click or menu item
2795 selection must only be processed by one handler.
2796 */
2797 void Skip(bool skip = true);
2798
2799 /**
2800 Stop the event from propagating to its parent window.
2801 Returns the old propagation level value which may be later passed to
2802 ResumePropagation() to allow propagating the
2803 event again.
2804 */
2805 int StopPropagation();
2806
2807 /**
2808 int m_propagationLevel
2809 Indicates how many levels the event can propagate. This member is protected and
2810 should typically only be set in the constructors of the derived classes. It
2811 may be temporarily changed by StopPropagation()
2812 and ResumePropagation() and tested with
2813 ShouldPropagate().
2814 The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by
2815 default) meaning that the event shouldn't be propagated at all or to
2816 @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be
2817 propagated as much as necessary.
2818 Any positive number means that the event should be propagated but no more than
2819 the given number of times. E.g. the propagation level may be set to 1 to
2820 propagate the event to its parent only, but not to its grandparent.
2821 */
2822 };
2823
2824
2825
2826 /**
2827 @class wxSizeEvent
2828 @wxheader{event.h}
2829
2830 A size event holds information about size change events.
2831
2832 The EVT_SIZE handler function will be called when the window has been resized.
2833
2834 You may wish to use this for frames to resize their child windows as
2835 appropriate.
2836
2837 Note that the size passed is of
2838 the whole window: call wxWindow::GetClientSize for the area which may be
2839 used by the application.
2840
2841 When a window is resized, usually only a small part of the window is damaged
2842 and you
2843 may only need to repaint that area. However, if your drawing depends on the
2844 size of the window,
2845 you may need to clear the DC explicitly and repaint the whole window. In which
2846 case, you
2847 may need to call wxWindow::Refresh to invalidate the entire window.
2848
2849 @library{wxcore}
2850 @category{events}
2851
2852 @see wxSize, @ref overview_eventhandling
2853 */
2854 class wxSizeEvent : public wxEvent
2855 {
2856 public:
2857 /**
2858 Constructor.
2859 */
2860 wxSizeEvent(const wxSize& sz, int id = 0);
2861
2862 /**
2863 Returns the entire size of the window generating the size change event.
2864 */
2865 wxSize GetSize() const;
2866 };
2867
2868
2869
2870 /**
2871 @class wxSetCursorEvent
2872 @wxheader{event.h}
2873
2874 A SetCursorEvent is generated when the mouse cursor is about to be set as a
2875 result of mouse motion. This event gives the application the chance to perform
2876 specific mouse cursor processing based on the current position of the mouse
2877 within the window. Use wxSetCursorEvent::SetCursor to
2878 specify the cursor you want to be displayed.
2879
2880 @library{wxcore}
2881 @category{events}
2882
2883 @see ::wxSetCursor, wxWindow::wxSetCursor
2884 */
2885 class wxSetCursorEvent : public wxEvent
2886 {
2887 public:
2888 /**
2889 Constructor, used by the library itself internally to initialize the event
2890 object.
2891 */
2892 wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0);
2893
2894 /**
2895 Returns a reference to the cursor specified by this event.
2896 */
2897 const wxCursor& GetCursor() const;
2898
2899 /**
2900 Returns the X coordinate of the mouse in client coordinates.
2901 */
2902 wxCoord GetX() const;
2903
2904 /**
2905 Returns the Y coordinate of the mouse in client coordinates.
2906 */
2907 wxCoord GetY() const;
2908
2909 /**
2910 Returns @true if the cursor specified by this event is a valid cursor.
2911
2912 @remarks You cannot specify wxNullCursor with this event, as it is not
2913 considered a valid cursor.
2914 */
2915 bool HasCursor() const;
2916
2917 /**
2918 Sets the cursor associated with this event.
2919 */
2920 void SetCursor(const wxCursor& cursor);
2921 };
2922
2923
2924
2925 // ============================================================================
2926 // Global functions/macros
2927 // ============================================================================
2928
2929 /** @ingroup group_funcmacro_misc */
2930 //@{
2931
2932 /**
2933 In a GUI application, this function posts @a event to the specified @e dest
2934 object using wxEvtHandler::AddPendingEvent().
2935
2936 Otherwise, it dispatches @a event immediately using
2937 wxEvtHandler::ProcessEvent(). See the respective documentation for details
2938 (and caveats).
2939
2940 @header{wx/event.h}
2941 */
2942 void wxPostEvent(wxEvtHandler* dest, wxEvent& event);
2943
2944 //@}
2945