1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxEventHandler, wxEventBlocker and many
4 // wxEvent-derived classes
5 // Author: wxWidgets team
7 // Licence: wxWindows license
8 /////////////////////////////////////////////////////////////////////////////
16 An event is a structure holding information about an event passed to a
17 callback or member function.
19 wxEvent used to be a multipurpose event object, and is an abstract base class
20 for other event classes (see below).
22 For more information about events, see the @ref overview_eventhandling overview.
25 In wxPerl custom event classes should be derived from
26 @c Wx::PlEvent and @c Wx::PlCommandEvent.
32 @see wxCommandEvent, wxMouseEvent
34 class wxEvent
: public wxObject
38 Constructor. Should not need to be used directly by an application.
40 wxEvent(int id
= 0, wxEventType eventType
= wxEVT_NULL
);
43 Returns a copy of the event.
45 Any event that is posted to the wxWidgets event system for later action (via
46 wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement this method.
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.
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:
57 wxEvent *Clone() const { return new MyEvent(*this); }
60 virtual wxEvent
* Clone() const = 0;
63 Returns the object (usually a window) associated with the event, if any.
65 wxObject
* GetEventObject() const;
68 Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED.
70 wxEventType
GetEventType() const;
73 Returns the identifier associated with this event, such as a button command id.
78 Returns @true if the event handler should be skipped, @false otherwise.
80 bool GetSkipped() const;
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).
87 long GetTimestamp() const;
90 Returns @true if the event is or is derived from wxCommandEvent else it returns @false.
92 @note exists only for optimization purposes.
94 bool IsCommandEvent() const;
97 Sets the propagation level to the given value (for example returned from an
98 earlier call to wxEvent::StopPropagation).
100 void ResumePropagation(int propagationLevel
);
103 Sets the originating object.
105 void SetEventObject(wxObject
* object
);
110 void SetEventType(wxEventType type
);
113 Sets the identifier associated with this event, such as a button command id.
118 Sets the timestamp for the event.
120 void SetTimestamp(long = 0);
123 Test if this event should be propagated or not, i.e. if the propagation level
124 is currently greater than 0.
126 bool ShouldPropagate() const;
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.
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.
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.
142 void Skip(bool skip
= true);
145 Stop the event from propagating to its parent window.
147 Returns the old propagation level value which may be later passed to
148 ResumePropagation() to allow propagating the event again.
150 int StopPropagation();
154 Indicates how many levels the event can propagate.
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().
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.
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.
169 int m_propagationLevel
;
173 @class wxEventBlocker
176 This class is a special event handler which allows to discard
177 any event (or a set of event types) directed to a specific window.
182 void MyWindow::DoSomething()
185 // block all events directed to this window while
186 // we do the 1000 FunctionWhichSendsEvents() calls
187 wxEventBlocker blocker(this);
189 for ( int i = 0; i 1000; i++ )
190 FunctionWhichSendsEvents(i);
192 } // ~wxEventBlocker called, old event handler is restored
194 // the event generated by this call will be processed:
195 FunctionWhichSendsEvents(0)
202 @see @ref overview_eventhandling, wxEvtHandler
204 class wxEventBlocker
: public wxEvtHandler
208 Constructs the blocker for the given window and for the given event type.
210 If @a type is @c wxEVT_ANY, then all events for that window are blocked.
211 You can call Block() after creation to add other event types to the list
214 Note that the @a win window @b must remain alive until the
215 wxEventBlocker object destruction.
217 wxEventBlocker(wxWindow
* win
, wxEventType
= wxEVT_ANY
);
220 Destructor. The blocker will remove itself from the chain of event handlers for
221 the window provided in the constructor, thus restoring normal processing of events.
223 virtual ~wxEventBlocker();
226 Adds to the list of event types which should be blocked the given @a eventType.
228 void Block(wxEventType eventType
);
237 A class that can handle events from the windowing system.
238 wxWindow (and therefore all window classes) are derived from this class.
240 When events are received, wxEvtHandler invokes the method listed in the
241 event table using itself as the object. When using multiple inheritance
242 it is imperative that the wxEvtHandler(-derived) class be the first
243 class inherited such that the "this" pointer for the overall object
244 will be identical to the "this" pointer for the wxEvtHandler portion.
249 @see @ref overview_eventhandling
251 class wxEvtHandler
: public wxObject
262 If the handler is part of a chain, the destructor will unlink itself and
263 restore the previous and next handlers so that they point to each other.
265 virtual ~wxEvtHandler();
268 This function posts an event to be processed later.
270 The difference between sending an event (using the ProcessEvent
271 method) and posting it is that in the first case the event is
272 processed before the function returns, while in the second case,
273 the function returns immediately and the event will be processed
274 sometime later (usually during the next event loop iteration).
276 A copy of event is made by the function, so the original can be deleted as
277 soon as function returns (it is common that the original is created on the
278 stack). This requires that the wxEvent::Clone method be implemented by event
279 so that it can be duplicated and stored until it gets processed.
281 This is also the method to call for inter-thread communication - it will post
282 events safely between different threads which means that this method is
283 thread-safe by using critical sections where needed. In a multi-threaded program,
284 you often need to inform the main GUI thread about the status of other working
285 threads and such notification should be done using this method.
287 This method automatically wakes up idle handling if the underlying window
288 system is currently idle and thus would not send any idle events.
289 (Waking up idle handling is done calling ::wxWakeUpIdle.)
292 Event to add to process queue.
294 virtual void AddPendingEvent(const wxEvent
& event
);
297 Connects the given function dynamically with the event handler, id and event type.
298 This is an alternative to the use of static event tables.
300 See the @ref page_samples_event sample for usage.
302 This specific overload allows you to connect an event handler to a @e range
304 Do not confuse @e source IDs with event @e types: source IDs identify the
305 event generator objects (typically wxMenuItem or wxWindow objects) while the
306 event @e type identify which type of events should be handled by the
307 given @e function (an event generator object may generate many different
311 The first ID of the identifier range to be associated with the event
314 The last ID of the identifier range to be associated with the event
317 The event type to be associated with this event handler.
319 The event handler function. Note that this function should
320 be explicitly converted to the correct type which can be done using a macro
321 called @c wxFooEventHandler for the handler for any @c wxFooEvent.
323 Data to be associated with the event table entry.
325 Object whose member function should be called.
326 If this is @NULL, @c *this will be used.
328 void Connect(int id
, int lastId
, wxEventType eventType
,
329 wxObjectEventFunction function
,
330 wxObject
* userData
= NULL
,
331 wxEvtHandler
* eventSink
= NULL
);
334 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
335 overload for more info.
337 This overload can be used to attach an event handler to a single source ID:
341 frame->Connect( wxID_EXIT,
342 wxEVT_COMMAND_MENU_SELECTED,
343 wxCommandEventHandler(MyFrame::OnQuit) );
346 void Connect(int id
, wxEventType eventType
,
347 wxObjectEventFunction function
,
348 wxObject
* userData
= NULL
,
349 wxEvtHandler
* eventSink
= NULL
);
352 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
353 overload for more info.
355 This overload will connect the given event handler so that regardless of the
356 ID of the event source, the handler will be called.
358 void Connect(wxEventType eventType
,
359 wxObjectEventFunction function
,
360 wxObject
* userData
= NULL
,
361 wxEvtHandler
* eventSink
= NULL
);
364 Disconnects the given function dynamically from the event handler, using the
365 specified parameters as search criteria and returning @true if a matching
366 function has been found and removed.
368 This method can only disconnect functions which have been added using the
369 Connect() method. There is no way to disconnect functions connected using
370 the (static) event tables.
373 The event type associated with this event handler.
375 The event handler function.
377 Data associated with the event table entry.
379 Object whose member function should be called.
381 bool Disconnect(wxEventType eventType
= wxEVT_NULL
,
382 wxObjectEventFunction function
= NULL
,
383 wxObject
* userData
= NULL
,
384 wxEvtHandler
* eventSink
= NULL
);
387 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
388 overload for more info.
390 This overload takes the additional @a id parameter.
392 bool Disconnect(int id
= wxID_ANY
,
393 wxEventType eventType
= wxEVT_NULL
,
394 wxObjectEventFunction function
= NULL
,
395 wxObject
* userData
= NULL
,
396 wxEvtHandler
* eventSink
= NULL
);
399 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
400 overload for more info.
402 This overload takes an additional range of source IDs.
404 bool Disconnect(int id
, int lastId
= wxID_ANY
,
405 wxEventType eventType
= wxEVT_NULL
,
406 wxObjectEventFunction function
= NULL
,
407 wxObject
* userData
= NULL
,
408 wxEvtHandler
* eventSink
= NULL
);
411 Returns user-supplied client data.
413 @remarks Normally, any extra data the programmer wishes to associate with
414 the object should be made available by deriving a new class with
419 void* GetClientData() const;
422 Returns a pointer to the user-supplied client data object.
424 @see SetClientObject(), wxClientData
426 wxClientData
* GetClientObject() const;
429 Returns @true if the event handler is enabled, @false otherwise.
431 @see SetEvtHandlerEnabled()
433 bool GetEvtHandlerEnabled() const;
436 Returns the pointer to the next handler in the chain.
438 @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
439 wxWindow::PushEventHandler, wxWindow::PopEventHandler
441 wxEvtHandler
* GetNextHandler() const;
444 Returns the pointer to the previous handler in the chain.
446 @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
447 wxWindow::PushEventHandler, wxWindow::PopEventHandler
449 wxEvtHandler
* GetPreviousHandler() const;
452 Processes an event, searching event tables and calling zero or more suitable
453 event handler function(s).
455 Normally, your application would not call this function: it is called in the
456 wxWidgets implementation to dispatch incoming user interface events to the
457 framework (and application).
459 However, you might need to call it if implementing new functionality
460 (such as a new control) where you define new event types, as opposed to
461 allowing the user to override virtual functions.
463 An instance where you might actually override the ProcessEvent function is where
464 you want to direct event processing to event handlers not normally noticed by
465 wxWidgets. For example, in the document/view architecture, documents and views
466 are potential event handlers. When an event reaches a frame, ProcessEvent will
467 need to be called on the associated document and view in case event handler functions
468 are associated with these objects. The property classes library (wxProperty) also
469 overrides ProcessEvent for similar reasons.
471 The normal order of event table searching is as follows:
472 -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
473 the function skips to step (6).
474 -# If the object is a wxWindow, ProcessEvent() is recursively called on the
475 window's wxValidator. If this returns @true, the function exits.
476 -# SearchEventTable() is called for this event handler. If this fails, the base
477 class table is tried, and so on until no more tables exist or an appropriate
478 function was found, in which case the function exits.
479 -# The search is applied down the entire chain of event handlers (usually the
480 chain has a length of one). If this succeeds, the function exits.
481 -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
482 is recursively applied to the parent window's event handler.
483 If this returns true, the function exits.
484 -# Finally, ProcessEvent() is called on the wxApp object.
489 @returns @true if a suitable event handler function was found and
490 executed, and the function did not call wxEvent::Skip.
492 @see SearchEventTable()
494 virtual bool ProcessEvent(wxEvent
& event
);
497 Processes an event by calling ProcessEvent() and handles any exceptions
498 that occur in the process.
499 If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
504 @returns @true if the event was processed, @false if no handler was found
505 or an exception was thrown.
507 @see wxWindow::HandleWindowEvent
509 bool SafelyProcessEvent(wxEvent
& event
);
512 Searches the event table, executing an event handler function if an appropriate
516 Event table to be searched.
518 Event to be matched against an event table entry.
520 @returns @true if a suitable event handler function was found and
521 executed, and the function did not call wxEvent::Skip.
523 @remarks This function looks through the object's event table and tries
524 to find an entry that will match the event.
525 An entry will match if:
526 @li The event type matches, and
527 @li the identifier or identifier range matches, or the event table
528 entry's identifier is zero.
529 If a suitable function is called but calls wxEvent::Skip, this
530 function will fail, and searching will continue.
534 virtual bool SearchEventTable(wxEventTable
& table
,
538 Sets user-supplied client data.
541 Data to be associated with the event handler.
543 @remarks Normally, any extra data the programmer wishes to associate
544 with the object should be made available by deriving a new
545 class with new data members. You must not call this method
546 and SetClientObject on the same class - only one of them.
550 void SetClientData(void* data
);
553 Set the client data object. Any previous object will be deleted.
555 @see GetClientObject(), wxClientData
557 void SetClientObject(wxClientData
* data
);
560 Enables or disables the event handler.
563 @true if the event handler is to be enabled, @false if it is to be disabled.
565 @remarks You can use this function to avoid having to remove the event
566 handler from the chain, for example when implementing a
567 dialog editor and changing from edit to test mode.
569 @see GetEvtHandlerEnabled()
571 void SetEvtHandlerEnabled(bool enabled
);
574 Sets the pointer to the next handler.
577 Event handler to be set as the next handler.
579 @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(),
580 wxWindow::PushEventHandler, wxWindow::PopEventHandler
582 void SetNextHandler(wxEvtHandler
* handler
);
585 Sets the pointer to the previous handler.
588 Event handler to be set as the previous handler.
590 void SetPreviousHandler(wxEvtHandler
* handler
);
598 This event class contains information about keypress (character) events.
600 Notice that there are three different kinds of keyboard events in wxWidgets:
601 key down and up events and char events. The difference between the first two
602 is clear - the first corresponds to a key press and the second to a key
603 release - otherwise they are identical. Just note that if the key is
604 maintained in a pressed state you will typically get a lot of (automatically
605 generated) down events but only one up so it is wrong to assume that there is
606 one up event corresponding to each down one.
608 Both key events provide untranslated key codes while the char event carries
609 the translated one. The untranslated code for alphanumeric keys is always
610 an upper case value. For the other keys it is one of @c WXK_XXX values
611 from the @ref page_keycodes.
612 The translated key is, in general, the character the user expects to appear
613 as the result of the key combination when typing the text into a text entry
616 A few examples to clarify this (all assume that CAPS LOCK is unpressed
617 and the standard US keyboard): when the @c 'A' key is pressed, the key down
618 event key code is equal to @c ASCII A == 65. But the char event key code
619 is @c ASCII a == 97. On the other hand, if you press both SHIFT and
620 @c 'A' keys simultaneously , the key code in key down event will still be
621 just @c 'A' while the char event key code parameter will now be @c 'A'
624 Although in this simple case it is clear that the correct key code could be
625 found in the key down event handler by checking the value returned by
626 wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as
627 for non-alphanumeric keys the translation is keyboard-layout dependent and
628 can only be done properly by the system itself.
630 Another kind of translation is done when the control key is pressed: for
631 example, for CTRL-A key press the key down event still carries the
632 same key code @c 'a' as usual but the char event will have key code of 1,
633 the ASCII value of this key combination.
635 You may discover how the other keys on your system behave interactively by
636 running the @ref page_samples_text wxWidgets sample and pressing some keys
637 in any of the text controls shown in it.
639 @b Tip: be sure to call @c event.Skip() for events that you don't process in
640 key event function, otherwise menu shortcuts may cease to work under Windows.
642 @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
643 does not call @c event.Skip() then the corresponding char event
644 (@c EVT_CHAR) will not happen.
645 This is by design and enables the programs that handle both types of
646 events to be a bit simpler.
648 @note For Windows programmers: The key and char events in wxWidgets are
649 similar to but slightly different from Windows @c WM_KEYDOWN and
650 @c WM_CHAR events. In particular, Alt-x combination will generate a
651 char event in wxWidgets (unless it is used as an accelerator).
654 @beginEventTable{wxKeyEvent}
655 @event{EVT_KEY_DOWN(func)}:
656 Process a wxEVT_KEY_DOWN event (any key has been pressed).
657 @event{EVT_KEY_UP(func)}:
658 Process a wxEVT_KEY_UP event (any key has been released).
659 @event{EVT_CHAR(func)}:
660 Process a wxEVT_CHAR event.
666 class wxKeyEvent
: public wxEvent
671 Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
673 wxKeyEvent(wxEventType keyEventType
= wxEVT_NULL
);
676 Returns @true if the Alt key was down at the time of the key event.
678 Notice that GetModifiers() is easier to use correctly than this function
679 so you should consider using it in new code.
681 bool AltDown() const;
684 CMD is a pseudo key which is the same as Control for PC and Unix
685 platforms but the special APPLE (a.k.a as COMMAND) key under Macs:
686 it makes often sense to use it instead of, say, ControlDown() because Cmd
687 key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still
688 exists, just not used for this purpose under Mac). So for non-Mac platforms
689 this is the same as ControlDown() and under Mac this is the same as MetaDown().
691 bool CmdDown() const;
694 Returns @true if the control key was down at the time of the key event.
696 Notice that GetModifiers() is easier to use correctly than this function
697 so you should consider using it in new code.
699 bool ControlDown() const;
702 Returns the virtual key code. ASCII events return normal ASCII values,
703 while non-ASCII events return values such as @b WXK_LEFT for the left cursor
704 key. See @ref page_keycodes for a full list of the virtual key codes.
706 Note that in Unicode build, the returned value is meaningful only if the
707 user entered a character that can be represented in current locale's default
708 charset. You can obtain the corresponding Unicode character using GetUnicodeKey().
710 int GetKeyCode() const;
713 Return the bitmask of modifier keys which were pressed when this event
714 happened. See @ref page_keymodifiers for the full list of modifiers.
716 Notice that this function is easier to use correctly than, for example,
717 ControlDown() because when using the latter you also have to remember to
718 test that none of the other modifiers is pressed:
721 if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
722 ... handle Ctrl-XXX ...
725 and forgetting to do it can result in serious program bugs (e.g. program
726 not working with European keyboard layout where ALTGR key which is seen by
727 the program as combination of CTRL and ALT is used). On the other hand,
728 you can simply write:
731 if ( GetModifiers() == wxMOD_CONTROL )
732 ... handle Ctrl-XXX ...
737 int GetModifiers() const;
741 Obtains the position (in client coordinates) at which the key was pressed.
743 wxPoint
GetPosition() const;
744 void GetPosition(long* x
, long* y
) const;
748 Returns the raw key code for this event. This is a platform-dependent scan code
749 which should only be used in advanced applications.
751 @note Currently the raw key codes are not supported by all ports, use
752 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
754 wxUint32
GetRawKeyCode() const;
757 Returns the low level key flags for this event. The flags are
758 platform-dependent and should only be used in advanced applications.
760 @note Currently the raw key flags are not supported by all ports, use
761 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
763 wxUint32
GetRawKeyFlags() const;
766 Returns the Unicode character corresponding to this key event.
768 This function is only available in Unicode build, i.e. when
769 @c wxUSE_UNICODE is 1.
771 wxChar
GetUnicodeKey() const;
774 Returns the X position (in client coordinates) of the event.
776 wxCoord
GetX() const;
779 Returns the Y position (in client coordinates) of the event.
781 wxCoord
GetY() const;
784 Returns @true if either CTRL or ALT keys was down at the time of the
787 Note that this function does not take into account neither SHIFT nor
788 META key states (the reason for ignoring the latter is that it is
789 common for NUMLOCK key to be configured as META under X but the key
790 presses even while NUMLOCK is on should be still processed normally).
792 bool HasModifiers() const;
795 Returns @true if the Meta key was down at the time of the key event.
797 Notice that GetModifiers() is easier to use correctly than this function
798 so you should consider using it in new code.
800 bool MetaDown() const;
803 Returns @true if the shift key was down at the time of the key event.
805 Notice that GetModifiers() is easier to use correctly than this function
806 so you should consider using it in new code.
808 bool ShiftDown() const;
814 @class wxJoystickEvent
817 This event class contains information about joystick events, particularly
818 events received by windows.
820 @beginEventTable{wxJoystickEvent}
821 @style{EVT_JOY_BUTTON_DOWN(func)}:
822 Process a wxEVT_JOY_BUTTON_DOWN event.
823 @style{EVT_JOY_BUTTON_UP(func)}:
824 Process a wxEVT_JOY_BUTTON_UP event.
825 @style{EVT_JOY_MOVE(func)}:
826 Process a wxEVT_JOY_MOVE event.
827 @style{EVT_JOY_ZMOVE(func)}:
828 Process a wxEVT_JOY_ZMOVE event.
829 @style{EVT_JOYSTICK_EVENTS(func)}:
830 Processes all joystick events.
838 class wxJoystickEvent
: public wxEvent
844 wxJoystickEvent(wxEventType eventType
= wxEVT_NULL
, int state
= 0,
845 int joystick
= wxJOYSTICK1
,
849 Returns @true if the event was a down event from the specified button
853 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
854 indicate any button down event.
856 bool ButtonDown(int button
= wxJOY_BUTTON_ANY
) const;
859 Returns @true if the specified button (or any button) was in a down state.
862 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
863 indicate any button down event.
865 bool ButtonIsDown(int button
= wxJOY_BUTTON_ANY
) const;
868 Returns @true if the event was an up event from the specified button
872 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
873 indicate any button down event.
875 bool ButtonUp(int button
= wxJOY_BUTTON_ANY
) const;
878 Returns the identifier of the button changing state.
880 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
882 int GetButtonChange() const;
885 Returns the down state of the buttons.
887 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
889 int GetButtonState() const;
892 Returns the identifier of the joystick generating the event - one of
893 wxJOYSTICK1 and wxJOYSTICK2.
895 int GetJoystick() const;
898 Returns the x, y position of the joystick event.
900 wxPoint
GetPosition() const;
903 Returns the z position of the joystick event.
905 int GetZPosition() const;
908 Returns @true if this was a button up or down event
909 (@e not 'is any button down?').
911 bool IsButton() const;
914 Returns @true if this was an x, y move event.
919 Returns @true if this was a z move event.
921 bool IsZMove() const;
927 @class wxScrollWinEvent
930 A scroll event holds information about events sent from scrolling windows.
933 @beginEventTable{wxScrollWinEvent}
934 You can use the EVT_SCROLLWIN* macros for intercepting scroll window events
935 from the receiving window.
936 @event{EVT_SCROLLWIN(func)}:
937 Process all scroll events.
938 @event{EVT_SCROLLWIN_TOP(func)}:
939 Process wxEVT_SCROLLWIN_TOP scroll-to-top events.
940 @event{EVT_SCROLLWIN_BOTTOM(func)}:
941 Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
942 @event{EVT_SCROLLWIN_LINEUP(func)}:
943 Process wxEVT_SCROLLWIN_LINEUP line up events.
944 @event{EVT_SCROLLWIN_LINEDOWN(func)}:
945 Process wxEVT_SCROLLWIN_LINEDOWN line down events.
946 @event{EVT_SCROLLWIN_PAGEUP(func)}:
947 Process wxEVT_SCROLLWIN_PAGEUP page up events.
948 @event{EVT_SCROLLWIN_PAGEDOWN(func)}:
949 Process wxEVT_SCROLLWIN_PAGEDOWN page down events.
950 @event{EVT_SCROLLWIN_THUMBTRACK(func)}:
951 Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
952 (frequent events sent as the user drags the thumbtrack).
953 @event{EVT_SCROLLWIN_THUMBRELEASE(func)}:
954 Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
961 @see wxScrollEvent, @ref overview_eventhandling
963 class wxScrollWinEvent
: public wxEvent
969 wxScrollWinEvent(wxEventType commandType
= wxEVT_NULL
, int pos
= 0,
970 int orientation
= 0);
973 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
976 @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
978 int GetOrientation() const;
981 Returns the position of the scrollbar for the thumb track and release events.
983 Note that this field can't be used for the other events, you need to query
984 the window itself for the current position in that case.
986 int GetPosition() const;
992 @class wxSysColourChangedEvent
995 This class is used for system colour change events, which are generated
996 when the user changes the colour settings using the control panel.
997 This is only appropriate under Windows.
1000 The default event handler for this event propagates the event to child windows,
1001 since Windows only sends the events to top-level windows.
1002 If intercepting this event for a top-level window, remember to call the base
1003 class handler, or to pass the event on to the window's children explicitly.
1005 @beginEventTable{wxSysColourChangedEvent}
1006 @event{EVT_SYS_COLOUR_CHANGED(func)}:
1007 Process a wxEVT_SYS_COLOUR_CHANGED event.
1013 @see @ref overview_eventhandling
1015 class wxSysColourChangedEvent
: public wxEvent
1021 wxSysColourChangedEvent();
1027 @class wxWindowCreateEvent
1030 This event is sent just after the actual window associated with a wxWindow
1031 object has been created.
1033 Since it is derived from wxCommandEvent, the event propagates up
1034 the window hierarchy.
1036 @beginEventTable{wxWindowCreateEvent}
1037 @event{EVT_WINDOW_CREATE(func)}:
1038 Process a wxEVT_CREATE event.
1044 @see @ref overview_eventhandling, wxWindowDestroyEvent
1046 class wxWindowCreateEvent
: public wxCommandEvent
1052 wxWindowCreateEvent(wxWindow
* win
= NULL
);
1061 A paint event is sent when a window's contents needs to be repainted.
1063 Please notice that in general it is impossible to change the drawing of a
1064 standard control (such as wxButton) and so you shouldn't attempt to handle
1065 paint events for them as even if it might work on some platforms, this is
1066 inherently not portable and won't work everywhere.
1069 Note that in a paint event handler, the application must always create a
1070 wxPaintDC object, even if you do not use it. Otherwise, under MS Windows,
1071 refreshing for this and other windows will go wrong.
1074 void MyWindow::OnPaint(wxPaintEvent& event)
1081 You can optimize painting by retrieving the rectangles that have been damaged
1082 and only repainting these. The rectangles are in terms of the client area,
1083 and are unscrolled, so you will need to do some calculations using the current
1084 view position to obtain logical, scrolled units.
1085 Here is an example of using the wxRegionIterator class:
1087 // Called when window needs to be repainted.
1088 void MyWindow::OnPaint(wxPaintEvent& event)
1092 // Find Out where the window is scrolled to
1093 int vbX,vbY; // Top left corner of client
1094 GetViewStart(&vbX,&vbY);
1096 int vX,vY,vW,vH; // Dimensions of client area in pixels
1097 wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
1106 // Alternatively we can do this:
1107 // wxRect rect(upd.GetRect());
1109 // Repaint this rectangle
1118 @beginEventTable{wxPaintEvent}
1119 @event{EVT_PAINT(func)}:
1120 Process a wxEVT_PAINT event.
1126 @see @ref overview_eventhandling
1128 class wxPaintEvent
: public wxEvent
1134 wxPaintEvent(int id
= 0);
1140 @class wxMaximizeEvent
1143 An event being sent when a top level window is maximized. Notice that it is
1144 not sent when the window is restored to its original size after it had been
1145 maximized, only a normal wxSizeEvent is generated in this case.
1147 @beginEventTable{wxMaximizeEvent}
1148 @event{EVT_MAXIMIZE(func)}:
1149 Process a wxEVT_MAXIMIZE event.
1155 @see @ref overview_eventhandling, wxTopLevelWindow::Maximize,
1156 wxTopLevelWindow::IsMaximized
1158 class wxMaximizeEvent
: public wxEvent
1162 Constructor. Only used by wxWidgets internally.
1164 wxMaximizeEvent(int id
= 0);
1168 The possibles modes to pass to wxUpdateUIEvent::SetMode().
1172 /** Send UI update events to all windows. */
1173 wxUPDATE_UI_PROCESS_ALL
,
1175 /** Send UI update events to windows that have
1176 the wxWS_EX_PROCESS_UI_UPDATES flag specified. */
1177 wxUPDATE_UI_PROCESS_SPECIFIED
1182 @class wxUpdateUIEvent
1185 This class is used for pseudo-events which are called by wxWidgets
1186 to give an application the chance to update various user interface elements.
1188 Without update UI events, an application has to work hard to check/uncheck,
1189 enable/disable, show/hide, and set the text for elements such as menu items
1190 and toolbar buttons. The code for doing this has to be mixed up with the code
1191 that is invoked when an action is invoked for a menu item or button.
1193 With update UI events, you define an event handler to look at the state of the
1194 application and change UI elements accordingly. wxWidgets will call your member
1195 functions in idle time, so you don't have to worry where to call this code.
1197 In addition to being a clearer and more declarative method, it also means you don't
1198 have to worry whether you're updating a toolbar or menubar identifier. The same
1199 handler can update a menu item and toolbar button, if the identifier is the same.
1200 Instead of directly manipulating the menu or button, you call functions in the event
1201 object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a
1202 call has been made, and which UI element to update.
1204 These events will work for popup menus as well as menubars. Just before a menu is
1205 popped up, wxMenu::UpdateUI is called to process any UI events for the window that
1208 If you find that the overhead of UI update processing is affecting your application,
1209 you can do one or both of the following:
1210 @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED,
1211 and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should
1212 receive update events. No other windows will receive update events.
1213 @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay
1214 between updates. You may need to call wxWindow::UpdateWindowUI at critical points,
1215 for example when a dialog is about to be shown, in case the user sees a slight
1216 delay before windows are updated.
1218 Note that although events are sent in idle time, defining a wxIdleEvent handler
1219 for a window does not affect this because the events are sent from wxWindow::OnInternalIdle
1220 which is always called in idle time.
1222 wxWidgets tries to optimize update events on some platforms.
1223 On Windows and GTK+, events for menubar items are only sent when the menu is about
1224 to be shown, and not in idle time.
1227 @beginEventTable{wxUpdateUIEvent}
1228 @event{EVT_UPDATE_UI(id, func)}:
1229 Process a wxEVT_UPDATE_UI event for the command with the given id.
1230 @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}:
1231 Process a wxEVT_UPDATE_UI event for any command with id included in the given range.
1237 @see @ref overview_eventhandling
1239 class wxUpdateUIEvent
: public wxCommandEvent
1245 wxUpdateUIEvent(wxWindowID commandId
= 0);
1248 Returns @true if it is appropriate to update (send UI update events to)
1251 This function looks at the mode used (see wxUpdateUIEvent::SetMode),
1252 the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events
1253 were last sent in idle time, and the update interval, to determine whether
1254 events should be sent to this window now. By default this will always
1255 return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL
1256 and the interval is set to 0; so update events will be sent as often as
1257 possible. You can reduce the frequency that events are sent by changing the
1258 mode and/or setting an update interval.
1260 @see ResetUpdateTime(), SetUpdateInterval(), SetMode()
1262 static bool CanUpdate(wxWindow
* window
);
1265 Check or uncheck the UI element.
1267 void Check(bool check
);
1270 Enable or disable the UI element.
1272 void Enable(bool enable
);
1275 Returns @true if the UI element should be checked.
1277 bool GetChecked() const;
1280 Returns @true if the UI element should be enabled.
1282 bool GetEnabled() const;
1285 Static function returning a value specifying how wxWidgets will send update
1286 events: to all windows, or only to those which specify that they will process
1291 static wxUpdateUIMode
GetMode();
1294 Returns @true if the application has called Check().
1295 For wxWidgets internal use only.
1297 bool GetSetChecked() const;
1300 Returns @true if the application has called Enable().
1301 For wxWidgets internal use only.
1303 bool GetSetEnabled() const;
1306 Returns @true if the application has called Show().
1307 For wxWidgets internal use only.
1309 bool GetSetShown() const;
1312 Returns @true if the application has called SetText().
1313 For wxWidgets internal use only.
1315 bool GetSetText() const;
1318 Returns @true if the UI element should be shown.
1320 bool GetShown() const;
1323 Returns the text that should be set for the UI element.
1325 wxString
GetText() const;
1328 Returns the current interval between updates in milliseconds.
1329 The value -1 disables updates, 0 updates as frequently as possible.
1331 @see SetUpdateInterval().
1333 static long GetUpdateInterval();
1336 Used internally to reset the last-updated time to the current time.
1338 It is assumed that update events are normally sent in idle time, so this
1339 is called at the end of idle processing.
1341 @see CanUpdate(), SetUpdateInterval(), SetMode()
1343 static void ResetUpdateTime();
1346 Specify how wxWidgets will send update events: to all windows, or only to
1347 those which specify that they will process the events.
1350 this parameter may be one of the ::wxUpdateUIMode enumeration values.
1351 The default mode is wxUPDATE_UI_PROCESS_ALL.
1353 static void SetMode(wxUpdateUIMode mode
);
1356 Sets the text for this UI element.
1358 void SetText(const wxString
& text
);
1361 Sets the interval between updates in milliseconds.
1363 Set to -1 to disable updates, or to 0 to update as frequently as possible.
1366 Use this to reduce the overhead of UI update events if your application
1367 has a lot of windows. If you set the value to -1 or greater than 0,
1368 you may also need to call wxWindow::UpdateWindowUI at appropriate points
1369 in your application, such as when a dialog is about to be shown.
1371 static void SetUpdateInterval(long updateInterval
);
1374 Show or hide the UI element.
1376 void Show(bool show
);
1382 @class wxClipboardTextEvent
1385 This class represents the events generated by a control (typically a
1386 wxTextCtrl but other windows can generate these events as well) when its
1387 content gets copied or cut to, or pasted from the clipboard.
1389 There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY,
1390 wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE.
1392 If any of these events is processed (without being skipped) by an event
1393 handler, the corresponding operation doesn't take place which allows to
1394 prevent the text from being copied from or pasted to a control. It is also
1395 possible to examine the clipboard contents in the PASTE event handler and
1396 transform it in some way before inserting in a control -- for example,
1397 changing its case or removing invalid characters.
1399 Finally notice that a CUT event is always preceded by the COPY event which
1400 makes it possible to only process the latter if it doesn't matter if the
1401 text was copied or cut.
1404 These events are currently only generated by wxTextCtrl under GTK+.
1405 They are generated by all controls under Windows.
1407 @beginEventTable{wxClipboardTextEvent}
1408 @event{EVT_TEXT_COPY(id, func)}:
1409 Some or all of the controls content was copied to the clipboard.
1410 @event{EVT_TEXT_CUT(id, func)}:
1411 Some or all of the controls content was cut (i.e. copied and
1413 @event{EVT_TEXT_PASTE(id, func)}:
1414 Clipboard content was pasted into the control.
1423 class wxClipboardTextEvent
: public wxCommandEvent
1429 wxClipboardTextEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
1438 This event class contains information about the events generated by the mouse:
1439 they include mouse buttons press and release events and mouse move events.
1441 All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the
1442 left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and
1443 @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more
1444 buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events
1445 can also be generated. Note that not all mice have even a middle button so a
1446 portable application should avoid relying on the events from it (but the right
1447 button click can be emulated using the left mouse button with the control key
1448 under Mac platforms with a single button mouse).
1450 For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events
1451 purposes, the mouse is considered to be inside the window if it is in the
1452 window client area and not inside one of its children. In other words, the
1453 parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
1454 mouse leaves the window entirely but also when it enters one of its children.
1456 @note Note that under Windows CE mouse enter and leave events are not natively
1457 supported by the system but are generated by wxWidgets itself. This has several
1458 drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
1459 left the window and the state variables for it may have changed during this time.
1461 @note Note the difference between methods like wxMouseEvent::LeftDown and
1462 wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds
1463 to the left mouse button click while the latter returns @true if the left
1464 mouse button is currently being pressed. For example, when the user is dragging
1465 the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse
1466 button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown
1467 returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets
1468 whatever the underlying GUI behaviour is (which is platform-dependent).
1469 The same applies, of course, to other mouse buttons as well.
1472 @beginEventTable{wxMouseEvent}
1473 @event{EVT_LEFT_DOWN(func)}:
1474 Process a wxEVT_LEFT_DOWN event. The handler of this event should normally
1475 call event.Skip() to allow the default processing to take place as otherwise
1476 the window under mouse wouldn't get the focus.
1477 @event{EVT_LEFT_UP(func)}:
1478 Process a wxEVT_LEFT_UP event.
1479 @event{EVT_LEFT_DCLICK(func)}:
1480 Process a wxEVT_LEFT_DCLICK event.
1481 @event{EVT_MIDDLE_DOWN(func)}:
1482 Process a wxEVT_MIDDLE_DOWN event.
1483 @event{EVT_MIDDLE_UP(func)}:
1484 Process a wxEVT_MIDDLE_UP event.
1485 @event{EVT_MIDDLE_DCLICK(func)}:
1486 Process a wxEVT_MIDDLE_DCLICK event.
1487 @event{EVT_RIGHT_DOWN(func)}:
1488 Process a wxEVT_RIGHT_DOWN event.
1489 @event{EVT_RIGHT_UP(func)}:
1490 Process a wxEVT_RIGHT_UP event.
1491 @event{EVT_RIGHT_DCLICK(func)}:
1492 Process a wxEVT_RIGHT_DCLICK event.
1493 @event{EVT_MOUSE_AUX1_DOWN(func)}:
1494 Process a wxEVT_MOUSE_AUX1_DOWN event.
1495 @event{EVT_MOUSE_AUX1_UP(func)}:
1496 Process a wxEVT_MOUSE_AUX1_UP event.
1497 @event{EVT_MOUSE_AUX1_DCLICK(func)}:
1498 Process a wxEVT_MOUSE_AUX1_DCLICK event.
1499 @event{EVT_MOUSE_AUX2_DOWN(func)}:
1500 Process a wxEVT_MOUSE_AUX2_DOWN event.
1501 @event{EVT_MOUSE_AUX2_UP(func)}:
1502 Process a wxEVT_MOUSE_AUX2_UP event.
1503 @event{EVT_MOUSE_AUX2_DCLICK(func)}:
1504 Process a wxEVT_MOUSE_AUX2_DCLICK event.
1505 @event{EVT_MOTION(func)}:
1506 Process a wxEVT_MOTION event.
1507 @event{EVT_ENTER_WINDOW(func)}:
1508 Process a wxEVT_ENTER_WINDOW event.
1509 @event{EVT_LEAVE_WINDOW(func)}:
1510 Process a wxEVT_LEAVE_WINDOW event.
1511 @event{EVT_MOUSEWHEEL(func)}:
1512 Process a wxEVT_MOUSEWHEEL event.
1513 @event{EVT_MOUSE_EVENTS(func)}:
1514 Process all mouse events.
1520 @see wxKeyEvent::CmdDown
1522 class wxMouseEvent
: public wxEvent
1526 Constructor. Valid event types are:
1528 @li wxEVT_ENTER_WINDOW
1529 @li wxEVT_LEAVE_WINDOW
1532 @li wxEVT_LEFT_DCLICK
1533 @li wxEVT_MIDDLE_DOWN
1535 @li wxEVT_MIDDLE_DCLICK
1536 @li wxEVT_RIGHT_DOWN
1538 @li wxEVT_RIGHT_DCLICK
1539 @li wxEVT_MOUSE_AUX1_DOWN
1540 @li wxEVT_MOUSE_AUX1_UP
1541 @li wxEVT_MOUSE_AUX1_DCLICK
1542 @li wxEVT_MOUSE_AUX2_DOWN
1543 @li wxEVT_MOUSE_AUX2_UP
1544 @li wxEVT_MOUSE_AUX2_DCLICK
1546 @li wxEVT_MOUSEWHEEL
1548 wxMouseEvent(wxEventType mouseEventType
= wxEVT_NULL
);
1551 Returns @true if the Alt key was down at the time of the event.
1553 bool AltDown() const;
1556 Returns @true if the event was a first extra button double click.
1558 bool Aux1DClick() const;
1561 Returns @true if the first extra button mouse button changed to down.
1563 bool Aux1Down() const;
1566 Returns @true if the first extra button mouse button is currently down,
1567 independent of the current event type.
1569 bool Aux1IsDown() const;
1572 Returns @true if the first extra button mouse button changed to up.
1574 bool Aux1Up() const;
1577 Returns @true if the event was a second extra button double click.
1579 bool Aux2DClick() const;
1582 Returns @true if the second extra button mouse button changed to down.
1584 bool Aux2Down() const;
1587 Returns @true if the second extra button mouse button is currently down,
1588 independent of the current event type.
1590 bool Aux2IsDown() const;
1593 Returns @true if the second extra button mouse button changed to up.
1595 bool Aux2Up() const;
1598 Returns @true if the identified mouse button is changing state.
1599 Valid values of @a button are:
1601 @li @c wxMOUSE_BTN_LEFT: check if left button was pressed
1602 @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed
1603 @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed
1604 @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed
1605 @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed
1606 @li @c wxMOUSE_BTN_ANY: check if any button was pressed
1608 @todo introduce wxMouseButton enum
1610 bool Button(int button
) const;
1613 If the argument is omitted, this returns @true if the event was a mouse
1614 double click event. Otherwise the argument specifies which double click event
1615 was generated (see Button() for the possible values).
1617 bool ButtonDClick(int but
= wxMOUSE_BTN_ANY
) const;
1620 If the argument is omitted, this returns @true if the event was a mouse
1621 button down event. Otherwise the argument specifies which button-down event
1622 was generated (see Button() for the possible values).
1624 bool ButtonDown(int = wxMOUSE_BTN_ANY
) const;
1627 If the argument is omitted, this returns @true if the event was a mouse
1628 button up event. Otherwise the argument specifies which button-up event
1629 was generated (see Button() for the possible values).
1631 bool ButtonUp(int = wxMOUSE_BTN_ANY
) const;
1634 Same as MetaDown() under Mac, same as ControlDown() elsewhere.
1636 @see wxKeyEvent::CmdDown
1638 bool CmdDown() const;
1641 Returns @true if the control key was down at the time of the event.
1643 bool ControlDown() const;
1646 Returns @true if this was a dragging event (motion while a button is depressed).
1650 bool Dragging() const;
1653 Returns @true if the mouse was entering the window.
1657 bool Entering() const;
1660 Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE
1661 if no button is involved (for mouse move, enter or leave event, for example).
1662 Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and
1663 double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT
1664 for the same events for the middle and the right buttons respectively.
1666 int GetButton() const;
1669 Returns the number of mouse clicks for this event: 1 for a simple click, 2
1670 for a double-click, 3 for a triple-click and so on.
1672 Currently this function is implemented only in wxMac and returns -1 for the
1673 other platforms (you can still distinguish simple clicks from double-clicks as
1674 they generate different kinds of events however).
1678 int GetClickCount() const;
1681 Returns the configured number of lines (or whatever) to be scrolled per
1682 wheel action. Defaults to three.
1684 int GetLinesPerAction() const;
1687 Returns the logical mouse position in pixels (i.e. translated according to the
1688 translation set for the DC, which usually indicates that the window has been
1691 wxPoint
GetLogicalPosition(const wxDC
& dc
) const;
1695 Sets *x and *y to the position at which the event occurred.
1696 Returns the physical mouse position in pixels.
1698 Note that if the mouse event has been artificially generated from a special
1699 keyboard combination (e.g. under Windows when the "menu" key is pressed), the
1700 returned position is ::wxDefaultPosition.
1702 wxPoint
GetPosition() const;
1703 void GetPosition(wxCoord
* x
, wxCoord
* y
) const;
1704 void GetPosition(long* x
, long* y
) const;
1708 Get wheel delta, normally 120.
1710 This is the threshold for action to be taken, and one such action
1711 (for example, scrolling one increment) should occur for each delta.
1713 int GetWheelDelta() const;
1716 Get wheel rotation, positive or negative indicates direction of rotation.
1718 Current devices all send an event when rotation is at least +/-WheelDelta, but
1719 finer resolution devices can be created in the future.
1721 Because of this you shouldn't assume that one event is equal to 1 line, but you
1722 should be able to either do partial line scrolling or wait until several
1723 events accumulate before scrolling.
1725 int GetWheelRotation() const;
1728 Returns X coordinate of the physical mouse event position.
1730 wxCoord
GetX() const;
1733 Returns Y coordinate of the physical mouse event position.
1735 wxCoord
GetY() const;
1738 Returns @true if the event was a mouse button event (not necessarily a button
1739 down event - that may be tested using ButtonDown()).
1741 bool IsButton() const;
1744 Returns @true if the system has been setup to do page scrolling with
1745 the mouse wheel instead of line scrolling.
1747 bool IsPageScroll() const;
1750 Returns @true if the mouse was leaving the window.
1754 bool Leaving() const;
1757 Returns @true if the event was a left double click.
1759 bool LeftDClick() const;
1762 Returns @true if the left mouse button changed to down.
1764 bool LeftDown() const;
1767 Returns @true if the left mouse button is currently down, independent
1768 of the current event type.
1770 Please notice that it is not the same as LeftDown() which returns @true if the
1771 event was generated by the left mouse button being pressed. Rather, it simply
1772 describes the state of the left mouse button at the time when the event was
1773 generated (so while it will be @true for a left click event, it can also be @true
1774 for a right click if it happened while the left mouse button was pressed).
1776 This event is usually used in the mouse event handlers which process "move
1777 mouse" messages to determine whether the user is (still) dragging the mouse.
1779 bool LeftIsDown() const;
1782 Returns @true if the left mouse button changed to up.
1784 bool LeftUp() const;
1787 Returns @true if the Meta key was down at the time of the event.
1789 bool MetaDown() const;
1792 Returns @true if the event was a middle double click.
1794 bool MiddleDClick() const;
1797 Returns @true if the middle mouse button changed to down.
1799 bool MiddleDown() const;
1802 Returns @true if the middle mouse button is currently down, independent
1803 of the current event type.
1805 bool MiddleIsDown() const;
1808 Returns @true if the middle mouse button changed to up.
1810 bool MiddleUp() const;
1813 Returns @true if this was a motion event and no mouse buttons were pressed.
1814 If any mouse button is held pressed, then this method returns @false and
1815 Dragging() returns @true.
1817 bool Moving() const;
1820 Returns @true if the event was a right double click.
1822 bool RightDClick() const;
1825 Returns @true if the right mouse button changed to down.
1827 bool RightDown() const;
1830 Returns @true if the right mouse button is currently down, independent
1831 of the current event type.
1833 bool RightIsDown() const;
1836 Returns @true if the right mouse button changed to up.
1838 bool RightUp() const;
1841 Returns @true if the shift key was down at the time of the event.
1843 bool ShiftDown() const;
1849 @class wxDropFilesEvent
1852 This class is used for drop files events, that is, when files have been dropped
1853 onto the window. This functionality is currently only available under Windows.
1855 The window must have previously been enabled for dropping by calling
1856 wxWindow::DragAcceptFiles().
1858 Important note: this is a separate implementation to the more general drag and drop
1859 implementation documented in the @ref overview_dnd. It uses the older, Windows
1860 message-based approach of dropping files.
1862 @beginEventTable{wxDropFilesEvent}
1863 @event{EVT_DROP_FILES(func)}:
1864 Process a wxEVT_DROP_FILES event.
1872 @see @ref overview_eventhandling
1874 class wxDropFilesEvent
: public wxEvent
1880 wxDropFilesEvent(wxEventType id
= 0, int noFiles
= 0,
1881 wxString
* files
= NULL
);
1884 Returns an array of filenames.
1886 wxString
* GetFiles() const;
1889 Returns the number of files dropped.
1891 int GetNumberOfFiles() const;
1894 Returns the position at which the files were dropped.
1895 Returns an array of filenames.
1897 wxPoint
GetPosition() const;
1903 @class wxCommandEvent
1906 This event class contains information about command events, which originate
1907 from a variety of simple controls.
1909 More complex controls, such as wxTreeCtrl, have separate command event classes.
1911 @beginEventTable{wxCommandEvent}
1912 @event{EVT_COMMAND(id, event, func)}:
1913 Process a command, supplying the window identifier, command event identifier,
1914 and member function.
1915 @event{EVT_COMMAND_RANGE(id1, id2, event, func)}:
1916 Process a command for a range of window identifiers, supplying the minimum and
1917 maximum window identifiers, command event identifier, and member function.
1918 @event{EVT_BUTTON(id, func)}:
1919 Process a wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
1920 @event{EVT_CHECKBOX(id, func)}:
1921 Process a wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
1922 @event{EVT_CHOICE(id, func)}:
1923 Process a wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
1924 @event{EVT_COMBOBOX(id, func)}:
1925 Process a wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
1926 @event{EVT_LISTBOX(id, func)}:
1927 Process a wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
1928 @event{EVT_LISTBOX_DCLICK(id, func)}:
1929 Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
1930 @event{EVT_MENU(id, func)}:
1931 Process a wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
1932 @event{EVT_MENU_RANGE(id1, id2, func)}:
1933 Process a wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
1934 @event{EVT_CONTEXT_MENU(func)}:
1935 Process the event generated when the user has requested a popup menu to appear by
1936 pressing a special keyboard key (under Windows) or by right clicking the mouse.
1937 @event{EVT_RADIOBOX(id, func)}:
1938 Process a wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
1939 @event{EVT_RADIOBUTTON(id, func)}:
1940 Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
1941 @event{EVT_SCROLLBAR(id, func)}:
1942 Process a wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
1943 control. This is provided for compatibility only; more specific scrollbar event macros
1944 should be used instead (see wxScrollEvent).
1945 @event{EVT_SLIDER(id, func)}:
1946 Process a wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
1947 @event{EVT_TEXT(id, func)}:
1948 Process a wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
1949 @event{EVT_TEXT_ENTER(id, func)}:
1950 Process a wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
1951 Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
1952 to generate such events.
1953 @event{EVT_TEXT_MAXLEN(id, func)}:
1954 Process a wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
1955 when the user tries to enter more characters into it than the limit previously set
1956 with SetMaxLength().
1957 @event{EVT_TOGGLEBUTTON(id, func)}:
1958 Process a wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
1959 @event{EVT_TOOL(id, func)}:
1960 Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for wxEVT_COMMAND_MENU_SELECTED).
1961 Pass the id of the tool.
1962 @event{EVT_TOOL_RANGE(id1, id2, func)}:
1963 Process a wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
1964 @event{EVT_TOOL_RCLICKED(id, func)}:
1965 Process a wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
1966 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}:
1967 Process a wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
1968 @event{EVT_TOOL_ENTER(id, func)}:
1969 Process a wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
1970 The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
1971 has moved off a tool.
1972 @event{EVT_COMMAND_LEFT_CLICK(id, func)}:
1973 Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (Windows 95 and NT only).
1974 @event{EVT_COMMAND_LEFT_DCLICK(id, func)}:
1975 Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (Windows 95 and NT only).
1976 @event{EVT_COMMAND_RIGHT_CLICK(id, func)}:
1977 Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (Windows 95 and NT only).
1978 @event{EVT_COMMAND_SET_FOCUS(id, func)}:
1979 Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (Windows 95 and NT only).
1980 @event{EVT_COMMAND_KILL_FOCUS(id, func)}:
1981 Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (Windows 95 and NT only).
1982 @event{EVT_COMMAND_ENTER(id, func)}:
1983 Process a wxEVT_COMMAND_ENTER command, which is generated by a control.
1989 class wxCommandEvent
: public wxEvent
1995 wxCommandEvent(wxEventType commandEventType
= 0, int id
= 0);
1998 Returns client data pointer for a listbox or choice selection event
1999 (not valid for a deselection).
2001 void* GetClientData() const;
2004 Returns client object pointer for a listbox or choice selection event
2005 (not valid for a deselection).
2007 wxClientData
* GetClientObject() const;
2010 Returns extra information dependant on the event objects type.
2012 If the event comes from a listbox selection, it is a boolean
2013 determining whether the event was a selection (@true) or a
2014 deselection (@false). A listbox deselection only occurs for
2015 multiple-selection boxes, and in this case the index and string values
2016 are indeterminate and the listbox must be examined by the application.
2018 long GetExtraLong() const;
2021 Returns the integer identifier corresponding to a listbox, choice or
2022 radiobox selection (only if the event was a selection, not a deselection),
2023 or a boolean value representing the value of a checkbox.
2028 Returns item index for a listbox or choice selection event (not valid for
2031 int GetSelection() const;
2034 Returns item string for a listbox or choice selection event (not valid for
2037 wxString
GetString() const;
2040 This method can be used with checkbox and menu events: for the checkboxes, the
2041 method returns @true for a selection event and @false for a deselection one.
2042 For the menu events, this method indicates if the menu item just has become
2043 checked or unchecked (and thus only makes sense for checkable menu items).
2045 Notice that this method can not be used with wxCheckListBox currently.
2047 bool IsChecked() const;
2050 For a listbox or similar event, returns @true if it is a selection, @false if it
2053 bool IsSelection() const;
2056 Sets the client data for this event.
2058 void SetClientData(void* clientData
);
2061 Sets the client object for this event. The client object is not owned by the
2062 event object and the event object will not delete the client object in its destructor.
2064 The client object must be owned and deleted by another object (e.g. a control)
2065 that has longer life time than the event object.
2067 void SetClientObject(wxClientData
* clientObject
);
2070 Sets the @b m_extraLong member.
2072 void SetExtraLong(long extraLong
);
2075 Sets the @b m_commandInt member.
2077 void SetInt(int intCommand
);
2080 Sets the @b m_commandString member.
2082 void SetString(const wxString
& string
);
2088 @class wxActivateEvent
2091 An activate event is sent when a window or application is being activated
2094 @beginEventTable{wxActivateEvent}
2095 @event{EVT_ACTIVATE(func)}:
2096 Process a wxEVT_ACTIVATE event.
2097 @event{EVT_ACTIVATE_APP(func)}:
2098 Process a wxEVT_ACTIVATE_APP event.
2099 @event{EVT_HIBERNATE(func)}:
2100 Process a hibernate event, supplying the member function. This event applies
2101 to wxApp only, and only on Windows SmartPhone and PocketPC.
2102 It is generated when the system is low on memory; the application should free
2103 up as much memory as possible, and restore full working state when it receives
2104 a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event.
2111 @see @ref overview_eventhandling, wxApp::IsActive
2113 class wxActivateEvent
: public wxEvent
2119 wxActivateEvent(wxEventType eventType
= wxEVT_NULL
, bool active
= true,
2123 Returns @true if the application or window is being activated, @false otherwise.
2125 bool GetActive() const;
2131 @class wxContextMenuEvent
2134 This class is used for context menu events, sent to give
2135 the application a chance to show a context (popup) menu.
2137 Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this
2138 means that the event originated from a keyboard context button event, and you
2139 should compute a suitable position yourself, for example by calling wxGetMousePosition().
2141 When a keyboard context menu button is pressed on Windows, a right-click event
2142 with default position is sent first, and if this event is not processed, the
2143 context menu event is sent. So if you process mouse events and you find your
2144 context menu event handler is not being called, you could call wxEvent::Skip()
2145 for mouse right-down events.
2147 @beginEventTable{wxContextMenuEvent}
2148 @event{EVT_CONTEXT_MENU(func)}:
2149 A right click (or other context menu command depending on platform) has been detected.
2156 @see wxCommandEvent, @ref overview_eventhandling
2158 class wxContextMenuEvent
: public wxCommandEvent
2164 wxContextMenuEvent(wxEventType id
= wxEVT_NULL
, int id
= 0,
2165 const wxPoint
& pos
= wxDefaultPosition
);
2168 Returns the position in screen coordinates at which the menu should be shown.
2169 Use wxWindow::ScreenToClient to convert to client coordinates.
2171 You can also omit a position from wxWindow::PopupMenu in order to use
2172 the current mouse pointer position.
2174 If the event originated from a keyboard event, the value returned from this
2175 function will be wxDefaultPosition.
2177 const wxPoint
& GetPosition() const;
2180 Sets the position at which the menu should be shown.
2182 void SetPosition(const wxPoint
& point
);
2191 An erase event is sent when a window's background needs to be repainted.
2193 On some platforms, such as GTK+, this event is simulated (simply generated just
2194 before the paint event) and may cause flicker. It is therefore recommended that
2195 you set the text background colour explicitly in order to prevent flicker.
2196 The default background colour under GTK+ is grey.
2198 To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
2201 You must call wxEraseEvent::GetDC and use the returned device context if it is
2202 non-@NULL. If it is @NULL, create your own temporary wxClientDC object.
2205 Use the device context returned by GetDC to draw on, don't create
2206 a wxPaintDC in the event handler.
2208 @beginEventTable{wxEraseEvent}
2209 @event{EVT_ERASE_BACKGROUND(func)}:
2210 Process a wxEVT_ERASE_BACKGROUND event.
2216 @see @ref overview_eventhandling
2218 class wxEraseEvent
: public wxEvent
2224 wxEraseEvent(int id
= 0, wxDC
* dc
= NULL
);
2227 Returns the device context associated with the erase event to draw on.
2229 wxDC
* GetDC() const;
2238 A focus event is sent when a window's focus changes. The window losing focus
2239 receives a "kill focus" event while the window gaining it gets a "set focus" one.
2241 Notice that the set focus event happens both when the user gives focus to the
2242 window (whether using the mouse or keyboard) and when it is done from the
2243 program itself using wxWindow::SetFocus.
2245 @beginEventTable{wxFocusEvent}
2246 @event{EVT_SET_FOCUS(func)}:
2247 Process a wxEVT_SET_FOCUS event.
2248 @event{EVT_KILL_FOCUS(func)}:
2249 Process a wxEVT_KILL_FOCUS event.
2255 @see @ref overview_eventhandling
2257 class wxFocusEvent
: public wxEvent
2263 wxFocusEvent(wxEventType eventType
= wxEVT_NULL
, int id
= 0);
2266 Returns the window associated with this event, that is the window which had the
2267 focus before for the @c wxEVT_SET_FOCUS event and the window which is
2268 going to receive focus for the @c wxEVT_KILL_FOCUS one.
2270 Warning: the window pointer may be @NULL!
2272 wxWindow
*GetWindow() const;
2278 @class wxChildFocusEvent
2281 A child focus event is sent to a (parent-)window when one of its child windows
2282 gains focus, so that the window could restore the focus back to its corresponding
2283 child if it loses it now and regains later.
2285 Notice that child window is the direct child of the window receiving event.
2286 Use wxWindow::FindFocus() to retreive the window which is actually getting focus.
2288 @beginEventTable{wxChildFocusEvent}
2289 @event{EVT_CHILD_FOCUS(func)}:
2290 Process a wxEVT_CHILD_FOCUS event.
2296 @see @ref overview_eventhandling
2298 class wxChildFocusEvent
: public wxCommandEvent
2305 The direct child which is (or which contains the window which is) receiving
2308 wxChildFocusEvent(wxWindow
* win
= NULL
);
2311 Returns the direct child which receives the focus, or a (grand-)parent of the
2312 control receiving the focus.
2314 To get the actually focused control use wxWindow::FindFocus.
2316 wxWindow
*GetWindow() const;
2322 @class wxMouseCaptureLostEvent
2325 An mouse capture lost event is sent to a window that obtained mouse capture,
2326 which was subsequently loss due to "external" event, for example when a dialog
2327 box is shown or if another application captures the mouse.
2329 If this happens, this event is sent to all windows that are on capture stack
2330 (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is
2331 not sent if the capture changes because of a call to CaptureMouse or
2334 This event is currently emitted under Windows only.
2336 @beginEventTable{wxMouseCaptureLostEvent}
2337 @event{EVT_MOUSE_CAPTURE_LOST(func)}:
2338 Process a wxEVT_MOUSE_CAPTURE_LOST event.
2346 @see wxMouseCaptureChangedEvent, @ref overview_eventhandling,
2347 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
2349 class wxMouseCaptureLostEvent
: public wxEvent
2355 wxMouseCaptureLostEvent(wxWindowID windowId
= 0);
2361 @class wxNotifyEvent
2364 This class is not used by the event handlers by itself, but is a base class
2365 for other event classes (such as wxNotebookEvent).
2367 It (or an object of a derived class) is sent when the controls state is being
2368 changed and allows the program to wxNotifyEvent::Veto() this change if it wants
2369 to prevent it from happening.
2374 @see wxNotebookEvent
2376 class wxNotifyEvent
: public wxCommandEvent
2380 Constructor (used internally by wxWidgets only).
2382 wxNotifyEvent(wxEventType eventType
= wxEVT_NULL
, int id
= 0);
2385 This is the opposite of Veto(): it explicitly allows the event to be processed.
2386 For most events it is not necessary to call this method as the events are allowed
2387 anyhow but some are forbidden by default (this will be mentioned in the corresponding
2393 Returns @true if the change is allowed (Veto() hasn't been called) or @false
2394 otherwise (if it was).
2396 bool IsAllowed() const;
2399 Prevents the change announced by this event from happening.
2401 It is in general a good idea to notify the user about the reasons for vetoing
2402 the change because otherwise the applications behaviour (which just refuses to
2403 do what the user wants) might be quite surprising.
2412 Indicates how a wxHelpEvent was generated.
2414 enum wxHelpEventOrigin
2416 wxHE_ORIGIN_UNKNOWN
= -1, /**< unrecognized event source. */
2417 wxHE_ORIGIN_KEYBOARD
, /**< event generated from F1 key press. */
2419 /** event generated by wxContextHelp or from the [?] button on
2420 the title bar (Windows). */
2421 wxHE_ORIGIN_HELPBUTTON
2428 A help event is sent when the user has requested context-sensitive help.
2429 This can either be caused by the application requesting context-sensitive help mode
2430 via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when
2431 the user pressed F1 or clicked on the query button in a dialog caption.
2433 A help event is sent to the window that the user clicked on, and is propagated
2434 up the window hierarchy until the event is processed or there are no more event
2437 The application should call wxEvent::GetId to check the identity of the
2438 clicked-on window, and then either show some suitable help or call wxEvent::Skip()
2439 if the identifier is unrecognised.
2441 Calling Skip is important because it allows wxWidgets to generate further
2442 events for ancestors of the clicked-on window. Otherwise it would be impossible to
2443 show help for container windows, since processing would stop after the first window
2446 @beginEventTable{wxHelpEvent}
2447 @event{EVT_HELP(id, func)}:
2448 Process a wxEVT_HELP event.
2449 @event{EVT_HELP_RANGE(id1, id2, func)}:
2450 Process a wxEVT_HELP event for a range of ids.
2456 @see wxContextHelp, wxDialog, @ref overview_eventhandling
2458 class wxHelpEvent
: public wxCommandEvent
2464 wxHelpEvent(wxEventType type
= wxEVT_NULL
,
2465 wxWindowID winid
= 0,
2466 const wxPoint
& pt
= wxDefaultPosition
,
2467 wxHelpEventOrigin origin
= wxHE_ORIGIN_UNKNOWN
);
2470 Returns the origin of the help event which is one of the ::wxHelpEventOrigin
2473 The application may handle events generated using the keyboard or mouse
2474 differently, e.g. by using wxGetMousePosition() for the mouse events.
2478 wxHelpEventOrigin
GetOrigin() const;
2481 Returns the left-click position of the mouse, in screen coordinates.
2482 This allows the application to position the help appropriately.
2484 const wxPoint
& GetPosition() const;
2487 Set the help event origin, only used internally by wxWidgets normally.
2491 void SetOrigin(wxHelpEventOrigin
);
2494 Sets the left-click position of the mouse, in screen coordinates.
2496 void SetPosition(const wxPoint
& pt
);
2502 @class wxScrollEvent
2505 A scroll event holds information about events sent from stand-alone
2506 scrollbars (see wxScrollBar) and sliders (see wxSlider).
2508 Note that scrolled windows send the wxScrollWinEvent which does not derive from
2509 wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of
2510 events and use the event table macros mentioned below only for the scrollbar-like
2513 @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
2515 The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
2516 using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
2517 by an EVT_SCROLL_CHANGED event).
2519 The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb
2520 position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE
2521 event does not happen).
2523 In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished
2524 independently of the way it had started. Please see the widgets sample ("Slider" page)
2525 to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action.
2528 Note that unless specifying a scroll control identifier, you will need to test for scrollbar
2529 orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events
2530 are processed using the same event handler.
2532 @beginEventTable{wxScrollEvent}
2533 You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
2534 scroll events from controls, or EVT_SCROLL... macros without window IDs for
2535 intercepting scroll events from the receiving window -- except for this, the
2536 macros behave exactly the same.
2537 @event{EVT_SCROLL(func)}:
2538 Process all scroll events.
2539 @event{EVT_SCROLL_TOP(func)}:
2540 Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
2541 @event{EVT_SCROLL_BOTTOM(func)}:
2542 Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
2543 @event{EVT_SCROLL_LINEUP(func)}:
2544 Process wxEVT_SCROLL_LINEUP line up events.
2545 @event{EVT_SCROLL_LINEDOWN(func)}:
2546 Process wxEVT_SCROLL_LINEDOWN line down events.
2547 @event{EVT_SCROLL_PAGEUP(func)}:
2548 Process wxEVT_SCROLL_PAGEUP page up events.
2549 @event{EVT_SCROLL_PAGEDOWN(func)}:
2550 Process wxEVT_SCROLL_PAGEDOWN page down events.
2551 @event{EVT_SCROLL_THUMBTRACK(func)}:
2552 Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the
2553 user drags the thumbtrack).
2554 @event{EVT_SCROLL_THUMBRELEASE(func)}:
2555 Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
2556 @event{EVT_SCROLL_CHANGED(func)}:
2557 Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
2558 @event{EVT_COMMAND_SCROLL(id, func)}:
2559 Process all scroll events.
2560 @event{EVT_COMMAND_SCROLL_TOP(id, func)}:
2561 Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
2562 @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}:
2563 Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
2564 @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}:
2565 Process wxEVT_SCROLL_LINEUP line up events.
2566 @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}:
2567 Process wxEVT_SCROLL_LINEDOWN line down events.
2568 @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}:
2569 Process wxEVT_SCROLL_PAGEUP page up events.
2570 @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}:
2571 Process wxEVT_SCROLL_PAGEDOWN page down events.
2572 @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}:
2573 Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent
2574 as the user drags the thumbtrack).
2575 @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}:
2576 Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
2577 @event{EVT_COMMAND_SCROLL_CHANGED(func)}:
2578 Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
2584 @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_eventhandling
2586 class wxScrollEvent
: public wxCommandEvent
2592 wxScrollEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0, int pos
= 0,
2593 int orientation
= 0);
2596 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
2599 int GetOrientation() const;
2602 Returns the position of the scrollbar.
2604 int GetPosition() const;
2608 See wxIdleEvent::SetMode() for more info.
2612 /** Send idle events to all windows */
2615 /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */
2616 wxIDLE_PROCESS_SPECIFIED
2624 This class is used for idle events, which are generated when the system becomes
2625 idle. Note that, unless you do something specifically, the idle events are not
2626 sent if the system remains idle once it has become it, e.g. only a single idle
2627 event will be generated until something else resulting in more normal events
2628 happens and only then is the next idle event sent again.
2630 If you need to ensure a continuous stream of idle events, you can either use
2631 wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically
2632 (for example from a timer event handler), but note that both of these approaches
2633 (and especially the first one) increase the system load and so should be avoided
2636 By default, idle events are sent to all windows (and also wxApp, as usual).
2637 If this is causing a significant overhead in your application, you can call
2638 wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the
2639 wxWS_EX_PROCESS_IDLE extra window style for every window which should receive
2642 @beginEventTable{wxIdleEvent}
2643 @event{EVT_IDLE(func)}:
2644 Process a wxEVT_IDLE event.
2650 @see @ref overview_eventhandling, wxUpdateUIEvent, wxWindow::OnInternalIdle
2652 class wxIdleEvent
: public wxEvent
2661 Returns @true if it is appropriate to send idle events to this window.
2663 This function looks at the mode used (see wxIdleEvent::SetMode),
2664 and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle
2665 events should be sent to this window now.
2667 By default this will always return @true because the update mode is initially
2668 wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to
2669 windows with the wxWS_EX_PROCESS_IDLE extra window style set.
2673 static bool CanSend(wxWindow
* window
);
2676 Static function returning a value specifying how wxWidgets will send idle
2677 events: to all windows, or only to those which specify that they
2678 will process the events.
2682 static wxIdleMode
GetMode();
2685 Returns @true if the OnIdle function processing this event requested more
2690 bool MoreRequested() const;
2693 Tells wxWidgets that more processing is required.
2695 This function can be called by an OnIdle handler for a window or window event
2696 handler to indicate that wxApp::OnIdle should forward the OnIdle event once
2697 more to the application windows.
2699 If no window calls this function during OnIdle, then the application will
2700 remain in a passive event loop (not calling OnIdle) until a new event is
2701 posted to the application by the windowing system.
2703 @see MoreRequested()
2705 void RequestMore(bool needMore
= true);
2708 Static function for specifying how wxWidgets will send idle events: to
2709 all windows, or only to those which specify that they will process the events.
2712 Can be one of the ::wxIdleMode values.
2713 The default is wxIDLE_PROCESS_ALL.
2715 static void SetMode(wxIdleMode mode
);
2721 @class wxInitDialogEvent
2724 A wxInitDialogEvent is sent as a dialog or panel is being initialised.
2725 Handlers for this event can transfer data to the window.
2727 The default handler calls wxWindow::TransferDataToWindow.
2729 @beginEventTable{wxInitDialogEvent}
2730 @event{EVT_INIT_DIALOG(func)}:
2731 Process a wxEVT_INIT_DIALOG event.
2737 @see @ref overview_eventhandling
2739 class wxInitDialogEvent
: public wxEvent
2745 wxInitDialogEvent(int id
= 0);
2751 @class wxWindowDestroyEvent
2754 This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a
2755 window is destroyed.
2757 When a class derived from wxWindow is destroyed its destructor will have
2758 already run by the time this event is sent. Therefore this event will not
2759 usually be received at all.
2761 To receive this event wxEvtHandler::Connect() must be used (using an event
2762 table macro will not work). Since it is received after the destructor has run,
2763 an object should not handle its own wxWindowDestroyEvent, but it can be used
2764 to get notification of the destruction of another window.
2769 @see @ref overview_eventhandling, wxWindowCreateEvent
2771 class wxWindowDestroyEvent
: public wxCommandEvent
2777 wxWindowDestroyEvent(wxWindow
* win
= NULL
);
2782 The possible flag values for a wxNavigationKeyEvent.
2784 enum wxNavigationKeyEventFlags
2786 wxNKEF_IS_BACKWARD
= 0x0000,
2787 wxNKEF_IS_FORWARD
= 0x0001,
2788 wxNKEF_WINCHANGE
= 0x0002,
2789 wxNKEF_FROMTAB
= 0x0004
2794 @class wxNavigationKeyEvent
2797 This event class contains information about navigation events,
2798 generated by navigation keys such as tab and page down.
2800 This event is mainly used by wxWidgets implementations.
2801 A wxNavigationKeyEvent handler is automatically provided by wxWidgets
2802 when you make a class into a control container with the macro
2803 WX_DECLARE_CONTROL_CONTAINER.
2805 @beginEventTable{wxNavigationKeyEvent}
2806 @event{EVT_NAVIGATION_KEY(func)}:
2807 Process a navigation key event.
2813 @see wxWindow::Navigate, wxWindow::NavigateIn
2815 class wxNavigationKeyEvent
: public wxEvent
2818 wxNavigationKeyEvent();
2819 wxNavigationKeyEvent(const wxNavigationKeyEvent
& event
);
2822 Returns the child that has the focus, or @NULL.
2824 wxWindow
* GetCurrentFocus() const;
2827 Returns @true if the navigation was in the forward direction.
2829 bool GetDirection() const;
2832 Returns @true if the navigation event was from a tab key.
2833 This is required for proper navigation over radio buttons.
2835 bool IsFromTab() const;
2838 Returns @true if the navigation event represents a window change
2839 (for example, from Ctrl-Page Down in a notebook).
2841 bool IsWindowChange() const;
2844 Sets the current focus window member.
2846 void SetCurrentFocus(wxWindow
* currentFocus
);
2849 Sets the direction to forward if @a direction is @true, or backward
2852 void SetDirection(bool direction
);
2855 Sets the flags for this event.
2856 The @a flags can be a combination of the ::wxNavigationKeyEventFlags values.
2858 void SetFlags(long flags
);
2861 Marks the navigation event as from a tab key.
2863 void SetFromTab(bool fromTab
);
2866 Marks the event as a window change event.
2868 void SetWindowChange(bool windowChange
);
2874 @class wxMouseCaptureChangedEvent
2877 An mouse capture changed event is sent to a window that loses its
2878 mouse capture. This is called even if wxWindow::ReleaseCapture
2879 was called by the application code. Handling this event allows
2880 an application to cater for unexpected capture releases which
2881 might otherwise confuse mouse handling code.
2885 @beginEventTable{wxMouseCaptureChangedEvent}
2886 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}:
2887 Process a wxEVT_MOUSE_CAPTURE_CHANGED event.
2893 @see wxMouseCaptureLostEvent, @ref overview_eventhandling,
2894 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
2896 class wxMouseCaptureChangedEvent
: public wxEvent
2902 wxMouseCaptureChangedEvent(wxWindowID windowId
= 0,
2903 wxWindow
* gainedCapture
= NULL
);
2906 Returns the window that gained the capture, or @NULL if it was a
2907 non-wxWidgets window.
2909 wxWindow
* GetCapturedWindow() const;
2918 This event class contains information about window and session close events.
2920 The handler function for EVT_CLOSE is called when the user has tried to close a
2921 a frame or dialog box using the window manager (X) or system menu (Windows).
2922 It can also be invoked by the application itself programmatically, for example by
2923 calling the wxWindow::Close function.
2925 You should check whether the application is forcing the deletion of the window
2926 using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window
2927 using wxWindow::Destroy.
2929 If the return value is @true, it is up to you whether you respond by destroying
2932 If you don't destroy the window, you should call wxCloseEvent::Veto to
2933 let the calling code know that you did not destroy the window.
2934 This allows the wxWindow::Close function to return @true or @false depending
2935 on whether the close instruction was honoured or not.
2937 @beginEventTable{wxCloseEvent}
2938 @event{EVT_CLOSE(func)}:
2939 Process a close event, supplying the member function.
2940 This event applies to wxFrame and wxDialog classes.
2941 @event{EVT_QUERY_END_SESSION(func)}:
2942 Process a query end session event, supplying the member function.
2943 This event applies to wxApp only.
2944 @event{EVT_END_SESSION(func)}:
2945 Process an end session event, supplying the member function.
2946 This event applies to wxApp only.
2952 @see wxWindow::Close, @ref overview_windowdeletion
2954 class wxCloseEvent
: public wxEvent
2960 wxCloseEvent(wxEventType commandEventType
= wxEVT_NULL
, int id
= 0);
2963 Returns @true if you can veto a system shutdown or a window close event.
2964 Vetoing a window close event is not possible if the calling code wishes to
2965 force the application to exit, and so this function must be called to check this.
2967 bool CanVeto() const;
2970 Returns @true if the user is just logging off or @false if the system is
2971 shutting down. This method can only be called for end session and query end
2972 session events, it doesn't make sense for close window event.
2974 bool GetLoggingOff() const;
2977 Sets the 'can veto' flag.
2979 void SetCanVeto(bool canVeto
);
2982 Sets the 'force' flag.
2984 void SetForce(bool force
) const;
2987 Sets the 'logging off' flag.
2989 void SetLoggingOff(bool loggingOff
);
2992 Call this from your event handler to veto a system shutdown or to signal
2993 to the calling application that a window close did not happen.
2995 You can only veto a shutdown if CanVeto() returns @true.
2997 void Veto(bool veto
= true);
3006 This class is used for a variety of menu-related events. Note that
3007 these do not include menu command events, which are
3008 handled using wxCommandEvent objects.
3010 The default handler for wxEVT_MENU_HIGHLIGHT displays help
3011 text in the first field of the status bar.
3013 @beginEventTable{wxMenuEvent}
3014 @event{EVT_MENU_OPEN(func)}:
3015 A menu is about to be opened. On Windows, this is only sent once for each
3016 navigation of the menubar (up until all menus have closed).
3017 @event{EVT_MENU_CLOSE(func)}:
3018 A menu has been just closed.
3019 @event{EVT_MENU_HIGHLIGHT(id, func)}:
3020 The menu item with the specified id has been highlighted: used to show
3021 help prompts in the status bar by wxFrame
3022 @event{EVT_MENU_HIGHLIGHT_ALL(func)}:
3023 A menu item has been highlighted, i.e. the currently selected menu item has changed.
3029 @see wxCommandEvent, @ref overview_eventhandling
3031 class wxMenuEvent
: public wxEvent
3037 wxMenuEvent(wxEventType id
= wxEVT_NULL
, int id
= 0, wxMenu
* menu
= NULL
);
3040 Returns the menu which is being opened or closed. This method should only be
3041 used with the @c OPEN and @c CLOSE events and even for them the
3042 returned pointer may be @NULL in some ports.
3044 wxMenu
* GetMenu() const;
3047 Returns the menu identifier associated with the event.
3048 This method should be only used with the @c HIGHLIGHT events.
3050 int GetMenuId() const;
3053 Returns @true if the menu which is being opened or closed is a popup menu,
3054 @false if it is a normal one.
3056 This method should only be used with the @c OPEN and @c CLOSE events.
3058 bool IsPopup() const;
3063 @class wxIconizeEvent
3066 An event being sent when the frame is iconized (minimized) or restored.
3068 Currently only wxMSW and wxGTK generate such events.
3070 @onlyfor{wxmsw,wxgtk}
3072 @beginEventTable{wxIconizeEvent}
3073 @event{EVT_ICONIZE(func)}:
3074 Process a wxEVT_ICONIZE event.
3080 @see @ref overview_eventhandling, wxTopLevelWindow::Iconize,
3081 wxTopLevelWindow::IsIconized
3083 class wxIconizeEvent
: public wxEvent
3089 wxIconizeEvent(int id
= 0, bool iconized
= true);
3092 Returns @true if the frame has been iconized, @false if it has been
3095 bool Iconized() const;
3104 A move event holds information about move change events.
3106 @beginEventTable{wxMoveEvent}
3107 @event{EVT_MOVE(func)}:
3108 Process a wxEVT_MOVE event, which is generated when a window is moved.
3109 @event{EVT_MOVE_START(func)}:
3110 Process a wxEVT_MOVE_START event, which is generated when the user starts
3111 to move or size a window. wxMSW only.
3112 @event{EVT_MOVE_END(func)}:
3113 Process a wxEVT_MOVE_END event, which is generated when the user stops
3114 moving or sizing a window. wxMSW only.
3120 @see wxPoint, @ref overview_eventhandling
3122 class wxMoveEvent
: public wxEvent
3128 wxMoveEvent(const wxPoint
& pt
, int id
= 0);
3131 Returns the position of the window generating the move change event.
3133 wxPoint
GetPosition() const;
3141 A size event holds information about size change events.
3143 The EVT_SIZE handler function will be called when the window has been resized.
3145 You may wish to use this for frames to resize their child windows as appropriate.
3147 Note that the size passed is of the whole window: call wxWindow::GetClientSize
3148 for the area which may be used by the application.
3150 When a window is resized, usually only a small part of the window is damaged
3151 and you may only need to repaint that area. However, if your drawing depends on the
3152 size of the window, you may need to clear the DC explicitly and repaint the whole window.
3153 In which case, you may need to call wxWindow::Refresh to invalidate the entire window.
3155 @beginEventTable{wxSizeEvent}
3156 @event{EVT_SIZE(func)}:
3157 Process a wxEVT_SIZE event.
3163 @see wxSize, @ref overview_eventhandling
3165 class wxSizeEvent
: public wxEvent
3171 wxSizeEvent(const wxSize
& sz
, int id
= 0);
3174 Returns the entire size of the window generating the size change event.
3176 wxSize
GetSize() const;
3182 @class wxSetCursorEvent
3185 A SetCursorEvent is generated when the mouse cursor is about to be set as a
3186 result of mouse motion.
3188 This event gives the application the chance to perform specific mouse cursor
3189 processing based on the current position of the mouse within the window.
3190 Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed.
3192 @beginEventTable{wxSetCursorEvent}
3193 @event{EVT_SET_CURSOR(func)}:
3194 Process a wxEVT_SET_CURSOR event.
3200 @see ::wxSetCursor, wxWindow::wxSetCursor
3202 class wxSetCursorEvent
: public wxEvent
3206 Constructor, used by the library itself internally to initialize the event
3209 wxSetCursorEvent(wxCoord x
= 0, wxCoord y
= 0);
3212 Returns a reference to the cursor specified by this event.
3214 const wxCursor
& GetCursor() const;
3217 Returns the X coordinate of the mouse in client coordinates.
3219 wxCoord
GetX() const;
3222 Returns the Y coordinate of the mouse in client coordinates.
3224 wxCoord
GetY() const;
3227 Returns @true if the cursor specified by this event is a valid cursor.
3229 @remarks You cannot specify wxNullCursor with this event, as it is not
3230 considered a valid cursor.
3232 bool HasCursor() const;
3235 Sets the cursor associated with this event.
3237 void SetCursor(const wxCursor
& cursor
);
3242 // ============================================================================
3243 // Global functions/macros
3244 // ============================================================================
3246 /** @ingroup group_funcmacro_misc */
3250 In a GUI application, this function posts @a event to the specified @e dest
3251 object using wxEvtHandler::AddPendingEvent().
3253 Otherwise, it dispatches @a event immediately using
3254 wxEvtHandler::ProcessEvent(). See the respective documentation for details
3259 void wxPostEvent(wxEvtHandler
* dest
, wxEvent
& event
);