1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxEvtHandler, wxEventBlocker and many
4 // wxEvent-derived classes
5 // Author: wxWidgets team
7 // Licence: wxWindows license
8 /////////////////////////////////////////////////////////////////////////////
11 The predefined constants for the number of times we propagate event
12 upwards window child-parent chain.
14 enum wxEventPropagation
16 /// don't propagate it at all
17 wxEVENT_PROPAGATE_NONE
= 0,
19 /// propagate it until it is processed
20 wxEVENT_PROPAGATE_MAX
= INT_MAX
24 The different categories for a wxEvent; see wxEvent::GetEventCategory.
26 @note They are used as OR-combinable flags by wxEventLoopBase::YieldFor.
31 This is the category for those events which are generated to update
32 the appearance of the GUI but which (usually) do not comport data
33 processing, i.e. which do not provide input or output data
34 (e.g. size events, scroll events, etc).
35 They are events NOT directly generated by the user's input devices.
37 wxEVT_CATEGORY_UI
= 1,
40 This category groups those events which are generated directly from the
41 user through input devices like mouse and keyboard and usually result in
42 data to be processed from the application
43 (e.g. mouse clicks, key presses, etc).
45 wxEVT_CATEGORY_USER_INPUT
= 2,
47 /// This category is for wxSocketEvent
48 wxEVT_CATEGORY_SOCKET
= 4,
50 /// This category is for wxTimerEvent
51 wxEVT_CATEGORY_TIMER
= 8,
54 This category is for any event used to send notifications from the
55 secondary threads to the main one or in general for notifications among
56 different threads (which may or may not be user-generated).
58 wxEVT_CATEGORY_THREAD
= 16,
61 This mask is used in wxEventLoopBase::YieldFor to specify that all event
62 categories should be processed.
65 wxEVT_CATEGORY_UI
|wxEVT_CATEGORY_USER_INPUT
|wxEVT_CATEGORY_SOCKET
| \
66 wxEVT_CATEGORY_TIMER
|wxEVT_CATEGORY_THREAD
72 An event is a structure holding information about an event passed to a
73 callback or member function.
75 wxEvent used to be a multipurpose event object, and is an abstract base class
76 for other event classes (see below).
78 For more information about events, see the @ref overview_events overview.
81 In wxPerl custom event classes should be derived from
82 @c Wx::PlEvent and @c Wx::PlCommandEvent.
88 @see wxCommandEvent, wxMouseEvent
90 class wxEvent
: public wxObject
96 Notice that events are usually created by wxWidgets itself and creating
97 e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl
98 will not usually affect it at all as native controls have no specific
99 knowledge about wxWidgets events. However you may construct objects of
100 specific types and pass them to wxEvtHandler::ProcessEvent() if you
101 want to create your own custom control and want to process its events
102 in the same manner as the standard ones.
104 Also please notice that the order of parameters in this constructor is
105 different from almost all the derived classes which specify the event
106 type as the first argument.
109 The identifier of the object (window, timer, ...) which generated
112 The unique type of event, e.g. wxEVT_PAINT, wxEVT_SIZE or
113 wxEVT_COMMAND_BUTTON_CLICKED.
115 wxEvent(int id
= 0, wxEventType eventType
= wxEVT_NULL
);
118 Returns a copy of the event.
120 Any event that is posted to the wxWidgets event system for later action
121 (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent())
122 must implement this method.
124 All wxWidgets events fully implement this method, but any derived events
125 implemented by the user should also implement this method just in case they
126 (or some event derived from them) are ever posted.
128 All wxWidgets events implement a copy constructor, so the easiest way of
129 implementing the Clone function is to implement a copy constructor for
130 a new event (call it MyEvent) and then define the Clone function like this:
133 wxEvent *Clone() const { return new MyEvent(*this); }
136 virtual wxEvent
* Clone() const = 0;
139 Returns the object (usually a window) associated with the event, if any.
141 wxObject
* GetEventObject() const;
144 Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED.
146 wxEventType
GetEventType() const;
149 Returns a generic category for this event.
150 wxEvent implementation returns @c wxEVT_CATEGORY_UI by default.
152 This function is used to selectively process events in wxEventLoopBase::YieldFor.
154 virtual wxEventCategory
GetEventCategory() const;
157 Returns the identifier associated with this event, such as a button command id.
162 Returns @true if the event handler should be skipped, @false otherwise.
164 bool GetSkipped() const;
167 Gets the timestamp for the event. The timestamp is the time in milliseconds
168 since some fixed moment (not necessarily the standard Unix Epoch, so only
169 differences between the timestamps and not their absolute values usually make sense).
172 wxWidgets returns a non-NULL timestamp only for mouse and key events
173 (see wxMouseEvent and wxKeyEvent).
175 long GetTimestamp() const;
178 Returns @true if the event is or is derived from wxCommandEvent else it returns @false.
180 @note exists only for optimization purposes.
182 bool IsCommandEvent() const;
185 Sets the propagation level to the given value (for example returned from an
186 earlier call to wxEvent::StopPropagation).
188 void ResumePropagation(int propagationLevel
);
191 Sets the originating object.
193 void SetEventObject(wxObject
* object
);
198 void SetEventType(wxEventType type
);
201 Sets the identifier associated with this event, such as a button command id.
206 Sets the timestamp for the event.
208 void SetTimestamp(long timeStamp
= 0);
211 Test if this event should be propagated or not, i.e. if the propagation level
212 is currently greater than 0.
214 bool ShouldPropagate() const;
217 This method can be used inside an event handler to control whether further
218 event handlers bound to this event will be called after the current one returns.
220 Without Skip() (or equivalently if Skip(@false) is used), the event will not
221 be processed any more. If Skip(@true) is called, the event processing system
222 continues searching for a further handler function for this event, even though
223 it has been processed already in the current handler.
225 In general, it is recommended to skip all non-command events to allow the
226 default handling to take place. The command events are, however, normally not
227 skipped as usually a single command such as a button click or menu item
228 selection must only be processed by one handler.
230 void Skip(bool skip
= true);
233 Stop the event from propagating to its parent window.
235 Returns the old propagation level value which may be later passed to
236 ResumePropagation() to allow propagating the event again.
238 int StopPropagation();
242 Indicates how many levels the event can propagate.
244 This member is protected and should typically only be set in the constructors
245 of the derived classes. It may be temporarily changed by StopPropagation()
246 and ResumePropagation() and tested with ShouldPropagate().
248 The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default)
249 meaning that the event shouldn't be propagated at all or to
250 @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be
251 propagated as much as necessary.
253 Any positive number means that the event should be propagated but no more than
254 the given number of times. E.g. the propagation level may be set to 1 to
255 propagate the event to its parent only, but not to its grandparent.
257 int m_propagationLevel
;
261 @class wxEventBlocker
263 This class is a special event handler which allows to discard
264 any event (or a set of event types) directed to a specific window.
269 void MyWindow::DoSomething()
272 // block all events directed to this window while
273 // we do the 1000 FunctionWhichSendsEvents() calls
274 wxEventBlocker blocker(this);
276 for ( int i = 0; i 1000; i++ )
277 FunctionWhichSendsEvents(i);
279 } // ~wxEventBlocker called, old event handler is restored
281 // the event generated by this call will be processed:
282 FunctionWhichSendsEvents(0)
289 @see @ref overview_events_processing, wxEvtHandler
291 class wxEventBlocker
: public wxEvtHandler
295 Constructs the blocker for the given window and for the given event type.
297 If @a type is @c wxEVT_ANY, then all events for that window are blocked.
298 You can call Block() after creation to add other event types to the list
301 Note that the @a win window @b must remain alive until the
302 wxEventBlocker object destruction.
304 wxEventBlocker(wxWindow
* win
, wxEventType type
= -1);
307 Destructor. The blocker will remove itself from the chain of event handlers for
308 the window provided in the constructor, thus restoring normal processing of events.
310 virtual ~wxEventBlocker();
313 Adds to the list of event types which should be blocked the given @a eventType.
315 void Block(wxEventType eventType
);
323 A class that can handle events from the windowing system.
324 wxWindow is (and therefore all window classes are) derived from this class.
326 When events are received, wxEvtHandler invokes the method listed in the
327 event table using itself as the object. When using multiple inheritance
328 <b>it is imperative that the wxEvtHandler(-derived) class is the first
329 class inherited</b> such that the @c this pointer for the overall object
330 will be identical to the @c this pointer of the wxEvtHandler portion.
335 @see @ref overview_events_processing
337 class wxEvtHandler
: public wxObject
348 If the handler is part of a chain, the destructor will unlink itself
351 virtual ~wxEvtHandler();
355 @name Event queuing and processing
360 Queue event for a later processing.
362 This method is similar to ProcessEvent() but while the latter is
363 synchronous, i.e. the event is processed immediately, before the
364 function returns, this one is asynchronous and returns immediately
365 while the event will be processed at some later time (usually during
366 the next event loop iteration).
368 Another important difference is that this method takes ownership of the
369 @a event parameter, i.e. it will delete it itself. This implies that
370 the event should be allocated on the heap and that the pointer can't be
371 used any more after the function returns (as it can be deleted at any
374 QueueEvent() can be used for inter-thread communication from the worker
375 threads to the main thread, it is safe in the sense that it uses
376 locking internally and avoids the problem mentioned in AddPendingEvent()
377 documentation by ensuring that the @a event object is not used by the
378 calling thread any more. Care should still be taken to avoid that some
379 fields of this object are used by it, notably any wxString members of
380 the event object must not be shallow copies of another wxString object
381 as this would result in them still using the same string buffer behind
382 the scenes. For example
384 void FunctionInAWorkerThread(const wxString& str)
386 wxCommandEvent* evt = new wxCommandEvent;
388 // NOT evt->SetString(str) as this would be a shallow copy
389 evt->SetString(str.c_str()); // make a deep copy
391 wxTheApp->QueueEvent( evt );
395 Finally notice that this method automatically wakes up the event loop
396 if it is currently idle by calling ::wxWakeUpIdle() so there is no need
397 to do it manually when using it.
402 A heap-allocated event to be queued, QueueEvent() takes ownership
403 of it. This parameter shouldn't be @c NULL.
405 virtual void QueueEvent(wxEvent
*event
);
408 Post an event to be processed later.
410 This function is similar to QueueEvent() but can't be used to post
411 events from worker threads for the event objects with wxString fields
412 (i.e. in practice most of them) because of an unsafe use of the same
413 wxString object which happens because the wxString field in the
414 original @a event object and its copy made internally by this function
415 share the same string buffer internally. Use QueueEvent() to avoid
418 A copy of @a event is made by the function, so the original can be deleted
419 as soon as function returns (it is common that the original is created
420 on the stack). This requires that the wxEvent::Clone() method be
421 implemented by event so that it can be duplicated and stored until it
425 Event to add to the pending events queue.
427 virtual void AddPendingEvent(const wxEvent
& event
);
430 Processes an event, searching event tables and calling zero or more suitable
431 event handler function(s).
433 Normally, your application would not call this function: it is called in the
434 wxWidgets implementation to dispatch incoming user interface events to the
435 framework (and application).
437 However, you might need to call it if implementing new functionality
438 (such as a new control) where you define new event types, as opposed to
439 allowing the user to override virtual functions.
441 An instance where you might actually override the ProcessEvent() function is where
442 you want to direct event processing to event handlers not normally noticed by
443 wxWidgets. For example, in the document/view architecture, documents and views
444 are potential event handlers. When an event reaches a frame, ProcessEvent() will
445 need to be called on the associated document and view in case event handler functions
446 are associated with these objects. The property classes library (wxProperty) also
447 overrides ProcessEvent() for similar reasons.
449 The normal order of event table searching is as follows:
450 -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
451 the function skips to step (6).
452 -# If the object is a wxWindow, ProcessEvent() is recursively called on the
453 window's wxValidator. If this returns @true, the function exits.
454 -# SearchEventTable() is called for this event handler. If this fails, the base
455 class table is tried, and so on until no more tables exist or an appropriate
456 function was found, in which case the function exits.
457 -# The search is applied down the entire chain of event handlers (usually the
458 chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler():
459 @image html overview_events_chain.png
460 (referring to the image, if @c A->ProcessEvent is called and it doesn't handle
461 the event, @c B->ProcessEvent will be called and so on...).
462 Note that in the case of wxWindow you can build a stack of event handlers
463 (see wxWindow::PushEventHandler() for more info).
464 If any of the handlers of the chain return @true, the function exits.
465 -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
466 is recursively applied to the parent window's event handler.
467 If this returns @true, the function exits.
468 -# Finally, ProcessEvent() is called on the wxApp object.
473 @return @true if a suitable event handler function was found and
474 executed, and the function did not call wxEvent::Skip.
476 @see SearchEventTable()
478 virtual bool ProcessEvent(wxEvent
& event
);
481 Processes an event by calling ProcessEvent() and handles any exceptions
482 that occur in the process.
483 If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
488 @return @true if the event was processed, @false if no handler was found
489 or an exception was thrown.
491 @see wxWindow::HandleWindowEvent
493 bool SafelyProcessEvent(wxEvent
& event
);
496 Searches the event table, executing an event handler function if an appropriate
500 Event table to be searched.
502 Event to be matched against an event table entry.
504 @return @true if a suitable event handler function was found and
505 executed, and the function did not call wxEvent::Skip.
507 @remarks This function looks through the object's event table and tries
508 to find an entry that will match the event.
509 An entry will match if:
510 @li The event type matches, and
511 @li the identifier or identifier range matches, or the event table
512 entry's identifier is zero.
514 If a suitable function is called but calls wxEvent::Skip, this
515 function will fail, and searching will continue.
519 virtual bool SearchEventTable(wxEventTable
& table
,
526 @name Connecting and disconnecting
531 Connects the given function dynamically with the event handler, id and
534 This is an alternative to the use of static event tables. It is more
535 flexible as it allows to connect events generated by some object to an
536 event handler defined in a different object of a different class (which
537 is impossible to do directly with the event tables -- the events can be
538 only handled in another object if they are propagated upwards to it).
539 Do make sure to specify the correct @a eventSink when connecting to an
540 event of a different object.
542 See @ref overview_events_connect for more detailed explanation
543 of this function and the @ref page_samples_event sample for usage
546 This specific overload allows you to connect an event handler to a @e range
548 Do not confuse @e source IDs with event @e types: source IDs identify the
549 event generator objects (typically wxMenuItem or wxWindow objects) while the
550 event @e type identify which type of events should be handled by the
551 given @e function (an event generator object may generate many different
555 The first ID of the identifier range to be associated with the event
558 The last ID of the identifier range to be associated with the event
561 The event type to be associated with this event handler.
563 The event handler function. Note that this function should
564 be explicitly converted to the correct type which can be done using a macro
565 called @c wxFooEventHandler for the handler for any @c wxFooEvent.
567 Data to be associated with the event table entry.
569 Object whose member function should be called. It must be specified
570 when connecting an event generated by one object to a member
571 function of a different object. If it is omitted, @c this is used.
573 void Connect(int id
, int lastId
, wxEventType eventType
,
574 wxObjectEventFunction function
,
575 wxObject
* userData
= NULL
,
576 wxEvtHandler
* eventSink
= NULL
);
579 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
580 overload for more info.
582 This overload can be used to attach an event handler to a single source ID:
586 frame->Connect( wxID_EXIT,
587 wxEVT_COMMAND_MENU_SELECTED,
588 wxCommandEventHandler(MyFrame::OnQuit) );
591 void Connect(int id
, wxEventType eventType
,
592 wxObjectEventFunction function
,
593 wxObject
* userData
= NULL
,
594 wxEvtHandler
* eventSink
= NULL
);
597 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
598 overload for more info.
600 This overload will connect the given event handler so that regardless of the
601 ID of the event source, the handler will be called.
603 void Connect(wxEventType eventType
,
604 wxObjectEventFunction function
,
605 wxObject
* userData
= NULL
,
606 wxEvtHandler
* eventSink
= NULL
);
609 Disconnects the given function dynamically from the event handler, using the
610 specified parameters as search criteria and returning @true if a matching
611 function has been found and removed.
613 This method can only disconnect functions which have been added using the
614 Connect() method. There is no way to disconnect functions connected using
615 the (static) event tables.
618 The event type associated with this event handler.
620 The event handler function.
622 Data associated with the event table entry.
624 Object whose member function should be called.
626 bool Disconnect(wxEventType eventType
,
627 wxObjectEventFunction function
,
628 wxObject
* userData
= NULL
,
629 wxEvtHandler
* eventSink
= NULL
);
632 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
633 overload for more info.
635 This overload takes the additional @a id parameter.
637 bool Disconnect(int id
= wxID_ANY
,
638 wxEventType eventType
= wxEVT_NULL
,
639 wxObjectEventFunction function
= NULL
,
640 wxObject
* userData
= NULL
,
641 wxEvtHandler
* eventSink
= NULL
);
644 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
645 overload for more info.
647 This overload takes an additional range of source IDs.
649 bool Disconnect(int id
, int lastId
,
650 wxEventType eventType
,
651 wxObjectEventFunction function
= NULL
,
652 wxObject
* userData
= NULL
,
653 wxEvtHandler
* eventSink
= NULL
);
658 @name User-supplied data
663 Returns user-supplied client data.
665 @remarks Normally, any extra data the programmer wishes to associate with
666 the object should be made available by deriving a new class with
671 void* GetClientData() const;
674 Returns a pointer to the user-supplied client data object.
676 @see SetClientObject(), wxClientData
678 wxClientData
* GetClientObject() const;
681 Sets user-supplied client data.
684 Data to be associated with the event handler.
686 @remarks Normally, any extra data the programmer wishes to associate
687 with the object should be made available by deriving a new
688 class with new data members. You must not call this method
689 and SetClientObject on the same class - only one of them.
693 void SetClientData(void* data
);
696 Set the client data object. Any previous object will be deleted.
698 @see GetClientObject(), wxClientData
700 void SetClientObject(wxClientData
* data
);
706 @name Event handler chaining
708 wxEvtHandler can be arranged in a double-linked list of handlers
709 which is automatically iterated by ProcessEvent() if needed.
714 Returns @true if the event handler is enabled, @false otherwise.
716 @see SetEvtHandlerEnabled()
718 bool GetEvtHandlerEnabled() const;
721 Returns the pointer to the next handler in the chain.
723 @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
724 wxWindow::PushEventHandler, wxWindow::PopEventHandler
726 wxEvtHandler
* GetNextHandler() const;
729 Returns the pointer to the previous handler in the chain.
731 @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
732 wxWindow::PushEventHandler, wxWindow::PopEventHandler
734 wxEvtHandler
* GetPreviousHandler() const;
737 Enables or disables the event handler.
740 @true if the event handler is to be enabled, @false if it is to be disabled.
742 @remarks You can use this function to avoid having to remove the event
743 handler from the chain, for example when implementing a
744 dialog editor and changing from edit to test mode.
746 @see GetEvtHandlerEnabled()
748 void SetEvtHandlerEnabled(bool enabled
);
751 Sets the pointer to the next handler.
754 See ProcessEvent() for more info about how the chains of event handlers
756 Also remember that wxEvtHandler uses double-linked lists and thus if you
757 use this function, you should also call SetPreviousHandler() on the
758 argument passed to this function:
760 handlerA->SetNextHandler(handlerB);
761 handlerB->SetPreviousHandler(handlerA);
765 The event handler to be set as the next handler.
768 @see @ref overview_events_processing
770 virtual void SetNextHandler(wxEvtHandler
* handler
);
773 Sets the pointer to the previous handler.
774 All remarks about SetNextHandler() apply to this function as well.
777 The event handler to be set as the previous handler.
780 @see @ref overview_events_processing
782 virtual void SetPreviousHandler(wxEvtHandler
* handler
);
785 Unlinks this event handler from the chain it's part of (if any);
786 then links the "previous" event handler to the "next" one
787 (so that the chain won't be interrupted).
789 E.g. if before calling Unlink() you have the following chain:
790 @image html evthandler_unlink_before.png
791 then after calling @c B->Unlink() you'll have:
792 @image html evthandler_unlink_after.png
799 Returns @true if the next and the previous handler pointers of this
800 event handler instance are @NULL.
804 @see SetPreviousHandler(), SetNextHandler()
806 bool IsUnlinked() const;
815 This event class contains information about keypress (character) events.
817 Notice that there are three different kinds of keyboard events in wxWidgets:
818 key down and up events and char events. The difference between the first two
819 is clear - the first corresponds to a key press and the second to a key
820 release - otherwise they are identical. Just note that if the key is
821 maintained in a pressed state you will typically get a lot of (automatically
822 generated) down events but only one up so it is wrong to assume that there is
823 one up event corresponding to each down one.
825 Both key events provide untranslated key codes while the char event carries
826 the translated one. The untranslated code for alphanumeric keys is always
827 an upper case value. For the other keys it is one of @c WXK_XXX values
828 from the ::wxKeyCode enumeration.
829 The translated key is, in general, the character the user expects to appear
830 as the result of the key combination when typing the text into a text entry
833 A few examples to clarify this (all assume that CAPS LOCK is unpressed
834 and the standard US keyboard): when the @c 'A' key is pressed, the key down
835 event key code is equal to @c ASCII A == 65. But the char event key code
836 is @c ASCII a == 97. On the other hand, if you press both SHIFT and
837 @c 'A' keys simultaneously , the key code in key down event will still be
838 just @c 'A' while the char event key code parameter will now be @c 'A'
841 Although in this simple case it is clear that the correct key code could be
842 found in the key down event handler by checking the value returned by
843 wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as
844 for non-alphanumeric keys the translation is keyboard-layout dependent and
845 can only be done properly by the system itself.
847 Another kind of translation is done when the control key is pressed: for
848 example, for CTRL-A key press the key down event still carries the
849 same key code @c 'a' as usual but the char event will have key code of 1,
850 the ASCII value of this key combination.
852 You may discover how the other keys on your system behave interactively by
853 running the @ref page_samples_text wxWidgets sample and pressing some keys
854 in any of the text controls shown in it.
856 @b Tip: be sure to call @c event.Skip() for events that you don't process in
857 key event function, otherwise menu shortcuts may cease to work under Windows.
859 @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
860 does not call @c event.Skip() then the corresponding char event
861 (@c EVT_CHAR) will not happen.
862 This is by design and enables the programs that handle both types of
863 events to be a bit simpler.
865 @note For Windows programmers: The key and char events in wxWidgets are
866 similar to but slightly different from Windows @c WM_KEYDOWN and
867 @c WM_CHAR events. In particular, Alt-x combination will generate a
868 char event in wxWidgets (unless it is used as an accelerator).
871 @beginEventTable{wxKeyEvent}
872 @event{EVT_KEY_DOWN(func)}
873 Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
874 @event{EVT_KEY_UP(func)}
875 Process a @c wxEVT_KEY_UP event (any key has been released).
876 @event{EVT_CHAR(func)}
877 Process a @c wxEVT_CHAR event.
885 class wxKeyEvent
: public wxEvent
,
886 public wxKeyboardState
891 Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
893 wxKeyEvent(wxEventType keyEventType
= wxEVT_NULL
);
896 Returns the virtual key code. ASCII events return normal ASCII values,
897 while non-ASCII events return values such as @b WXK_LEFT for the left cursor
898 key. See ::wxKeyCode for a full list of the virtual key codes.
900 Note that in Unicode build, the returned value is meaningful only if the
901 user entered a character that can be represented in current locale's default
902 charset. You can obtain the corresponding Unicode character using GetUnicodeKey().
904 int GetKeyCode() const;
908 Obtains the position (in client coordinates) at which the key was pressed.
910 wxPoint
GetPosition() const;
911 void GetPosition(long* x
, long* y
) const;
915 Returns the raw key code for this event. This is a platform-dependent scan code
916 which should only be used in advanced applications.
918 @note Currently the raw key codes are not supported by all ports, use
919 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
921 wxUint32
GetRawKeyCode() const;
924 Returns the low level key flags for this event. The flags are
925 platform-dependent and should only be used in advanced applications.
927 @note Currently the raw key flags are not supported by all ports, use
928 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
930 wxUint32
GetRawKeyFlags() const;
933 Returns the Unicode character corresponding to this key event.
935 This function is only available in Unicode build, i.e. when
936 @c wxUSE_UNICODE is 1.
938 wxChar
GetUnicodeKey() const;
941 Returns the X position (in client coordinates) of the event.
943 wxCoord
GetX() const;
946 Returns the Y position (in client coordinates) of the event.
948 wxCoord
GetY() const;
954 @class wxJoystickEvent
956 This event class contains information about joystick events, particularly
957 events received by windows.
959 @beginEventTable{wxJoystickEvent}
960 @event{EVT_JOY_BUTTON_DOWN(func)}
961 Process a @c wxEVT_JOY_BUTTON_DOWN event.
962 @event{EVT_JOY_BUTTON_UP(func)}
963 Process a @c wxEVT_JOY_BUTTON_UP event.
964 @event{EVT_JOY_MOVE(func)}
965 Process a @c wxEVT_JOY_MOVE event.
966 @event{EVT_JOY_ZMOVE(func)}
967 Process a @c wxEVT_JOY_ZMOVE event.
968 @event{EVT_JOYSTICK_EVENTS(func)}
969 Processes all joystick events.
977 class wxJoystickEvent
: public wxEvent
983 wxJoystickEvent(wxEventType eventType
= wxEVT_NULL
, int state
= 0,
984 int joystick
= wxJOYSTICK1
,
988 Returns @true if the event was a down event from the specified button
992 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
993 indicate any button down event.
995 bool ButtonDown(int button
= wxJOY_BUTTON_ANY
) const;
998 Returns @true if the specified button (or any button) was in a down state.
1001 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1002 indicate any button down event.
1004 bool ButtonIsDown(int button
= wxJOY_BUTTON_ANY
) const;
1007 Returns @true if the event was an up event from the specified button
1011 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1012 indicate any button down event.
1014 bool ButtonUp(int button
= wxJOY_BUTTON_ANY
) const;
1017 Returns the identifier of the button changing state.
1019 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
1021 int GetButtonChange() const;
1024 Returns the down state of the buttons.
1026 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
1028 int GetButtonState() const;
1031 Returns the identifier of the joystick generating the event - one of
1032 wxJOYSTICK1 and wxJOYSTICK2.
1034 int GetJoystick() const;
1037 Returns the x, y position of the joystick event.
1039 wxPoint
GetPosition() const;
1042 Returns the z position of the joystick event.
1044 int GetZPosition() const;
1047 Returns @true if this was a button up or down event
1048 (@e not 'is any button down?').
1050 bool IsButton() const;
1053 Returns @true if this was an x, y move event.
1055 bool IsMove() const;
1058 Returns @true if this was a z move event.
1060 bool IsZMove() const;
1066 @class wxScrollWinEvent
1068 A scroll event holds information about events sent from scrolling windows.
1070 Note that you can use the EVT_SCROLLWIN* macros for intercepting scroll window events
1071 from the receiving window.
1073 @beginEventTable{wxScrollWinEvent}
1074 @event{EVT_SCROLLWIN(func)}
1075 Process all scroll events.
1076 @event{EVT_SCROLLWIN_TOP(func)}
1077 Process wxEVT_SCROLLWIN_TOP scroll-to-top events.
1078 @event{EVT_SCROLLWIN_BOTTOM(func)}
1079 Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
1080 @event{EVT_SCROLLWIN_LINEUP(func)}
1081 Process wxEVT_SCROLLWIN_LINEUP line up events.
1082 @event{EVT_SCROLLWIN_LINEDOWN(func)}
1083 Process wxEVT_SCROLLWIN_LINEDOWN line down events.
1084 @event{EVT_SCROLLWIN_PAGEUP(func)}
1085 Process wxEVT_SCROLLWIN_PAGEUP page up events.
1086 @event{EVT_SCROLLWIN_PAGEDOWN(func)}
1087 Process wxEVT_SCROLLWIN_PAGEDOWN page down events.
1088 @event{EVT_SCROLLWIN_THUMBTRACK(func)}
1089 Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
1090 (frequent events sent as the user drags the thumbtrack).
1091 @event{EVT_SCROLLWIN_THUMBRELEASE(func)}
1092 Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
1099 @see wxScrollEvent, @ref overview_events
1101 class wxScrollWinEvent
: public wxEvent
1107 wxScrollWinEvent(wxEventType commandType
= wxEVT_NULL
, int pos
= 0,
1108 int orientation
= 0);
1111 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
1114 @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
1116 int GetOrientation() const;
1119 Returns the position of the scrollbar for the thumb track and release events.
1121 Note that this field can't be used for the other events, you need to query
1122 the window itself for the current position in that case.
1124 int GetPosition() const;
1130 @class wxSysColourChangedEvent
1132 This class is used for system colour change events, which are generated
1133 when the user changes the colour settings using the control panel.
1134 This is only appropriate under Windows.
1137 The default event handler for this event propagates the event to child windows,
1138 since Windows only sends the events to top-level windows.
1139 If intercepting this event for a top-level window, remember to call the base
1140 class handler, or to pass the event on to the window's children explicitly.
1142 @beginEventTable{wxSysColourChangedEvent}
1143 @event{EVT_SYS_COLOUR_CHANGED(func)}
1144 Process a @c wxEVT_SYS_COLOUR_CHANGED event.
1150 @see @ref overview_events
1152 class wxSysColourChangedEvent
: public wxEvent
1158 wxSysColourChangedEvent();
1164 @class wxWindowCreateEvent
1166 This event is sent just after the actual window associated with a wxWindow
1167 object has been created.
1169 Since it is derived from wxCommandEvent, the event propagates up
1170 the window hierarchy.
1172 @beginEventTable{wxWindowCreateEvent}
1173 @event{EVT_WINDOW_CREATE(func)}
1174 Process a @c wxEVT_CREATE event.
1180 @see @ref overview_events, wxWindowDestroyEvent
1182 class wxWindowCreateEvent
: public wxCommandEvent
1188 wxWindowCreateEvent(wxWindow
* win
= NULL
);
1190 /// Retutn the window being created.
1191 wxWindow
*GetWindow() const;
1199 A paint event is sent when a window's contents needs to be repainted.
1201 Please notice that in general it is impossible to change the drawing of a
1202 standard control (such as wxButton) and so you shouldn't attempt to handle
1203 paint events for them as even if it might work on some platforms, this is
1204 inherently not portable and won't work everywhere.
1207 Note that in a paint event handler, the application must always create a
1208 wxPaintDC object, even if you do not use it. Otherwise, under MS Windows,
1209 refreshing for this and other windows will go wrong.
1212 void MyWindow::OnPaint(wxPaintEvent& event)
1219 You can optimize painting by retrieving the rectangles that have been damaged
1220 and only repainting these. The rectangles are in terms of the client area,
1221 and are unscrolled, so you will need to do some calculations using the current
1222 view position to obtain logical, scrolled units.
1223 Here is an example of using the wxRegionIterator class:
1225 // Called when window needs to be repainted.
1226 void MyWindow::OnPaint(wxPaintEvent& event)
1230 // Find Out where the window is scrolled to
1231 int vbX,vbY; // Top left corner of client
1232 GetViewStart(&vbX,&vbY);
1234 int vX,vY,vW,vH; // Dimensions of client area in pixels
1235 wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
1244 // Alternatively we can do this:
1245 // wxRect rect(upd.GetRect());
1247 // Repaint this rectangle
1256 @beginEventTable{wxPaintEvent}
1257 @event{EVT_PAINT(func)}
1258 Process a @c wxEVT_PAINT event.
1264 @see @ref overview_events
1266 class wxPaintEvent
: public wxEvent
1272 wxPaintEvent(int id
= 0);
1278 @class wxMaximizeEvent
1280 An event being sent when a top level window is maximized. Notice that it is
1281 not sent when the window is restored to its original size after it had been
1282 maximized, only a normal wxSizeEvent is generated in this case.
1284 @beginEventTable{wxMaximizeEvent}
1285 @event{EVT_MAXIMIZE(func)}
1286 Process a @c wxEVT_MAXIMIZE event.
1292 @see @ref overview_events, wxTopLevelWindow::Maximize,
1293 wxTopLevelWindow::IsMaximized
1295 class wxMaximizeEvent
: public wxEvent
1299 Constructor. Only used by wxWidgets internally.
1301 wxMaximizeEvent(int id
= 0);
1305 The possibles modes to pass to wxUpdateUIEvent::SetMode().
1309 /** Send UI update events to all windows. */
1310 wxUPDATE_UI_PROCESS_ALL
,
1312 /** Send UI update events to windows that have
1313 the wxWS_EX_PROCESS_UI_UPDATES flag specified. */
1314 wxUPDATE_UI_PROCESS_SPECIFIED
1319 @class wxUpdateUIEvent
1321 This class is used for pseudo-events which are called by wxWidgets
1322 to give an application the chance to update various user interface elements.
1324 Without update UI events, an application has to work hard to check/uncheck,
1325 enable/disable, show/hide, and set the text for elements such as menu items
1326 and toolbar buttons. The code for doing this has to be mixed up with the code
1327 that is invoked when an action is invoked for a menu item or button.
1329 With update UI events, you define an event handler to look at the state of the
1330 application and change UI elements accordingly. wxWidgets will call your member
1331 functions in idle time, so you don't have to worry where to call this code.
1333 In addition to being a clearer and more declarative method, it also means you don't
1334 have to worry whether you're updating a toolbar or menubar identifier. The same
1335 handler can update a menu item and toolbar button, if the identifier is the same.
1336 Instead of directly manipulating the menu or button, you call functions in the event
1337 object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a
1338 call has been made, and which UI element to update.
1340 These events will work for popup menus as well as menubars. Just before a menu is
1341 popped up, wxMenu::UpdateUI is called to process any UI events for the window that
1344 If you find that the overhead of UI update processing is affecting your application,
1345 you can do one or both of the following:
1346 @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED,
1347 and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should
1348 receive update events. No other windows will receive update events.
1349 @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay
1350 between updates. You may need to call wxWindow::UpdateWindowUI at critical points,
1351 for example when a dialog is about to be shown, in case the user sees a slight
1352 delay before windows are updated.
1354 Note that although events are sent in idle time, defining a wxIdleEvent handler
1355 for a window does not affect this because the events are sent from wxWindow::OnInternalIdle
1356 which is always called in idle time.
1358 wxWidgets tries to optimize update events on some platforms.
1359 On Windows and GTK+, events for menubar items are only sent when the menu is about
1360 to be shown, and not in idle time.
1363 @beginEventTable{wxUpdateUIEvent}
1364 @event{EVT_UPDATE_UI(id, func)}
1365 Process a @c wxEVT_UPDATE_UI event for the command with the given id.
1366 @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}
1367 Process a @c wxEVT_UPDATE_UI event for any command with id included in the given range.
1373 @see @ref overview_events
1375 class wxUpdateUIEvent
: public wxCommandEvent
1381 wxUpdateUIEvent(wxWindowID commandId
= 0);
1384 Returns @true if it is appropriate to update (send UI update events to)
1387 This function looks at the mode used (see wxUpdateUIEvent::SetMode),
1388 the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events
1389 were last sent in idle time, and the update interval, to determine whether
1390 events should be sent to this window now. By default this will always
1391 return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL
1392 and the interval is set to 0; so update events will be sent as often as
1393 possible. You can reduce the frequency that events are sent by changing the
1394 mode and/or setting an update interval.
1396 @see ResetUpdateTime(), SetUpdateInterval(), SetMode()
1398 static bool CanUpdate(wxWindow
* window
);
1401 Check or uncheck the UI element.
1403 void Check(bool check
);
1406 Enable or disable the UI element.
1408 void Enable(bool enable
);
1411 Returns @true if the UI element should be checked.
1413 bool GetChecked() const;
1416 Returns @true if the UI element should be enabled.
1418 bool GetEnabled() const;
1421 Static function returning a value specifying how wxWidgets will send update
1422 events: to all windows, or only to those which specify that they will process
1427 static wxUpdateUIMode
GetMode();
1430 Returns @true if the application has called Check().
1431 For wxWidgets internal use only.
1433 bool GetSetChecked() const;
1436 Returns @true if the application has called Enable().
1437 For wxWidgets internal use only.
1439 bool GetSetEnabled() const;
1442 Returns @true if the application has called Show().
1443 For wxWidgets internal use only.
1445 bool GetSetShown() const;
1448 Returns @true if the application has called SetText().
1449 For wxWidgets internal use only.
1451 bool GetSetText() const;
1454 Returns @true if the UI element should be shown.
1456 bool GetShown() const;
1459 Returns the text that should be set for the UI element.
1461 wxString
GetText() const;
1464 Returns the current interval between updates in milliseconds.
1465 The value -1 disables updates, 0 updates as frequently as possible.
1467 @see SetUpdateInterval().
1469 static long GetUpdateInterval();
1472 Used internally to reset the last-updated time to the current time.
1474 It is assumed that update events are normally sent in idle time, so this
1475 is called at the end of idle processing.
1477 @see CanUpdate(), SetUpdateInterval(), SetMode()
1479 static void ResetUpdateTime();
1482 Specify how wxWidgets will send update events: to all windows, or only to
1483 those which specify that they will process the events.
1486 this parameter may be one of the ::wxUpdateUIMode enumeration values.
1487 The default mode is wxUPDATE_UI_PROCESS_ALL.
1489 static void SetMode(wxUpdateUIMode mode
);
1492 Sets the text for this UI element.
1494 void SetText(const wxString
& text
);
1497 Sets the interval between updates in milliseconds.
1499 Set to -1 to disable updates, or to 0 to update as frequently as possible.
1502 Use this to reduce the overhead of UI update events if your application
1503 has a lot of windows. If you set the value to -1 or greater than 0,
1504 you may also need to call wxWindow::UpdateWindowUI at appropriate points
1505 in your application, such as when a dialog is about to be shown.
1507 static void SetUpdateInterval(long updateInterval
);
1510 Show or hide the UI element.
1512 void Show(bool show
);
1518 @class wxClipboardTextEvent
1520 This class represents the events generated by a control (typically a
1521 wxTextCtrl but other windows can generate these events as well) when its
1522 content gets copied or cut to, or pasted from the clipboard.
1524 There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY,
1525 wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE.
1527 If any of these events is processed (without being skipped) by an event
1528 handler, the corresponding operation doesn't take place which allows to
1529 prevent the text from being copied from or pasted to a control. It is also
1530 possible to examine the clipboard contents in the PASTE event handler and
1531 transform it in some way before inserting in a control -- for example,
1532 changing its case or removing invalid characters.
1534 Finally notice that a CUT event is always preceded by the COPY event which
1535 makes it possible to only process the latter if it doesn't matter if the
1536 text was copied or cut.
1539 These events are currently only generated by wxTextCtrl under GTK+.
1540 They are generated by all controls under Windows.
1542 @beginEventTable{wxClipboardTextEvent}
1543 @event{EVT_TEXT_COPY(id, func)}
1544 Some or all of the controls content was copied to the clipboard.
1545 @event{EVT_TEXT_CUT(id, func)}
1546 Some or all of the controls content was cut (i.e. copied and
1548 @event{EVT_TEXT_PASTE(id, func)}
1549 Clipboard content was pasted into the control.
1558 class wxClipboardTextEvent
: public wxCommandEvent
1564 wxClipboardTextEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
1572 This event class contains information about the events generated by the mouse:
1573 they include mouse buttons press and release events and mouse move events.
1575 All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the
1576 left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and
1577 @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more
1578 buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events
1579 can also be generated. Note that not all mice have even a middle button so a
1580 portable application should avoid relying on the events from it (but the right
1581 button click can be emulated using the left mouse button with the control key
1582 under Mac platforms with a single button mouse).
1584 For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events
1585 purposes, the mouse is considered to be inside the window if it is in the
1586 window client area and not inside one of its children. In other words, the
1587 parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
1588 mouse leaves the window entirely but also when it enters one of its children.
1590 The position associated with a mouse event is expressed in the window
1591 coordinates of the window which generated the event, you can use
1592 wxWindow::ClientToScreen() to convert it to screen coordinates and possibly
1593 call wxWindow::ScreenToClient() next to convert it to window coordinates of
1596 @note Note that under Windows CE mouse enter and leave events are not natively
1597 supported by the system but are generated by wxWidgets itself. This has several
1598 drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
1599 left the window and the state variables for it may have changed during this time.
1601 @note Note the difference between methods like wxMouseEvent::LeftDown and
1602 wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds
1603 to the left mouse button click while the latter returns @true if the left
1604 mouse button is currently being pressed. For example, when the user is dragging
1605 the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse
1606 button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown
1607 returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets
1608 whatever the underlying GUI behaviour is (which is platform-dependent).
1609 The same applies, of course, to other mouse buttons as well.
1612 @beginEventTable{wxMouseEvent}
1613 @event{EVT_LEFT_DOWN(func)}
1614 Process a @c wxEVT_LEFT_DOWN event. The handler of this event should normally
1615 call event.Skip() to allow the default processing to take place as otherwise
1616 the window under mouse wouldn't get the focus.
1617 @event{EVT_LEFT_UP(func)}
1618 Process a @c wxEVT_LEFT_UP event.
1619 @event{EVT_LEFT_DCLICK(func)}
1620 Process a @c wxEVT_LEFT_DCLICK event.
1621 @event{EVT_MIDDLE_DOWN(func)}
1622 Process a @c wxEVT_MIDDLE_DOWN event.
1623 @event{EVT_MIDDLE_UP(func)}
1624 Process a @c wxEVT_MIDDLE_UP event.
1625 @event{EVT_MIDDLE_DCLICK(func)}
1626 Process a @c wxEVT_MIDDLE_DCLICK event.
1627 @event{EVT_RIGHT_DOWN(func)}
1628 Process a @c wxEVT_RIGHT_DOWN event.
1629 @event{EVT_RIGHT_UP(func)}
1630 Process a @c wxEVT_RIGHT_UP event.
1631 @event{EVT_RIGHT_DCLICK(func)}
1632 Process a @c wxEVT_RIGHT_DCLICK event.
1633 @event{EVT_MOUSE_AUX1_DOWN(func)}
1634 Process a @c wxEVT_MOUSE_AUX1_DOWN event.
1635 @event{EVT_MOUSE_AUX1_UP(func)}
1636 Process a @c wxEVT_MOUSE_AUX1_UP event.
1637 @event{EVT_MOUSE_AUX1_DCLICK(func)}
1638 Process a @c wxEVT_MOUSE_AUX1_DCLICK event.
1639 @event{EVT_MOUSE_AUX2_DOWN(func)}
1640 Process a @c wxEVT_MOUSE_AUX2_DOWN event.
1641 @event{EVT_MOUSE_AUX2_UP(func)}
1642 Process a @c wxEVT_MOUSE_AUX2_UP event.
1643 @event{EVT_MOUSE_AUX2_DCLICK(func)}
1644 Process a @c wxEVT_MOUSE_AUX2_DCLICK event.
1645 @event{EVT_MOTION(func)}
1646 Process a @c wxEVT_MOTION event.
1647 @event{EVT_ENTER_WINDOW(func)}
1648 Process a @c wxEVT_ENTER_WINDOW event.
1649 @event{EVT_LEAVE_WINDOW(func)}
1650 Process a @c wxEVT_LEAVE_WINDOW event.
1651 @event{EVT_MOUSEWHEEL(func)}
1652 Process a @c wxEVT_MOUSEWHEEL event.
1653 @event{EVT_MOUSE_EVENTS(func)}
1654 Process all mouse events.
1662 class wxMouseEvent
: public wxEvent
,
1667 Constructor. Valid event types are:
1669 @li wxEVT_ENTER_WINDOW
1670 @li wxEVT_LEAVE_WINDOW
1673 @li wxEVT_LEFT_DCLICK
1674 @li wxEVT_MIDDLE_DOWN
1676 @li wxEVT_MIDDLE_DCLICK
1677 @li wxEVT_RIGHT_DOWN
1679 @li wxEVT_RIGHT_DCLICK
1680 @li wxEVT_MOUSE_AUX1_DOWN
1681 @li wxEVT_MOUSE_AUX1_UP
1682 @li wxEVT_MOUSE_AUX1_DCLICK
1683 @li wxEVT_MOUSE_AUX2_DOWN
1684 @li wxEVT_MOUSE_AUX2_UP
1685 @li wxEVT_MOUSE_AUX2_DCLICK
1687 @li wxEVT_MOUSEWHEEL
1689 wxMouseEvent(wxEventType mouseEventType
= wxEVT_NULL
);
1692 Returns @true if the event was a first extra button double click.
1694 bool Aux1DClick() const;
1697 Returns @true if the first extra button mouse button changed to down.
1699 bool Aux1Down() const;
1702 Returns @true if the first extra button mouse button is currently down,
1703 independent of the current event type.
1705 bool Aux1IsDown() const;
1708 Returns @true if the first extra button mouse button changed to up.
1710 bool Aux1Up() const;
1713 Returns @true if the event was a second extra button double click.
1715 bool Aux2DClick() const;
1718 Returns @true if the second extra button mouse button changed to down.
1720 bool Aux2Down() const;
1723 Returns @true if the second extra button mouse button is currently down,
1724 independent of the current event type.
1726 bool Aux2IsDown() const;
1729 Returns @true if the second extra button mouse button changed to up.
1731 bool Aux2Up() const;
1734 Returns @true if the identified mouse button is changing state.
1735 Valid values of @a button are:
1737 @li @c wxMOUSE_BTN_LEFT: check if left button was pressed
1738 @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed
1739 @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed
1740 @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed
1741 @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed
1742 @li @c wxMOUSE_BTN_ANY: check if any button was pressed
1744 @todo introduce wxMouseButton enum
1746 bool Button(int button
) const;
1749 If the argument is omitted, this returns @true if the event was a mouse
1750 double click event. Otherwise the argument specifies which double click event
1751 was generated (see Button() for the possible values).
1753 bool ButtonDClick(int but
= wxMOUSE_BTN_ANY
) const;
1756 If the argument is omitted, this returns @true if the event was a mouse
1757 button down event. Otherwise the argument specifies which button-down event
1758 was generated (see Button() for the possible values).
1760 bool ButtonDown(int = wxMOUSE_BTN_ANY
) const;
1763 If the argument is omitted, this returns @true if the event was a mouse
1764 button up event. Otherwise the argument specifies which button-up event
1765 was generated (see Button() for the possible values).
1767 bool ButtonUp(int = wxMOUSE_BTN_ANY
) const;
1770 Returns @true if this was a dragging event (motion while a button is depressed).
1774 bool Dragging() const;
1777 Returns @true if the mouse was entering the window.
1781 bool Entering() const;
1784 Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE
1785 if no button is involved (for mouse move, enter or leave event, for example).
1786 Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and
1787 double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT
1788 for the same events for the middle and the right buttons respectively.
1790 int GetButton() const;
1793 Returns the number of mouse clicks for this event: 1 for a simple click, 2
1794 for a double-click, 3 for a triple-click and so on.
1796 Currently this function is implemented only in wxMac and returns -1 for the
1797 other platforms (you can still distinguish simple clicks from double-clicks as
1798 they generate different kinds of events however).
1802 int GetClickCount() const;
1805 Returns the configured number of lines (or whatever) to be scrolled per
1806 wheel action. Defaults to three.
1808 int GetLinesPerAction() const;
1811 Returns the logical mouse position in pixels (i.e. translated according to the
1812 translation set for the DC, which usually indicates that the window has been
1815 wxPoint
GetLogicalPosition(const wxDC
& dc
) const;
1819 Sets *x and *y to the position at which the event occurred.
1820 Returns the physical mouse position in pixels.
1822 Note that if the mouse event has been artificially generated from a special
1823 keyboard combination (e.g. under Windows when the "menu" key is pressed), the
1824 returned position is ::wxDefaultPosition.
1826 wxPoint
GetPosition() const;
1827 void GetPosition(wxCoord
* x
, wxCoord
* y
) const;
1828 void GetPosition(long* x
, long* y
) const;
1832 Get wheel delta, normally 120.
1834 This is the threshold for action to be taken, and one such action
1835 (for example, scrolling one increment) should occur for each delta.
1837 int GetWheelDelta() const;
1840 Get wheel rotation, positive or negative indicates direction of rotation.
1842 Current devices all send an event when rotation is at least +/-WheelDelta, but
1843 finer resolution devices can be created in the future.
1845 Because of this you shouldn't assume that one event is equal to 1 line, but you
1846 should be able to either do partial line scrolling or wait until several
1847 events accumulate before scrolling.
1849 int GetWheelRotation() const;
1852 Gets the axis the wheel operation concerns; @c 0 is the Y axis as on
1853 most mouse wheels, @c 1 is the X axis.
1855 Note that only some models of mouse have horizontal wheel axis.
1857 int GetWheelAxis() const;
1860 Returns X coordinate of the physical mouse event position.
1862 wxCoord
GetX() const;
1865 Returns Y coordinate of the physical mouse event position.
1867 wxCoord
GetY() const;
1870 Returns @true if the event was a mouse button event (not necessarily a button
1871 down event - that may be tested using ButtonDown()).
1873 bool IsButton() const;
1876 Returns @true if the system has been setup to do page scrolling with
1877 the mouse wheel instead of line scrolling.
1879 bool IsPageScroll() const;
1882 Returns @true if the mouse was leaving the window.
1886 bool Leaving() const;
1889 Returns @true if the event was a left double click.
1891 bool LeftDClick() const;
1894 Returns @true if the left mouse button changed to down.
1896 bool LeftDown() const;
1899 Returns @true if the left mouse button is currently down, independent
1900 of the current event type.
1902 Please notice that it is not the same as LeftDown() which returns @true if the
1903 event was generated by the left mouse button being pressed. Rather, it simply
1904 describes the state of the left mouse button at the time when the event was
1905 generated (so while it will be @true for a left click event, it can also be @true
1906 for a right click if it happened while the left mouse button was pressed).
1908 This event is usually used in the mouse event handlers which process "move
1909 mouse" messages to determine whether the user is (still) dragging the mouse.
1911 bool LeftIsDown() const;
1914 Returns @true if the left mouse button changed to up.
1916 bool LeftUp() const;
1919 Returns @true if the Meta key was down at the time of the event.
1921 bool MetaDown() const;
1924 Returns @true if the event was a middle double click.
1926 bool MiddleDClick() const;
1929 Returns @true if the middle mouse button changed to down.
1931 bool MiddleDown() const;
1934 Returns @true if the middle mouse button is currently down, independent
1935 of the current event type.
1937 bool MiddleIsDown() const;
1940 Returns @true if the middle mouse button changed to up.
1942 bool MiddleUp() const;
1945 Returns @true if this was a motion event and no mouse buttons were pressed.
1946 If any mouse button is held pressed, then this method returns @false and
1947 Dragging() returns @true.
1949 bool Moving() const;
1952 Returns @true if the event was a right double click.
1954 bool RightDClick() const;
1957 Returns @true if the right mouse button changed to down.
1959 bool RightDown() const;
1962 Returns @true if the right mouse button is currently down, independent
1963 of the current event type.
1965 bool RightIsDown() const;
1968 Returns @true if the right mouse button changed to up.
1970 bool RightUp() const;
1976 @class wxDropFilesEvent
1978 This class is used for drop files events, that is, when files have been dropped
1979 onto the window. This functionality is currently only available under Windows.
1981 The window must have previously been enabled for dropping by calling
1982 wxWindow::DragAcceptFiles().
1984 Important note: this is a separate implementation to the more general drag and drop
1985 implementation documented in the @ref overview_dnd. It uses the older, Windows
1986 message-based approach of dropping files.
1988 @beginEventTable{wxDropFilesEvent}
1989 @event{EVT_DROP_FILES(func)}
1990 Process a @c wxEVT_DROP_FILES event.
1998 @see @ref overview_events
2000 class wxDropFilesEvent
: public wxEvent
2006 wxDropFilesEvent(wxEventType id
= 0, int noFiles
= 0,
2007 wxString
* files
= NULL
);
2010 Returns an array of filenames.
2012 wxString
* GetFiles() const;
2015 Returns the number of files dropped.
2017 int GetNumberOfFiles() const;
2020 Returns the position at which the files were dropped.
2021 Returns an array of filenames.
2023 wxPoint
GetPosition() const;
2029 @class wxCommandEvent
2031 This event class contains information about command events, which originate
2032 from a variety of simple controls.
2034 Note that wxCommandEvents and wxCommandEvent-derived event classes by default
2035 and unlike other wxEvent-derived classes propagate upward from the source
2036 window (the window which emits the event) up to the first parent which processes
2037 the event. Be sure to read @ref overview_events_propagation.
2039 More complex controls, such as wxTreeCtrl, have separate command event classes.
2041 @beginEventTable{wxCommandEvent}
2042 @event{EVT_COMMAND(id, event, func)}
2043 Process a command, supplying the window identifier, command event identifier,
2044 and member function.
2045 @event{EVT_COMMAND_RANGE(id1, id2, event, func)}
2046 Process a command for a range of window identifiers, supplying the minimum and
2047 maximum window identifiers, command event identifier, and member function.
2048 @event{EVT_BUTTON(id, func)}
2049 Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
2050 @event{EVT_CHECKBOX(id, func)}
2051 Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
2052 @event{EVT_CHOICE(id, func)}
2053 Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
2054 @event{EVT_COMBOBOX(id, func)}
2055 Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
2056 @event{EVT_LISTBOX(id, func)}
2057 Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
2058 @event{EVT_LISTBOX_DCLICK(id, func)}
2059 Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
2060 @event{EVT_CHECKLISTBOX(id, func)}
2061 Process a @c wxEVT_COMMAND_CHECKLISTBOX_TOGGLED command, which is generated by a wxCheckListBox control.
2062 @event{EVT_MENU(id, func)}
2063 Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
2064 @event{EVT_MENU_RANGE(id1, id2, func)}
2065 Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
2066 @event{EVT_CONTEXT_MENU(func)}
2067 Process the event generated when the user has requested a popup menu to appear by
2068 pressing a special keyboard key (under Windows) or by right clicking the mouse.
2069 @event{EVT_RADIOBOX(id, func)}
2070 Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
2071 @event{EVT_RADIOBUTTON(id, func)}
2072 Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
2073 @event{EVT_SCROLLBAR(id, func)}
2074 Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
2075 control. This is provided for compatibility only; more specific scrollbar event macros
2076 should be used instead (see wxScrollEvent).
2077 @event{EVT_SLIDER(id, func)}
2078 Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
2079 @event{EVT_TEXT(id, func)}
2080 Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
2081 @event{EVT_TEXT_ENTER(id, func)}
2082 Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
2083 Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
2084 to generate such events.
2085 @event{EVT_TEXT_MAXLEN(id, func)}
2086 Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
2087 when the user tries to enter more characters into it than the limit previously set
2088 with SetMaxLength().
2089 @event{EVT_TOGGLEBUTTON(id, func)}
2090 Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
2091 @event{EVT_TOOL(id, func)}
2092 Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED).
2093 Pass the id of the tool.
2094 @event{EVT_TOOL_RANGE(id1, id2, func)}
2095 Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
2096 @event{EVT_TOOL_RCLICKED(id, func)}
2097 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
2098 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
2099 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
2100 @event{EVT_TOOL_ENTER(id, func)}
2101 Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
2102 The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
2103 has moved off a tool.
2104 @event{EVT_COMMAND_LEFT_CLICK(id, func)}
2105 Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
2106 @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
2107 Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
2108 @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
2109 Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
2110 @event{EVT_COMMAND_SET_FOCUS(id, func)}
2111 Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
2112 @event{EVT_COMMAND_KILL_FOCUS(id, func)}
2113 Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
2114 @event{EVT_COMMAND_ENTER(id, func)}
2115 Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
2121 class wxCommandEvent
: public wxEvent
2127 wxCommandEvent(wxEventType commandEventType
= wxEVT_NULL
, int id
= 0);
2130 Returns client data pointer for a listbox or choice selection event
2131 (not valid for a deselection).
2133 void* GetClientData() const;
2136 Returns client object pointer for a listbox or choice selection event
2137 (not valid for a deselection).
2139 wxClientData
* GetClientObject() const;
2142 Returns extra information dependant on the event objects type.
2144 If the event comes from a listbox selection, it is a boolean
2145 determining whether the event was a selection (@true) or a
2146 deselection (@false). A listbox deselection only occurs for
2147 multiple-selection boxes, and in this case the index and string values
2148 are indeterminate and the listbox must be examined by the application.
2150 long GetExtraLong() const;
2153 Returns the integer identifier corresponding to a listbox, choice or
2154 radiobox selection (only if the event was a selection, not a deselection),
2155 or a boolean value representing the value of a checkbox.
2160 Returns item index for a listbox or choice selection event (not valid for
2163 int GetSelection() const;
2166 Returns item string for a listbox or choice selection event. If one
2167 or several items have been deselected, returns the index of the first
2168 deselected item. If some items have been selected and others deselected
2169 at the same time, it will return the index of the first selected item.
2171 wxString
GetString() const;
2174 This method can be used with checkbox and menu events: for the checkboxes, the
2175 method returns @true for a selection event and @false for a deselection one.
2176 For the menu events, this method indicates if the menu item just has become
2177 checked or unchecked (and thus only makes sense for checkable menu items).
2179 Notice that this method can not be used with wxCheckListBox currently.
2181 bool IsChecked() const;
2184 For a listbox or similar event, returns @true if it is a selection, @false
2185 if it is a deselection. If some items have been selected and others deselected
2186 at the same time, it will return @true.
2188 bool IsSelection() const;
2191 Sets the client data for this event.
2193 void SetClientData(void* clientData
);
2196 Sets the client object for this event. The client object is not owned by the
2197 event object and the event object will not delete the client object in its destructor.
2199 The client object must be owned and deleted by another object (e.g. a control)
2200 that has longer life time than the event object.
2202 void SetClientObject(wxClientData
* clientObject
);
2205 Sets the @b m_extraLong member.
2207 void SetExtraLong(long extraLong
);
2210 Sets the @b m_commandInt member.
2212 void SetInt(int intCommand
);
2215 Sets the @b m_commandString member.
2217 void SetString(const wxString
& string
);
2223 @class wxActivateEvent
2225 An activate event is sent when a window or application is being activated
2228 @beginEventTable{wxActivateEvent}
2229 @event{EVT_ACTIVATE(func)}
2230 Process a @c wxEVT_ACTIVATE event.
2231 @event{EVT_ACTIVATE_APP(func)}
2232 Process a @c wxEVT_ACTIVATE_APP event.
2233 This event is received by the wxApp-derived instance only.
2234 @event{EVT_HIBERNATE(func)}
2235 Process a hibernate event, supplying the member function. This event applies
2236 to wxApp only, and only on Windows SmartPhone and PocketPC.
2237 It is generated when the system is low on memory; the application should free
2238 up as much memory as possible, and restore full working state when it receives
2239 a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event.
2245 @see @ref overview_events, wxApp::IsActive
2247 class wxActivateEvent
: public wxEvent
2253 wxActivateEvent(wxEventType eventType
= wxEVT_NULL
, bool active
= true,
2257 Returns @true if the application or window is being activated, @false otherwise.
2259 bool GetActive() const;
2265 @class wxContextMenuEvent
2267 This class is used for context menu events, sent to give
2268 the application a chance to show a context (popup) menu for a wxWindow.
2270 Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this
2271 means that the event originated from a keyboard context button event, and you
2272 should compute a suitable position yourself, for example by calling wxGetMousePosition().
2274 When a keyboard context menu button is pressed on Windows, a right-click event
2275 with default position is sent first, and if this event is not processed, the
2276 context menu event is sent. So if you process mouse events and you find your
2277 context menu event handler is not being called, you could call wxEvent::Skip()
2278 for mouse right-down events.
2280 @beginEventTable{wxContextMenuEvent}
2281 @event{EVT_CONTEXT_MENU(func)}
2282 A right click (or other context menu command depending on platform) has been detected.
2289 @see wxCommandEvent, @ref overview_events
2291 class wxContextMenuEvent
: public wxCommandEvent
2297 wxContextMenuEvent(wxEventType id
= wxEVT_NULL
, int id
= 0,
2298 const wxPoint
& pos
= wxDefaultPosition
);
2301 Returns the position in screen coordinates at which the menu should be shown.
2302 Use wxWindow::ScreenToClient to convert to client coordinates.
2304 You can also omit a position from wxWindow::PopupMenu in order to use
2305 the current mouse pointer position.
2307 If the event originated from a keyboard event, the value returned from this
2308 function will be wxDefaultPosition.
2310 const wxPoint
& GetPosition() const;
2313 Sets the position at which the menu should be shown.
2315 void SetPosition(const wxPoint
& point
);
2323 An erase event is sent when a window's background needs to be repainted.
2325 On some platforms, such as GTK+, this event is simulated (simply generated just
2326 before the paint event) and may cause flicker. It is therefore recommended that
2327 you set the text background colour explicitly in order to prevent flicker.
2328 The default background colour under GTK+ is grey.
2330 To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
2333 You must call wxEraseEvent::GetDC and use the returned device context if it is
2334 non-@NULL. If it is @NULL, create your own temporary wxClientDC object.
2337 Use the device context returned by GetDC to draw on, don't create
2338 a wxPaintDC in the event handler.
2340 @beginEventTable{wxEraseEvent}
2341 @event{EVT_ERASE_BACKGROUND(func)}
2342 Process a @c wxEVT_ERASE_BACKGROUND event.
2348 @see @ref overview_events
2350 class wxEraseEvent
: public wxEvent
2356 wxEraseEvent(int id
= 0, wxDC
* dc
= NULL
);
2359 Returns the device context associated with the erase event to draw on.
2361 wxDC
* GetDC() const;
2369 A focus event is sent when a window's focus changes. The window losing focus
2370 receives a "kill focus" event while the window gaining it gets a "set focus" one.
2372 Notice that the set focus event happens both when the user gives focus to the
2373 window (whether using the mouse or keyboard) and when it is done from the
2374 program itself using wxWindow::SetFocus.
2376 @beginEventTable{wxFocusEvent}
2377 @event{EVT_SET_FOCUS(func)}
2378 Process a @c wxEVT_SET_FOCUS event.
2379 @event{EVT_KILL_FOCUS(func)}
2380 Process a @c wxEVT_KILL_FOCUS event.
2386 @see @ref overview_events
2388 class wxFocusEvent
: public wxEvent
2394 wxFocusEvent(wxEventType eventType
= wxEVT_NULL
, int id
= 0);
2397 Returns the window associated with this event, that is the window which had the
2398 focus before for the @c wxEVT_SET_FOCUS event and the window which is
2399 going to receive focus for the @c wxEVT_KILL_FOCUS one.
2401 Warning: the window pointer may be @NULL!
2403 wxWindow
*GetWindow() const;
2409 @class wxChildFocusEvent
2411 A child focus event is sent to a (parent-)window when one of its child windows
2412 gains focus, so that the window could restore the focus back to its corresponding
2413 child if it loses it now and regains later.
2415 Notice that child window is the direct child of the window receiving event.
2416 Use wxWindow::FindFocus() to retreive the window which is actually getting focus.
2418 @beginEventTable{wxChildFocusEvent}
2419 @event{EVT_CHILD_FOCUS(func)}
2420 Process a @c wxEVT_CHILD_FOCUS event.
2426 @see @ref overview_events
2428 class wxChildFocusEvent
: public wxCommandEvent
2435 The direct child which is (or which contains the window which is) receiving
2438 wxChildFocusEvent(wxWindow
* win
= NULL
);
2441 Returns the direct child which receives the focus, or a (grand-)parent of the
2442 control receiving the focus.
2444 To get the actually focused control use wxWindow::FindFocus.
2446 wxWindow
*GetWindow() const;
2452 @class wxMouseCaptureLostEvent
2454 An mouse capture lost event is sent to a window that obtained mouse capture,
2455 which was subsequently loss due to "external" event, for example when a dialog
2456 box is shown or if another application captures the mouse.
2458 If this happens, this event is sent to all windows that are on capture stack
2459 (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is
2460 not sent if the capture changes because of a call to CaptureMouse or
2463 This event is currently emitted under Windows only.
2465 @beginEventTable{wxMouseCaptureLostEvent}
2466 @event{EVT_MOUSE_CAPTURE_LOST(func)}
2467 Process a @c wxEVT_MOUSE_CAPTURE_LOST event.
2475 @see wxMouseCaptureChangedEvent, @ref overview_events,
2476 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
2478 class wxMouseCaptureLostEvent
: public wxEvent
2484 wxMouseCaptureLostEvent(wxWindowID windowId
= 0);
2490 @class wxNotifyEvent
2492 This class is not used by the event handlers by itself, but is a base class
2493 for other event classes (such as wxBookCtrlEvent).
2495 It (or an object of a derived class) is sent when the controls state is being
2496 changed and allows the program to wxNotifyEvent::Veto() this change if it wants
2497 to prevent it from happening.
2502 @see wxBookCtrlEvent
2504 class wxNotifyEvent
: public wxCommandEvent
2508 Constructor (used internally by wxWidgets only).
2510 wxNotifyEvent(wxEventType eventType
= wxEVT_NULL
, int id
= 0);
2513 This is the opposite of Veto(): it explicitly allows the event to be processed.
2514 For most events it is not necessary to call this method as the events are allowed
2515 anyhow but some are forbidden by default (this will be mentioned in the corresponding
2521 Returns @true if the change is allowed (Veto() hasn't been called) or @false
2522 otherwise (if it was).
2524 bool IsAllowed() const;
2527 Prevents the change announced by this event from happening.
2529 It is in general a good idea to notify the user about the reasons for vetoing
2530 the change because otherwise the applications behaviour (which just refuses to
2531 do what the user wants) might be quite surprising.
2538 @class wxThreadEvent
2540 This class adds some simple functionalities to wxCommandEvent coinceived
2541 for inter-threads communications.
2543 This event is not natively emitted by any control/class: this is just
2544 an helper class for the user.
2545 Its most important feature is the GetEventCategory() implementation which
2546 allows thread events to @b NOT be processed by wxEventLoopBase::YieldFor calls
2547 (unless the @c wxEVT_CATEGORY_THREAD is specified - which is never in wx code).
2552 @see @ref overview_thread, wxEventLoopBase::YieldFor
2554 class wxThreadEvent
: public wxCommandEvent
2560 wxThreadEvent(wxEventType eventType
= wxEVT_COMMAND_THREAD
, int id
= wxID_ANY
);
2563 Clones this event making sure that all internal members which use
2564 COW (only @c m_commandString for now; see @ref overview_refcount)
2565 are unshared (see wxObject::UnShare).
2567 virtual wxEvent
*Clone() const;
2570 Returns @c wxEVT_CATEGORY_THREAD.
2572 This is important to avoid unwanted processing of thread events
2573 when calling wxEventLoopBase::YieldFor().
2575 virtual wxEventCategory
GetEventCategory() const;
2582 A help event is sent when the user has requested context-sensitive help.
2583 This can either be caused by the application requesting context-sensitive help mode
2584 via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when
2585 the user pressed F1 or clicked on the query button in a dialog caption.
2587 A help event is sent to the window that the user clicked on, and is propagated
2588 up the window hierarchy until the event is processed or there are no more event
2591 The application should call wxEvent::GetId to check the identity of the
2592 clicked-on window, and then either show some suitable help or call wxEvent::Skip()
2593 if the identifier is unrecognised.
2595 Calling Skip is important because it allows wxWidgets to generate further
2596 events for ancestors of the clicked-on window. Otherwise it would be impossible to
2597 show help for container windows, since processing would stop after the first window
2600 @beginEventTable{wxHelpEvent}
2601 @event{EVT_HELP(id, func)}
2602 Process a @c wxEVT_HELP event.
2603 @event{EVT_HELP_RANGE(id1, id2, func)}
2604 Process a @c wxEVT_HELP event for a range of ids.
2610 @see wxContextHelp, wxDialog, @ref overview_events
2612 class wxHelpEvent
: public wxCommandEvent
2616 Indicates how a wxHelpEvent was generated.
2620 Origin_Unknown
, /**< unrecognized event source. */
2621 Origin_Keyboard
, /**< event generated from F1 key press. */
2623 /** event generated by wxContextHelp or from the [?] button on
2624 the title bar (Windows). */
2631 wxHelpEvent(wxEventType type
= wxEVT_NULL
,
2632 wxWindowID winid
= 0,
2633 const wxPoint
& pt
= wxDefaultPosition
,
2634 wxHelpEvent
::Origin origin
= Origin_Unknown
);
2637 Returns the origin of the help event which is one of the ::wxHelpEventOrigin
2640 The application may handle events generated using the keyboard or mouse
2641 differently, e.g. by using wxGetMousePosition() for the mouse events.
2645 wxHelpEvent
::Origin
GetOrigin() const;
2648 Returns the left-click position of the mouse, in screen coordinates.
2649 This allows the application to position the help appropriately.
2651 const wxPoint
& GetPosition() const;
2654 Set the help event origin, only used internally by wxWidgets normally.
2658 void SetOrigin(wxHelpEvent
::Origin origin
);
2661 Sets the left-click position of the mouse, in screen coordinates.
2663 void SetPosition(const wxPoint
& pt
);
2669 @class wxScrollEvent
2671 A scroll event holds information about events sent from stand-alone
2672 scrollbars (see wxScrollBar) and sliders (see wxSlider).
2674 Note that scrolled windows send the wxScrollWinEvent which does not derive from
2675 wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of
2676 events and use the event table macros mentioned below only for the scrollbar-like
2679 @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
2681 The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
2682 using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
2683 by an EVT_SCROLL_CHANGED event).
2685 The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb
2686 position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE
2687 event does not happen).
2689 In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished
2690 independently of the way it had started. Please see the widgets sample ("Slider" page)
2691 to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action.
2694 Note that unless specifying a scroll control identifier, you will need to test for scrollbar
2695 orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events
2696 are processed using the same event handler.
2698 @beginEventTable{wxScrollEvent}
2699 You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
2700 scroll events from controls, or EVT_SCROLL... macros without window IDs for
2701 intercepting scroll events from the receiving window -- except for this, the
2702 macros behave exactly the same.
2703 @event{EVT_SCROLL(func)}
2704 Process all scroll events.
2705 @event{EVT_SCROLL_TOP(func)}
2706 Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
2707 @event{EVT_SCROLL_BOTTOM(func)}
2708 Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
2709 @event{EVT_SCROLL_LINEUP(func)}
2710 Process wxEVT_SCROLL_LINEUP line up events.
2711 @event{EVT_SCROLL_LINEDOWN(func)}
2712 Process wxEVT_SCROLL_LINEDOWN line down events.
2713 @event{EVT_SCROLL_PAGEUP(func)}
2714 Process wxEVT_SCROLL_PAGEUP page up events.
2715 @event{EVT_SCROLL_PAGEDOWN(func)}
2716 Process wxEVT_SCROLL_PAGEDOWN page down events.
2717 @event{EVT_SCROLL_THUMBTRACK(func)}
2718 Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the
2719 user drags the thumbtrack).
2720 @event{EVT_SCROLL_THUMBRELEASE(func)}
2721 Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
2722 @event{EVT_SCROLL_CHANGED(func)}
2723 Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
2724 @event{EVT_COMMAND_SCROLL(id, func)}
2725 Process all scroll events.
2726 @event{EVT_COMMAND_SCROLL_TOP(id, func)}
2727 Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
2728 @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
2729 Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
2730 @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
2731 Process wxEVT_SCROLL_LINEUP line up events.
2732 @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
2733 Process wxEVT_SCROLL_LINEDOWN line down events.
2734 @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
2735 Process wxEVT_SCROLL_PAGEUP page up events.
2736 @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
2737 Process wxEVT_SCROLL_PAGEDOWN page down events.
2738 @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
2739 Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent
2740 as the user drags the thumbtrack).
2741 @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
2742 Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
2743 @event{EVT_COMMAND_SCROLL_CHANGED(func)}
2744 Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
2750 @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_events
2752 class wxScrollEvent
: public wxCommandEvent
2758 wxScrollEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0, int pos
= 0,
2759 int orientation
= 0);
2762 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
2765 int GetOrientation() const;
2768 Returns the position of the scrollbar.
2770 int GetPosition() const;
2774 See wxIdleEvent::SetMode() for more info.
2778 /** Send idle events to all windows */
2781 /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */
2782 wxIDLE_PROCESS_SPECIFIED
2789 This class is used for idle events, which are generated when the system becomes
2790 idle. Note that, unless you do something specifically, the idle events are not
2791 sent if the system remains idle once it has become it, e.g. only a single idle
2792 event will be generated until something else resulting in more normal events
2793 happens and only then is the next idle event sent again.
2795 If you need to ensure a continuous stream of idle events, you can either use
2796 wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically
2797 (for example from a timer event handler), but note that both of these approaches
2798 (and especially the first one) increase the system load and so should be avoided
2801 By default, idle events are sent to all windows (and also wxApp, as usual).
2802 If this is causing a significant overhead in your application, you can call
2803 wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the
2804 wxWS_EX_PROCESS_IDLE extra window style for every window which should receive
2807 @beginEventTable{wxIdleEvent}
2808 @event{EVT_IDLE(func)}
2809 Process a @c wxEVT_IDLE event.
2815 @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle
2817 class wxIdleEvent
: public wxEvent
2826 Returns @true if it is appropriate to send idle events to this window.
2828 This function looks at the mode used (see wxIdleEvent::SetMode),
2829 and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle
2830 events should be sent to this window now.
2832 By default this will always return @true because the update mode is initially
2833 wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to
2834 windows with the wxWS_EX_PROCESS_IDLE extra window style set.
2838 static bool CanSend(wxWindow
* window
);
2841 Static function returning a value specifying how wxWidgets will send idle
2842 events: to all windows, or only to those which specify that they
2843 will process the events.
2847 static wxIdleMode
GetMode();
2850 Returns @true if the OnIdle function processing this event requested more
2855 bool MoreRequested() const;
2858 Tells wxWidgets that more processing is required.
2860 This function can be called by an OnIdle handler for a window or window event
2861 handler to indicate that wxApp::OnIdle should forward the OnIdle event once
2862 more to the application windows.
2864 If no window calls this function during OnIdle, then the application will
2865 remain in a passive event loop (not calling OnIdle) until a new event is
2866 posted to the application by the windowing system.
2868 @see MoreRequested()
2870 void RequestMore(bool needMore
= true);
2873 Static function for specifying how wxWidgets will send idle events: to
2874 all windows, or only to those which specify that they will process the events.
2877 Can be one of the ::wxIdleMode values.
2878 The default is wxIDLE_PROCESS_ALL.
2880 static void SetMode(wxIdleMode mode
);
2886 @class wxInitDialogEvent
2888 A wxInitDialogEvent is sent as a dialog or panel is being initialised.
2889 Handlers for this event can transfer data to the window.
2891 The default handler calls wxWindow::TransferDataToWindow.
2893 @beginEventTable{wxInitDialogEvent}
2894 @event{EVT_INIT_DIALOG(func)}
2895 Process a @c wxEVT_INIT_DIALOG event.
2901 @see @ref overview_events
2903 class wxInitDialogEvent
: public wxEvent
2909 wxInitDialogEvent(int id
= 0);
2915 @class wxWindowDestroyEvent
2917 This event is sent as early as possible during the window destruction
2920 For the top level windows, as early as possible means that this is done by
2921 wxFrame or wxDialog destructor, i.e. after the destructor of the derived
2922 class was executed and so any methods specific to the derived class can't
2923 be called any more from this event handler. If you need to do this, you
2924 must call wxWindow::SendDestroyEvent() from your derived class destructor.
2926 For the child windows, this event is generated just before deleting the
2927 window from wxWindow::Destroy() (which is also called when the parent
2928 window is deleted) or from the window destructor if operator @c delete was
2929 used directly (which is not recommended for this very reason).
2931 It is usually pointless to handle this event in the window itself but it ca
2932 be very useful to receive notifications about the window destruction in the
2933 parent window or in any other object interested in this window.
2938 @see @ref overview_events, wxWindowCreateEvent
2940 class wxWindowDestroyEvent
: public wxCommandEvent
2946 wxWindowDestroyEvent(wxWindow
* win
= NULL
);
2948 /// Retutn the window being destroyed.
2949 wxWindow
*GetWindow() const;
2954 @class wxNavigationKeyEvent
2956 This event class contains information about navigation events,
2957 generated by navigation keys such as tab and page down.
2959 This event is mainly used by wxWidgets implementations.
2960 A wxNavigationKeyEvent handler is automatically provided by wxWidgets
2961 when you make a class into a control container with the macro
2962 WX_DECLARE_CONTROL_CONTAINER.
2964 @beginEventTable{wxNavigationKeyEvent}
2965 @event{EVT_NAVIGATION_KEY(func)}
2966 Process a navigation key event.
2972 @see wxWindow::Navigate, wxWindow::NavigateIn
2974 class wxNavigationKeyEvent
: public wxEvent
2978 Flags which can be used with wxNavigationKeyEvent.
2980 enum wxNavigationKeyEventFlags
2982 IsBackward
= 0x0000,
2988 wxNavigationKeyEvent();
2989 wxNavigationKeyEvent(const wxNavigationKeyEvent
& event
);
2992 Returns the child that has the focus, or @NULL.
2994 wxWindow
* GetCurrentFocus() const;
2997 Returns @true if the navigation was in the forward direction.
2999 bool GetDirection() const;
3002 Returns @true if the navigation event was from a tab key.
3003 This is required for proper navigation over radio buttons.
3005 bool IsFromTab() const;
3008 Returns @true if the navigation event represents a window change
3009 (for example, from Ctrl-Page Down in a notebook).
3011 bool IsWindowChange() const;
3014 Sets the current focus window member.
3016 void SetCurrentFocus(wxWindow
* currentFocus
);
3019 Sets the direction to forward if @a direction is @true, or backward
3022 void SetDirection(bool direction
);
3025 Sets the flags for this event.
3026 The @a flags can be a combination of the ::wxNavigationKeyEventFlags values.
3028 void SetFlags(long flags
);
3031 Marks the navigation event as from a tab key.
3033 void SetFromTab(bool fromTab
);
3036 Marks the event as a window change event.
3038 void SetWindowChange(bool windowChange
);
3044 @class wxMouseCaptureChangedEvent
3046 An mouse capture changed event is sent to a window that loses its
3047 mouse capture. This is called even if wxWindow::ReleaseMouse
3048 was called by the application code. Handling this event allows
3049 an application to cater for unexpected capture releases which
3050 might otherwise confuse mouse handling code.
3054 @beginEventTable{wxMouseCaptureChangedEvent}
3055 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
3056 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event.
3062 @see wxMouseCaptureLostEvent, @ref overview_events,
3063 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
3065 class wxMouseCaptureChangedEvent
: public wxEvent
3071 wxMouseCaptureChangedEvent(wxWindowID windowId
= 0,
3072 wxWindow
* gainedCapture
= NULL
);
3075 Returns the window that gained the capture, or @NULL if it was a
3076 non-wxWidgets window.
3078 wxWindow
* GetCapturedWindow() const;
3086 This event class contains information about window and session close events.
3088 The handler function for EVT_CLOSE is called when the user has tried to close a
3089 a frame or dialog box using the window manager (X) or system menu (Windows).
3090 It can also be invoked by the application itself programmatically, for example by
3091 calling the wxWindow::Close function.
3093 You should check whether the application is forcing the deletion of the window
3094 using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window
3095 using wxWindow::Destroy.
3097 If the return value is @true, it is up to you whether you respond by destroying
3100 If you don't destroy the window, you should call wxCloseEvent::Veto to
3101 let the calling code know that you did not destroy the window.
3102 This allows the wxWindow::Close function to return @true or @false depending
3103 on whether the close instruction was honoured or not.
3105 Example of a wxCloseEvent handler:
3108 void MyFrame::OnClose(wxCloseEvent& event)
3110 if ( event.CanVeto() && m_bFileNotSaved )
3112 if ( wxMessageBox("The file has not been saved... continue closing?",
3114 wxICON_QUESTION | wxYES_NO) != wxYES )
3121 Destroy(); // you may also do: event.Skip();
3122 // since the default event handler does call Destroy(), too
3126 The EVT_END_SESSION event is slightly different as it is sent by the system
3127 when the user session is ending (e.g. because of log out or shutdown) and
3128 so all windows are being forcefully closed. At least under MSW, after the
3129 handler for this event is executed the program is simply killed by the
3130 system. Because of this, the default handler for this event provided by
3131 wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so
3132 that it could still be executed and exit()s the process itself, without
3133 waiting for being killed. If this behaviour is for some reason undesirable,
3134 make sure that you define a handler for this event in your wxApp-derived
3135 class and do not call @c event.Skip() in it (but be aware that the system
3136 will still kill your application).
3138 @beginEventTable{wxCloseEvent}
3139 @event{EVT_CLOSE(func)}
3140 Process a close event, supplying the member function.
3141 This event applies to wxFrame and wxDialog classes.
3142 @event{EVT_QUERY_END_SESSION(func)}
3143 Process a query end session event, supplying the member function.
3144 This event can be handled in wxApp-derived class only.
3145 @event{EVT_END_SESSION(func)}
3146 Process an end session event, supplying the member function.
3147 This event can be handled in wxApp-derived class only.
3153 @see wxWindow::Close, @ref overview_windowdeletion
3155 class wxCloseEvent
: public wxEvent
3161 wxCloseEvent(wxEventType commandEventType
= wxEVT_NULL
, int id
= 0);
3164 Returns @true if you can veto a system shutdown or a window close event.
3165 Vetoing a window close event is not possible if the calling code wishes to
3166 force the application to exit, and so this function must be called to check this.
3168 bool CanVeto() const;
3171 Returns @true if the user is just logging off or @false if the system is
3172 shutting down. This method can only be called for end session and query end
3173 session events, it doesn't make sense for close window event.
3175 bool GetLoggingOff() const;
3178 Sets the 'can veto' flag.
3180 void SetCanVeto(bool canVeto
);
3183 Sets the 'logging off' flag.
3185 void SetLoggingOff(bool loggingOff
);
3188 Call this from your event handler to veto a system shutdown or to signal
3189 to the calling application that a window close did not happen.
3191 You can only veto a shutdown if CanVeto() returns @true.
3193 void Veto(bool veto
= true);
3201 This class is used for a variety of menu-related events. Note that
3202 these do not include menu command events, which are
3203 handled using wxCommandEvent objects.
3205 The default handler for @c wxEVT_MENU_HIGHLIGHT displays help
3206 text in the first field of the status bar.
3208 @beginEventTable{wxMenuEvent}
3209 @event{EVT_MENU_OPEN(func)}
3210 A menu is about to be opened. On Windows, this is only sent once for each
3211 navigation of the menubar (up until all menus have closed).
3212 @event{EVT_MENU_CLOSE(func)}
3213 A menu has been just closed.
3214 @event{EVT_MENU_HIGHLIGHT(id, func)}
3215 The menu item with the specified id has been highlighted: used to show
3216 help prompts in the status bar by wxFrame
3217 @event{EVT_MENU_HIGHLIGHT_ALL(func)}
3218 A menu item has been highlighted, i.e. the currently selected menu item has changed.
3224 @see wxCommandEvent, @ref overview_events
3226 class wxMenuEvent
: public wxEvent
3232 wxMenuEvent(wxEventType id
= wxEVT_NULL
, int id
= 0, wxMenu
* menu
= NULL
);
3235 Returns the menu which is being opened or closed. This method should only be
3236 used with the @c OPEN and @c CLOSE events and even for them the
3237 returned pointer may be @NULL in some ports.
3239 wxMenu
* GetMenu() const;
3242 Returns the menu identifier associated with the event.
3243 This method should be only used with the @c HIGHLIGHT events.
3245 int GetMenuId() const;
3248 Returns @true if the menu which is being opened or closed is a popup menu,
3249 @false if it is a normal one.
3251 This method should only be used with the @c OPEN and @c CLOSE events.
3253 bool IsPopup() const;
3259 An event being sent when the window is shown or hidden.
3261 Currently only wxMSW, wxGTK and wxOS2 generate such events.
3263 @onlyfor{wxmsw,wxgtk,wxos2}
3265 @beginEventTable{wxShowEvent}
3266 @event{EVT_SHOW(func)}
3267 Process a @c wxEVT_SHOW event.
3273 @see @ref overview_events, wxWindow::Show,
3277 class wxShowEvent
: public wxEvent
3283 wxShowEvent(int winid
= 0, bool show
= false);
3286 Set whether the windows was shown or hidden.
3288 void SetShow(bool show
);
3291 Return @true if the window has been shown, @false if it has been
3294 bool IsShown() const;
3297 @deprecated This function is deprecated in favour of IsShown().
3299 bool GetShow() const;
3305 @class wxIconizeEvent
3307 An event being sent when the frame is iconized (minimized) or restored.
3309 Currently only wxMSW and wxGTK generate such events.
3311 @onlyfor{wxmsw,wxgtk}
3313 @beginEventTable{wxIconizeEvent}
3314 @event{EVT_ICONIZE(func)}
3315 Process a @c wxEVT_ICONIZE event.
3321 @see @ref overview_events, wxTopLevelWindow::Iconize,
3322 wxTopLevelWindow::IsIconized
3324 class wxIconizeEvent
: public wxEvent
3330 wxIconizeEvent(int id
= 0, bool iconized
= true);
3333 Returns @true if the frame has been iconized, @false if it has been
3336 bool IsIconized() const;
3339 @deprecated This function is deprecated in favour of IsIconized().
3341 bool Iconized() const;
3349 A move event holds information about wxTopLevelWindow move change events.
3351 @beginEventTable{wxMoveEvent}
3352 @event{EVT_MOVE(func)}
3353 Process a @c wxEVT_MOVE event, which is generated when a window is moved.
3354 @event{EVT_MOVE_START(func)}
3355 Process a @c wxEVT_MOVE_START event, which is generated when the user starts
3356 to move or size a window. wxMSW only.
3357 @event{EVT_MOVE_END(func)}
3358 Process a @c wxEVT_MOVE_END event, which is generated when the user stops
3359 moving or sizing a window. wxMSW only.
3365 @see wxPoint, @ref overview_events
3367 class wxMoveEvent
: public wxEvent
3373 wxMoveEvent(const wxPoint
& pt
, int id
= 0);
3376 Returns the position of the window generating the move change event.
3378 wxPoint
GetPosition() const;
3385 A size event holds information about size change events of wxWindow.
3387 The EVT_SIZE handler function will be called when the window has been resized.
3389 You may wish to use this for frames to resize their child windows as appropriate.
3391 Note that the size passed is of the whole window: call wxWindow::GetClientSize
3392 for the area which may be used by the application.
3394 When a window is resized, usually only a small part of the window is damaged
3395 and you may only need to repaint that area. However, if your drawing depends on the
3396 size of the window, you may need to clear the DC explicitly and repaint the whole window.
3397 In which case, you may need to call wxWindow::Refresh to invalidate the entire window.
3399 @beginEventTable{wxSizeEvent}
3400 @event{EVT_SIZE(func)}
3401 Process a @c wxEVT_SIZE event.
3407 @see wxSize, @ref overview_events
3409 class wxSizeEvent
: public wxEvent
3415 wxSizeEvent(const wxSize
& sz
, int id
= 0);
3418 Returns the entire size of the window generating the size change event.
3420 wxSize
GetSize() const;
3426 @class wxSetCursorEvent
3428 A wxSetCursorEvent is generated from wxWindow when the mouse cursor is about
3429 to be set as a result of mouse motion.
3431 This event gives the application the chance to perform specific mouse cursor
3432 processing based on the current position of the mouse within the window.
3433 Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed.
3435 @beginEventTable{wxSetCursorEvent}
3436 @event{EVT_SET_CURSOR(func)}
3437 Process a @c wxEVT_SET_CURSOR event.
3443 @see ::wxSetCursor, wxWindow::wxSetCursor
3445 class wxSetCursorEvent
: public wxEvent
3449 Constructor, used by the library itself internally to initialize the event
3452 wxSetCursorEvent(wxCoord x
= 0, wxCoord y
= 0);
3455 Returns a reference to the cursor specified by this event.
3457 const wxCursor
& GetCursor() const;
3460 Returns the X coordinate of the mouse in client coordinates.
3462 wxCoord
GetX() const;
3465 Returns the Y coordinate of the mouse in client coordinates.
3467 wxCoord
GetY() const;
3470 Returns @true if the cursor specified by this event is a valid cursor.
3472 @remarks You cannot specify wxNullCursor with this event, as it is not
3473 considered a valid cursor.
3475 bool HasCursor() const;
3478 Sets the cursor associated with this event.
3480 void SetCursor(const wxCursor
& cursor
);
3485 // ============================================================================
3486 // Global functions/macros
3487 // ============================================================================
3489 /** @addtogroup group_funcmacro_events */
3493 A value uniquely identifying the type of the event.
3495 The values of this type should only be created using wxNewEventType().
3497 See the macro DEFINE_EVENT_TYPE() for more info.
3499 @see @ref overview_events_introduction
3501 typedef int wxEventType
;
3504 A special event type usually used to indicate that some wxEvent has yet
3507 wxEventType wxEVT_NULL
;
3510 Initializes a new event type using wxNewEventType().
3512 @deprecated Use wxDEFINE_EVENT() instead
3514 #define DEFINE_EVENT_TYPE(name) const wxEventType name = wxNewEventType();
3517 Generates a new unique event type.
3519 Usually this function is only used by wxDEFINE_EVENT() and not called
3522 wxEventType
wxNewEventType();
3525 Define a new event type associated with the specified event class.
3527 This macro defines a new unique event type @a name associated with the
3532 wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
3534 class MyCustomEvent : public wxEvent { ... };
3535 wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
3538 @see wxDECLARE_EVENT(), @ref overview_events_custom
3540 #define wxDEFINE_EVENT(name, cls) \
3541 const wxEventTypeTag< cls > name(wxNewEventType())
3544 Declares a custom event type.
3546 This macro declares a variable called @a name which must be defined
3547 elsewhere using wxDEFINE_EVENT().
3549 The class @a cls must be the wxEvent-derived class associated with the
3550 events of this type and its full declaration must be visible from the point
3551 of use of this macro.
3553 #define wxDECLARE_EVENT(name, cls) \
3554 wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls)
3557 Variant of wxDECLARE_EVENT() used for event types defined inside a shared
3560 This is mostly used by wxWidgets internally, e.g.
3562 wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_COMMAND_BUTTON_CLICKED, wxCommandEvent)
3565 #define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \
3566 extern const expdecl wxEventTypeTag< cls > name;
3569 Helper macro for definition of custom event table macros.
3571 This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise
3572 it is better and more clear to just use the address of the function
3573 directly as this is all this macro does in this case. However it needs to
3574 explicitly cast @a func to @a functype, which is the type of wxEvtHandler
3575 member function taking the custom event argument when
3576 wxEVENTS_COMPATIBILITY_2_8 is 0.
3578 See wx__DECLARE_EVT0 for an example of use.
3580 @see @ref overview_events_custom_ownclass
3582 #define wxEVENT_HANDLER_CAST(functype, func) (&func)
3586 These macros are used to define event table macros for handling custom
3591 class MyEvent : public wxEvent { ... };
3593 // note that this is not necessary unless using old compilers: for the
3594 // reasonably new ones just use &func instead of MyEventHandler(func)
3595 typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&);
3596 #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func)
3598 wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent);
3600 #define EVT_MY(id, func) \
3601 wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func))
3605 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
3606 EVT_MY(wxID_ANY, MyFrame::OnMyEvent)
3611 The event type to handle.
3613 The identifier of events to handle.
3615 The first identifier of the range.
3617 The second identifier of the range.
3619 The event handler method.
3621 #define wx__DECLARE_EVT2(evt, id1, id2, fn) \
3622 DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
3623 #define wx__DECLARE_EVT1(evt, id, fn) \
3624 wx__DECLARE_EVT2(evt, id, wxID_ANY, fn)
3625 #define wx__DECLARE_EVT0(evt, fn) \
3626 wx__DECLARE_EVT1(evt, wxID_ANY, fn)
3631 Use this macro inside a class declaration to declare a @e static event table
3634 In the implementation file you'll need to use the BEGIN_EVENT_TABLE()
3635 and the END_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro
3638 @see @ref overview_events_eventtables
3640 #define DECLARE_EVENT_TABLE()
3643 Use this macro in a source file to start listing @e static event handlers
3644 for a specific class.
3646 Use END_EVENT_TABLE() to terminate the event-declaration block.
3648 @see @ref overview_events_eventtables
3650 #define BEGIN_EVENT_TABLE(theClass, baseClass)
3653 Use this macro in a source file to end listing @e static event handlers
3654 for a specific class.
3656 Use BEGIN_EVENT_TABLE() to start the event-declaration block.
3658 @see @ref overview_events_eventtables
3660 #define END_EVENT_TABLE()
3663 In a GUI application, this function posts @a event to the specified @e dest
3664 object using wxEvtHandler::AddPendingEvent().
3666 Otherwise, it dispatches @a event immediately using
3667 wxEvtHandler::ProcessEvent(). See the respective documentation for details
3668 (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent()
3669 this function is not thread-safe for event objects having wxString fields,
3670 use wxQueueEvent() instead.
3674 void wxPostEvent(wxEvtHandler
* dest
, const wxEvent
& event
);
3677 Queue an event for processing on the given object.
3679 This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation
3685 The object to queue the event on, can't be @c NULL.
3687 The heap-allocated and non-@c NULL event to queue, the function takes
3690 void wxQueueEvent(wxEvtHandler
* dest
, wxEvent
*event
);