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