1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxEvtHandler, wxEventBlocker and many
4 // wxEvent-derived classes
5 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
12 The predefined constants for the number of times we propagate event
13 upwards window child-parent chain.
15 enum wxEventPropagation
17 /// don't propagate it at all
18 wxEVENT_PROPAGATE_NONE
= 0,
20 /// propagate it until it is processed
21 wxEVENT_PROPAGATE_MAX
= INT_MAX
25 The different categories for a wxEvent; see wxEvent::GetEventCategory.
27 @note They are used as OR-combinable flags by wxEventLoopBase::YieldFor.
32 This is the category for those events which are generated to update
33 the appearance of the GUI but which (usually) do not comport data
34 processing, i.e. which do not provide input or output data
35 (e.g. size events, scroll events, etc).
36 They are events NOT directly generated by the user's input devices.
38 wxEVT_CATEGORY_UI
= 1,
41 This category groups those events which are generated directly from the
42 user through input devices like mouse and keyboard and usually result in
43 data to be processed from the application
44 (e.g. mouse clicks, key presses, etc).
46 wxEVT_CATEGORY_USER_INPUT
= 2,
48 /// This category is for wxSocketEvent
49 wxEVT_CATEGORY_SOCKET
= 4,
51 /// This category is for wxTimerEvent
52 wxEVT_CATEGORY_TIMER
= 8,
55 This category is for any event used to send notifications from the
56 secondary threads to the main one or in general for notifications among
57 different threads (which may or may not be user-generated).
58 See e.g. wxThreadEvent.
60 wxEVT_CATEGORY_THREAD
= 16,
63 This mask is used in wxEventLoopBase::YieldFor to specify that all event
64 categories should be processed.
67 wxEVT_CATEGORY_UI
|wxEVT_CATEGORY_USER_INPUT
|wxEVT_CATEGORY_SOCKET
| \
68 wxEVT_CATEGORY_TIMER
|wxEVT_CATEGORY_THREAD
74 An event is a structure holding information about an event passed to a
75 callback or member function.
77 wxEvent used to be a multipurpose event object, and is an abstract base class
78 for other event classes (see below).
80 For more information about events, see the @ref overview_events overview.
83 In wxPerl custom event classes should be derived from
84 @c Wx::PlEvent and @c Wx::PlCommandEvent.
90 @see wxCommandEvent, wxMouseEvent
92 class wxEvent
: public wxObject
98 Notice that events are usually created by wxWidgets itself and creating
99 e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl
100 will not usually affect it at all as native controls have no specific
101 knowledge about wxWidgets events. However you may construct objects of
102 specific types and pass them to wxEvtHandler::ProcessEvent() if you
103 want to create your own custom control and want to process its events
104 in the same manner as the standard ones.
106 Also please notice that the order of parameters in this constructor is
107 different from almost all the derived classes which specify the event
108 type as the first argument.
111 The identifier of the object (window, timer, ...) which generated
114 The unique type of event, e.g. @c wxEVT_PAINT, @c wxEVT_SIZE or
117 wxEvent(int id
= 0, wxEventType eventType
= wxEVT_NULL
);
120 Returns a copy of the event.
122 Any event that is posted to the wxWidgets event system for later action
123 (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent())
124 must implement this method.
126 All wxWidgets events fully implement this method, but any derived events
127 implemented by the user should also implement this method just in case they
128 (or some event derived from them) are ever posted.
130 All wxWidgets events implement a copy constructor, so the easiest way of
131 implementing the Clone function is to implement a copy constructor for
132 a new event (call it MyEvent) and then define the Clone function like this:
135 wxEvent *Clone() const { return new MyEvent(*this); }
138 virtual wxEvent
* Clone() const = 0;
141 Returns the object (usually a window) associated with the event, if any.
143 wxObject
* GetEventObject() const;
146 Returns the identifier of the given event type, such as @c wxEVT_BUTTON.
148 wxEventType
GetEventType() const;
151 Returns a generic category for this event.
152 wxEvent implementation returns @c wxEVT_CATEGORY_UI by default.
154 This function is used to selectively process events in wxEventLoopBase::YieldFor.
156 virtual wxEventCategory
GetEventCategory() const;
159 Returns the identifier associated with this event, such as a button command id.
164 Return the user data associated with a dynamically connected event handler.
166 wxEvtHandler::Connect() and wxEvtHandler::Bind() allow associating
167 optional @c userData pointer with the handler and this method returns
168 the value of this pointer.
170 The returned pointer is owned by wxWidgets and must not be deleted.
174 wxObject
*GetEventUserData() const;
177 Returns @true if the event handler should be skipped, @false otherwise.
179 bool GetSkipped() const;
182 Gets the timestamp for the event. The timestamp is the time in milliseconds
183 since some fixed moment (not necessarily the standard Unix Epoch, so only
184 differences between the timestamps and not their absolute values usually make sense).
187 wxWidgets returns a non-NULL timestamp only for mouse and key events
188 (see wxMouseEvent and wxKeyEvent).
190 long GetTimestamp() const;
193 Returns @true if the event is or is derived from wxCommandEvent else it returns @false.
195 @note exists only for optimization purposes.
197 bool IsCommandEvent() const;
200 Sets the propagation level to the given value (for example returned from an
201 earlier call to wxEvent::StopPropagation).
203 void ResumePropagation(int propagationLevel
);
206 Sets the originating object.
208 void SetEventObject(wxObject
* object
);
213 void SetEventType(wxEventType type
);
216 Sets the identifier associated with this event, such as a button command id.
221 Sets the timestamp for the event.
223 void SetTimestamp(long timeStamp
= 0);
226 Test if this event should be propagated or not, i.e.\ if the propagation level
227 is currently greater than 0.
229 bool ShouldPropagate() const;
232 This method can be used inside an event handler to control whether further
233 event handlers bound to this event will be called after the current one returns.
235 Without Skip() (or equivalently if Skip(@false) is used), the event will not
236 be processed any more. If Skip(@true) is called, the event processing system
237 continues searching for a further handler function for this event, even though
238 it has been processed already in the current handler.
240 In general, it is recommended to skip all non-command events to allow the
241 default handling to take place. The command events are, however, normally not
242 skipped as usually a single command such as a button click or menu item
243 selection must only be processed by one handler.
245 void Skip(bool skip
= true);
248 Stop the event from propagating to its parent window.
250 Returns the old propagation level value which may be later passed to
251 ResumePropagation() to allow propagating the event again.
253 int StopPropagation();
257 Indicates how many levels the event can propagate.
259 This member is protected and should typically only be set in the constructors
260 of the derived classes. It may be temporarily changed by StopPropagation()
261 and ResumePropagation() and tested with ShouldPropagate().
263 The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default)
264 meaning that the event shouldn't be propagated at all or to
265 @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be
266 propagated as much as necessary.
268 Any positive number means that the event should be propagated but no more than
269 the given number of times. E.g. the propagation level may be set to 1 to
270 propagate the event to its parent only, but not to its grandparent.
272 int m_propagationLevel
;
280 @class wxEventBlocker
282 This class is a special event handler which allows to discard
283 any event (or a set of event types) directed to a specific window.
288 void MyWindow::DoSomething()
291 // block all events directed to this window while
292 // we do the 1000 FunctionWhichSendsEvents() calls
293 wxEventBlocker blocker(this);
295 for ( int i = 0; i 1000; i++ )
296 FunctionWhichSendsEvents(i);
298 } // ~wxEventBlocker called, old event handler is restored
300 // the event generated by this call will be processed:
301 FunctionWhichSendsEvents(0)
308 @see @ref overview_events_processing, wxEvtHandler
310 class wxEventBlocker
: public wxEvtHandler
314 Constructs the blocker for the given window and for the given event type.
316 If @a type is @c wxEVT_ANY, then all events for that window are blocked.
317 You can call Block() after creation to add other event types to the list
320 Note that the @a win window @b must remain alive until the
321 wxEventBlocker object destruction.
323 wxEventBlocker(wxWindow
* win
, wxEventType type
= -1);
326 Destructor. The blocker will remove itself from the chain of event handlers for
327 the window provided in the constructor, thus restoring normal processing of events.
329 virtual ~wxEventBlocker();
332 Adds to the list of event types which should be blocked the given @a eventType.
334 void Block(wxEventType eventType
);
340 Helper class to temporarily change an event to not propagate.
342 class wxPropagationDisabler
345 wxPropagationDisabler(wxEvent
& event
);
346 ~wxPropagationDisabler();
351 Helper class to temporarily lower propagation level.
353 class wxPropagateOnce
356 wxPropagateOnce(wxEvent
& event
);
367 A class that can handle events from the windowing system.
368 wxWindow is (and therefore all window classes are) derived from this class.
370 When events are received, wxEvtHandler invokes the method listed in the
371 event table using itself as the object. When using multiple inheritance
372 <b>it is imperative that the wxEvtHandler(-derived) class is the first
373 class inherited</b> such that the @c this pointer for the overall object
374 will be identical to the @c this pointer of the wxEvtHandler portion.
379 @see @ref overview_events_processing, wxEventBlocker, wxEventLoopBase
381 class wxEvtHandler
: public wxObject
, public wxTrackable
392 If the handler is part of a chain, the destructor will unlink itself
395 virtual ~wxEvtHandler();
399 @name Event queuing and processing
404 Queue event for a later processing.
406 This method is similar to ProcessEvent() but while the latter is
407 synchronous, i.e. the event is processed immediately, before the
408 function returns, this one is asynchronous and returns immediately
409 while the event will be processed at some later time (usually during
410 the next event loop iteration).
412 Another important difference is that this method takes ownership of the
413 @a event parameter, i.e. it will delete it itself. This implies that
414 the event should be allocated on the heap and that the pointer can't be
415 used any more after the function returns (as it can be deleted at any
418 QueueEvent() can be used for inter-thread communication from the worker
419 threads to the main thread, it is safe in the sense that it uses
420 locking internally and avoids the problem mentioned in AddPendingEvent()
421 documentation by ensuring that the @a event object is not used by the
422 calling thread any more. Care should still be taken to avoid that some
423 fields of this object are used by it, notably any wxString members of
424 the event object must not be shallow copies of another wxString object
425 as this would result in them still using the same string buffer behind
426 the scenes. For example:
428 void FunctionInAWorkerThread(const wxString& str)
430 wxCommandEvent* evt = new wxCommandEvent;
432 // NOT evt->SetString(str) as this would be a shallow copy
433 evt->SetString(str.c_str()); // make a deep copy
435 wxTheApp->QueueEvent( evt );
439 Note that you can use wxThreadEvent instead of wxCommandEvent
440 to avoid this problem:
442 void FunctionInAWorkerThread(const wxString& str)
447 // wxThreadEvent::Clone() makes sure that the internal wxString
448 // member is not shared by other wxString instances:
449 wxTheApp->QueueEvent( evt.Clone() );
453 Finally notice that this method automatically wakes up the event loop
454 if it is currently idle by calling ::wxWakeUpIdle() so there is no need
455 to do it manually when using it.
460 A heap-allocated event to be queued, QueueEvent() takes ownership
461 of it. This parameter shouldn't be @c NULL.
463 virtual void QueueEvent(wxEvent
*event
);
466 Post an event to be processed later.
468 This function is similar to QueueEvent() but can't be used to post
469 events from worker threads for the event objects with wxString fields
470 (i.e. in practice most of them) because of an unsafe use of the same
471 wxString object which happens because the wxString field in the
472 original @a event object and its copy made internally by this function
473 share the same string buffer internally. Use QueueEvent() to avoid
476 A copy of @a event is made by the function, so the original can be deleted
477 as soon as function returns (it is common that the original is created
478 on the stack). This requires that the wxEvent::Clone() method be
479 implemented by event so that it can be duplicated and stored until it
483 Event to add to the pending events queue.
485 virtual void AddPendingEvent(const wxEvent
& event
);
488 Asynchronously call the given method.
490 Calling this function on an object schedules an asynchronous call to
491 the method specified as CallAfter() argument at a (slightly) later
492 time. This is useful when processing some events as certain actions
493 typically can't be performed inside their handlers, e.g. you shouldn't
494 show a modal dialog from a mouse click event handler as this would
495 break the mouse capture state -- but you can call a method showing
496 this message dialog after the current event handler completes.
498 The method being called must be the method of the object on which
499 CallAfter() itself is called.
501 Notice that it is safe to use CallAfter() from other, non-GUI,
502 threads, but that the method will be always called in the main, GUI,
507 class MyFrame : public wxFrame {
508 void OnClick(wxMouseEvent& event) {
509 CallAfter(&MyFrame::ShowPosition, event.GetPosition());
512 void ShowPosition(const wxPoint& pos) {
514 wxString::Format("Perform click at (%d, %d)?",
515 pos.x, pos.y), "", wxYES_NO) == wxYES )
517 ... do take this click into account ...
523 @param method The method to call.
524 @param x1 The (optional) first parameter to pass to the method.
525 @param x2 The (optional) second parameter to pass to the method.
527 Note that currently only up to 2 arguments can be passed. For more
528 complicated needs, you can use the CallAfter<T>(const T& fn) overload
529 that can call any functor.
531 @note This method is not available with Visual C++ before version 8
532 (Visual Studio 2005) as earlier versions of the compiler don't
533 have the required support for C++ templates to implement it.
537 template<typename T
, typename T1
, ...>
538 void CallAfter(void (T::*method
)(T1
, ...), T1 x1
, ...);
541 Asynchronously call the given functor.
543 Calling this function on an object schedules an asynchronous call to
544 the functor specified as CallAfter() argument at a (slightly) later
545 time. This is useful when processing some events as certain actions
546 typically can't be performed inside their handlers, e.g. you shouldn't
547 show a modal dialog from a mouse click event handler as this would
548 break the mouse capture state -- but you can call a function showing
549 this message dialog after the current event handler completes.
551 Notice that it is safe to use CallAfter() from other, non-GUI,
552 threads, but that the method will be always called in the main, GUI,
555 This overload is particularly useful in combination with C++11 lambdas:
557 wxGetApp().CallAfter([]{
562 @param functor The functor to call.
564 @note This method is not available with Visual C++ before version 8
565 (Visual Studio 2005) as earlier versions of the compiler don't
566 have the required support for C++ templates to implement it.
571 void CallAfter(const T
& functor
);
574 Processes an event, searching event tables and calling zero or more suitable
575 event handler function(s).
577 Normally, your application would not call this function: it is called in the
578 wxWidgets implementation to dispatch incoming user interface events to the
579 framework (and application).
581 However, you might need to call it if implementing new functionality
582 (such as a new control) where you define new event types, as opposed to
583 allowing the user to override virtual functions.
585 Notice that you don't usually need to override ProcessEvent() to
586 customize the event handling, overriding the specially provided
587 TryBefore() and TryAfter() functions is usually enough. For example,
588 wxMDIParentFrame may override TryBefore() to ensure that the menu
589 events are processed in the active child frame before being processed
590 in the parent frame itself.
592 The normal order of event table searching is as follows:
593 -# wxApp::FilterEvent() is called. If it returns anything but @c -1
594 (default) the processing stops here.
595 -# TryBefore() is called (this is where wxValidator are taken into
596 account for wxWindow objects). If this returns @true, the function exits.
597 -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
598 the function skips to step (7).
599 -# Dynamic event table of the handlers bound using Bind<>() is
600 searched. If a handler is found, it is executed and the function
601 returns @true unless the handler used wxEvent::Skip() to indicate
602 that it didn't handle the event in which case the search continues.
603 -# Static events table of the handlers bound using event table
604 macros is searched for this event handler. If this fails, the base
605 class event table is tried, and so on until no more tables
606 exist or an appropriate function was found. If a handler is found,
607 the same logic as in the previous step applies.
608 -# The search is applied down the entire chain of event handlers (usually the
609 chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler():
610 @image html overview_events_chain.png
611 (referring to the image, if @c A->ProcessEvent is called and it doesn't handle
612 the event, @c B->ProcessEvent will be called and so on...).
613 Note that in the case of wxWindow you can build a stack of event handlers
614 (see wxWindow::PushEventHandler() for more info).
615 If any of the handlers of the chain return @true, the function exits.
616 -# TryAfter() is called: for the wxWindow object this may propagate the
617 event to the window parent (recursively). If the event is still not
618 processed, ProcessEvent() on wxTheApp object is called as the last
621 Notice that steps (2)-(6) are performed in ProcessEventLocally()
622 which is called by this function.
627 @true if a suitable event handler function was found and executed,
628 and the function did not call wxEvent::Skip.
630 @see SearchEventTable()
632 virtual bool ProcessEvent(wxEvent
& event
);
635 Try to process the event in this handler and all those chained to it.
637 As explained in ProcessEvent() documentation, the event handlers may be
638 chained in a doubly-linked list. This function tries to process the
639 event in this handler (including performing any pre-processing done in
640 TryBefore(), e.g. applying validators) and all those following it in
641 the chain until the event is processed or the chain is exhausted.
643 This function is called from ProcessEvent() and, in turn, calls
644 TryBefore() and TryAfter(). It is not virtual and so cannot be
645 overridden but can, and should, be called to forward an event to
646 another handler instead of ProcessEvent() which would result in a
647 duplicate call to TryAfter(), e.g. resulting in all unprocessed events
648 being sent to the application object multiple times.
655 @true if this handler of one of those chained to it processed the
658 bool ProcessEventLocally(wxEvent
& event
);
661 Processes an event by calling ProcessEvent() and handles any exceptions
662 that occur in the process.
663 If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
668 @return @true if the event was processed, @false if no handler was found
669 or an exception was thrown.
671 @see wxWindow::HandleWindowEvent
673 bool SafelyProcessEvent(wxEvent
& event
);
676 Processes the pending events previously queued using QueueEvent() or
677 AddPendingEvent(); you must call this function only if you are sure
678 there are pending events for this handler, otherwise a @c wxCHECK
681 The real processing still happens in ProcessEvent() which is called by this
684 Note that this function needs a valid application object (see
685 wxAppConsole::GetInstance()) because wxApp holds the list of the event
686 handlers with pending events and this function manipulates that list.
688 void ProcessPendingEvents();
691 Deletes all events queued on this event handler using QueueEvent() or
694 Use with care because the events which are deleted are (obviously) not
695 processed and this may have unwanted consequences (e.g. user actions events
698 void DeletePendingEvents();
701 Searches the event table, executing an event handler function if an appropriate
705 Event table to be searched.
707 Event to be matched against an event table entry.
709 @return @true if a suitable event handler function was found and
710 executed, and the function did not call wxEvent::Skip.
712 @remarks This function looks through the object's event table and tries
713 to find an entry that will match the event.
714 An entry will match if:
715 @li The event type matches, and
716 @li the identifier or identifier range matches, or the event table
717 entry's identifier is zero.
719 If a suitable function is called but calls wxEvent::Skip, this
720 function will fail, and searching will continue.
722 @todo this function in the header is listed as an "implementation only" function;
723 are we sure we want to document it?
727 virtual bool SearchEventTable(wxEventTable
& table
,
734 @name Connecting and disconnecting
739 Connects the given function dynamically with the event handler, id and
742 Notice that Bind() provides a more flexible and safer way to do the
743 same thing as Connect(), please use it in any new code -- while
744 Connect() is not formally deprecated due to its existing widespread
745 usage, it has no advantages compared to Bind().
747 This is an alternative to the use of static event tables. It is more
748 flexible as it allows to connect events generated by some object to an
749 event handler defined in a different object of a different class (which
750 is impossible to do directly with the event tables -- the events can be
751 only handled in another object if they are propagated upwards to it).
752 Do make sure to specify the correct @a eventSink when connecting to an
753 event of a different object.
755 See @ref overview_events_bind for more detailed explanation
756 of this function and the @ref page_samples_event sample for usage
759 This specific overload allows you to connect an event handler to a @e range
761 Do not confuse @e source IDs with event @e types: source IDs identify the
762 event generator objects (typically wxMenuItem or wxWindow objects) while the
763 event @e type identify which type of events should be handled by the
764 given @e function (an event generator object may generate many different
768 The first ID of the identifier range to be associated with the event
771 The last ID of the identifier range to be associated with the event
774 The event type to be associated with this event handler.
776 The event handler function. Note that this function should
777 be explicitly converted to the correct type which can be done using a macro
778 called @c wxFooEventHandler for the handler for any @c wxFooEvent.
780 Optional data to be associated with the event table entry.
781 wxWidgets will take ownership of this pointer, i.e. it will be
782 destroyed when the event handler is disconnected or at the program
783 termination. This pointer can be retrieved using
784 wxEvent::GetEventUserData() later.
786 Object whose member function should be called. It must be specified
787 when connecting an event generated by one object to a member
788 function of a different object. If it is omitted, @c this is used.
791 In wxPerl this function takes 4 arguments: @a id, @a lastid,
792 @a type, @a method; if @a method is undef, the handler is
798 void Connect(int id
, int lastId
, wxEventType eventType
,
799 wxObjectEventFunction function
,
800 wxObject
* userData
= NULL
,
801 wxEvtHandler
* eventSink
= NULL
);
804 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
805 overload for more info.
807 This overload can be used to attach an event handler to a single source ID:
811 frame->Connect( wxID_EXIT,
813 wxCommandEventHandler(MyFrame::OnQuit) );
817 Not supported by wxPerl.
820 void Connect(int id
, wxEventType eventType
,
821 wxObjectEventFunction function
,
822 wxObject
* userData
= NULL
,
823 wxEvtHandler
* eventSink
= NULL
);
826 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
827 overload for more info.
829 This overload will connect the given event handler so that regardless of the
830 ID of the event source, the handler will be called.
833 Not supported by wxPerl.
836 void Connect(wxEventType eventType
,
837 wxObjectEventFunction function
,
838 wxObject
* userData
= NULL
,
839 wxEvtHandler
* eventSink
= NULL
);
842 Disconnects the given function dynamically from the event handler, using the
843 specified parameters as search criteria and returning @true if a matching
844 function has been found and removed.
846 This method can only disconnect functions which have been added using the
847 Connect() method. There is no way to disconnect functions connected using
848 the (static) event tables.
851 The event type associated with this event handler.
853 The event handler function.
855 Data associated with the event table entry.
857 Object whose member function should be called.
860 Not supported by wxPerl.
863 bool Disconnect(wxEventType eventType
,
864 wxObjectEventFunction function
,
865 wxObject
* userData
= NULL
,
866 wxEvtHandler
* eventSink
= NULL
);
869 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
870 overload for more info.
872 This overload takes the additional @a id parameter.
875 Not supported by wxPerl.
878 bool Disconnect(int id
= wxID_ANY
,
879 wxEventType eventType
= wxEVT_NULL
,
880 wxObjectEventFunction function
= NULL
,
881 wxObject
* userData
= NULL
,
882 wxEvtHandler
* eventSink
= NULL
);
885 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
886 overload for more info.
888 This overload takes an additional range of source IDs.
891 In wxPerl this function takes 3 arguments: @a id,
895 bool Disconnect(int id
, int lastId
,
896 wxEventType eventType
,
897 wxObjectEventFunction function
= NULL
,
898 wxObject
* userData
= NULL
,
899 wxEvtHandler
* eventSink
= NULL
);
904 @name Binding and Unbinding
909 Binds the given function, functor or method dynamically with the event.
911 This offers basically the same functionality as Connect(), but it is
912 more flexible as it also allows you to use ordinary functions and
913 arbitrary functors as event handlers. It is also less restrictive then
914 Connect() because you can use an arbitrary method as an event handler,
915 whereas Connect() requires a wxEvtHandler derived handler.
917 See @ref overview_events_bind for more detailed explanation
918 of this function and the @ref page_samples_event sample for usage
922 The event type to be associated with this event handler.
924 The event handler functor. This can be an ordinary function but also
925 an arbitrary functor like boost::function<>.
927 The first ID of the identifier range to be associated with the event
930 The last ID of the identifier range to be associated with the event
933 Optional data to be associated with the event table entry.
934 wxWidgets will take ownership of this pointer, i.e. it will be
935 destroyed when the event handler is disconnected or at the program
936 termination. This pointer can be retrieved using
937 wxEvent::GetEventUserData() later.
939 @see @ref overview_cpp_rtti_disabled
943 template <typename EventTag
, typename Functor
>
944 void Bind(const EventTag
& eventType
,
947 int lastId
= wxID_ANY
,
948 wxObject
*userData
= NULL
);
951 See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for
954 This overload will bind the given method as the event handler.
957 The event type to be associated with this event handler.
959 The event handler method. This can be an arbitrary method (doesn't need
960 to be from a wxEvtHandler derived class).
962 Object whose method should be called. It must always be specified
963 so it can be checked at compile time whether the given method is an
964 actual member of the given handler.
966 The first ID of the identifier range to be associated with the event
969 The last ID of the identifier range to be associated with the event
972 Optional data to be associated with the event table entry.
973 wxWidgets will take ownership of this pointer, i.e. it will be
974 destroyed when the event handler is disconnected or at the program
975 termination. This pointer can be retrieved using
976 wxEvent::GetEventUserData() later.
978 @see @ref overview_cpp_rtti_disabled
982 template <typename EventTag
, typename Class
, typename EventArg
, typename EventHandler
>
983 void Bind(const EventTag
&eventType
,
984 void (Class::*method
)(EventArg
&),
985 EventHandler
*handler
,
987 int lastId
= wxID_ANY
,
988 wxObject
*userData
= NULL
);
990 Unbinds the given function, functor or method dynamically from the
991 event handler, using the specified parameters as search criteria and
992 returning @true if a matching function has been found and removed.
994 This method can only unbind functions, functors or methods which have
995 been added using the Bind<>() method. There is no way to unbind
996 functions bound using the (static) event tables.
999 The event type associated with this event handler.
1001 The event handler functor. This can be an ordinary function but also
1002 an arbitrary functor like boost::function<>.
1004 The first ID of the identifier range associated with the event
1007 The last ID of the identifier range associated with the event
1010 Data associated with the event table entry.
1012 @see @ref overview_cpp_rtti_disabled
1016 template <typename EventTag
, typename Functor
>
1017 bool Unbind(const EventTag
& eventType
,
1020 int lastId
= wxID_ANY
,
1021 wxObject
*userData
= NULL
);
1024 See the Unbind<>(const EventTag&, Functor, int, int, wxObject*)
1025 overload for more info.
1027 This overload unbinds the given method from the event..
1030 The event type associated with this event handler.
1032 The event handler method associated with this event.
1034 Object whose method was called.
1036 The first ID of the identifier range associated with the event
1039 The last ID of the identifier range associated with the event
1042 Data associated with the event table entry.
1044 @see @ref overview_cpp_rtti_disabled
1048 template <typename EventTag
, typename Class
, typename EventArg
, typename EventHandler
>
1049 bool Unbind(const EventTag
&eventType
,
1050 void (Class::*method
)(EventArg
&),
1051 EventHandler
*handler
,
1053 int lastId
= wxID_ANY
,
1054 wxObject
*userData
= NULL
);
1057 @name User-supplied data
1062 Returns user-supplied client data.
1064 @remarks Normally, any extra data the programmer wishes to associate with
1065 the object should be made available by deriving a new class with
1068 @see SetClientData()
1070 void* GetClientData() const;
1073 Returns a pointer to the user-supplied client data object.
1075 @see SetClientObject(), wxClientData
1077 wxClientData
* GetClientObject() const;
1080 Sets user-supplied client data.
1083 Data to be associated with the event handler.
1085 @remarks Normally, any extra data the programmer wishes to associate
1086 with the object should be made available by deriving a new
1087 class with new data members. You must not call this method
1088 and SetClientObject on the same class - only one of them.
1090 @see GetClientData()
1092 void SetClientData(void* data
);
1095 Set the client data object. Any previous object will be deleted.
1097 @see GetClientObject(), wxClientData
1099 void SetClientObject(wxClientData
* data
);
1105 @name Event handler chaining
1107 wxEvtHandler can be arranged in a double-linked list of handlers
1108 which is automatically iterated by ProcessEvent() if needed.
1113 Returns @true if the event handler is enabled, @false otherwise.
1115 @see SetEvtHandlerEnabled()
1117 bool GetEvtHandlerEnabled() const;
1120 Returns the pointer to the next handler in the chain.
1122 @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
1123 wxWindow::PushEventHandler, wxWindow::PopEventHandler
1125 wxEvtHandler
* GetNextHandler() const;
1128 Returns the pointer to the previous handler in the chain.
1130 @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
1131 wxWindow::PushEventHandler, wxWindow::PopEventHandler
1133 wxEvtHandler
* GetPreviousHandler() const;
1136 Enables or disables the event handler.
1139 @true if the event handler is to be enabled, @false if it is to be disabled.
1141 @remarks You can use this function to avoid having to remove the event
1142 handler from the chain, for example when implementing a
1143 dialog editor and changing from edit to test mode.
1145 @see GetEvtHandlerEnabled()
1147 void SetEvtHandlerEnabled(bool enabled
);
1150 Sets the pointer to the next handler.
1153 See ProcessEvent() for more info about how the chains of event handlers
1154 are internally used.
1155 Also remember that wxEvtHandler uses double-linked lists and thus if you
1156 use this function, you should also call SetPreviousHandler() on the
1157 argument passed to this function:
1159 handlerA->SetNextHandler(handlerB);
1160 handlerB->SetPreviousHandler(handlerA);
1164 The event handler to be set as the next handler.
1167 @see @ref overview_events_processing
1169 virtual void SetNextHandler(wxEvtHandler
* handler
);
1172 Sets the pointer to the previous handler.
1173 All remarks about SetNextHandler() apply to this function as well.
1176 The event handler to be set as the previous handler.
1179 @see @ref overview_events_processing
1181 virtual void SetPreviousHandler(wxEvtHandler
* handler
);
1184 Unlinks this event handler from the chain it's part of (if any);
1185 then links the "previous" event handler to the "next" one
1186 (so that the chain won't be interrupted).
1188 E.g. if before calling Unlink() you have the following chain:
1189 @image html evthandler_unlink_before.png
1190 then after calling @c B->Unlink() you'll have:
1191 @image html evthandler_unlink_after.png
1198 Returns @true if the next and the previous handler pointers of this
1199 event handler instance are @NULL.
1203 @see SetPreviousHandler(), SetNextHandler()
1205 bool IsUnlinked() const;
1210 @name Global event filters.
1212 Methods for working with the global list of event filters.
1214 Event filters can be defined to pre-process all the events that happen
1215 in an application, see wxEventFilter documentation for more information.
1220 Add an event filter whose FilterEvent() method will be called for each
1221 and every event processed by wxWidgets.
1223 The filters are called in LIFO order and wxApp is registered as an
1224 event filter by default. The pointer must remain valid until it's
1225 removed with RemoveFilter() and is not deleted by wxEvtHandler.
1229 static void AddFilter(wxEventFilter
* filter
);
1232 Remove a filter previously installed with AddFilter().
1234 It's an error to remove a filter that hadn't been previously added or
1235 was already removed.
1239 static void RemoveFilter(wxEventFilter
* filter
);
1245 Method called by ProcessEvent() before examining this object event
1248 This method can be overridden to hook into the event processing logic
1249 as early as possible. You should usually call the base class version
1250 when overriding this method, even if wxEvtHandler itself does nothing
1251 here, some derived classes do use this method, e.g. wxWindow implements
1252 support for wxValidator in it.
1256 class MyClass : public BaseClass // inheriting from wxEvtHandler
1260 virtual bool TryBefore(wxEvent& event)
1262 if ( MyPreProcess(event) )
1265 return BaseClass::TryBefore(event);
1272 virtual bool TryBefore(wxEvent
& event
);
1275 Method called by ProcessEvent() as last resort.
1277 This method can be overridden to implement post-processing for the
1278 events which were not processed anywhere else.
1280 The base class version handles forwarding the unprocessed events to
1281 wxApp at wxEvtHandler level and propagating them upwards the window
1282 child-parent chain at wxWindow level and so should usually be called
1283 when overriding this method:
1285 class MyClass : public BaseClass // inheriting from wxEvtHandler
1289 virtual bool TryAfter(wxEvent& event)
1291 if ( BaseClass::TryAfter(event) )
1294 return MyPostProcess(event);
1301 virtual bool TryAfter(wxEvent
& event
);
1304 #endif // wxUSE_BASE
1309 Flags for categories of keys.
1311 These values are used by wxKeyEvent::IsKeyInCategory(). They may be
1312 combined via the bitwise operators |, &, and ~.
1316 enum wxKeyCategoryFlags
1318 /// arrow keys, on and off numeric keypads
1321 /// page up and page down keys, on and off numeric keypads
1322 WXK_CATEGORY_PAGING
,
1324 /// home and end keys, on and off numeric keypads
1327 /// tab key, on and off numeric keypads
1330 /// backspace and delete keys, on and off numeric keypads
1333 /// union of WXK_CATEGORY_ARROW, WXK_CATEGORY_PAGING, and WXK_CATEGORY_JUMP categories
1334 WXK_CATEGORY_NAVIGATION
1341 This event class contains information about key press and release events.
1343 The main information carried by this event is the key being pressed or
1344 released. It can be accessed using either GetKeyCode() function or
1345 GetUnicodeKey(). For the printable characters, the latter should be used as
1346 it works for any keys, including non-Latin-1 characters that can be entered
1347 when using national keyboard layouts. GetKeyCode() should be used to handle
1348 special characters (such as cursor arrows keys or @c HOME or @c INS and so
1349 on) which correspond to ::wxKeyCode enum elements above the @c WXK_START
1350 constant. While GetKeyCode() also returns the character code for Latin-1
1351 keys for compatibility, it doesn't work for Unicode characters in general
1352 and will return @c WXK_NONE for any non-Latin-1 ones. For this reason, it's
1353 recommended to always use GetUnicodeKey() and only fall back to GetKeyCode()
1354 if GetUnicodeKey() returned @c WXK_NONE meaning that the event corresponds
1355 to a non-printable special keys.
1357 While both of these functions can be used with the events of @c
1358 wxEVT_KEY_DOWN, @c wxEVT_KEY_UP and @c wxEVT_CHAR types, the values
1359 returned by them are different for the first two events and the last one.
1360 For the latter, the key returned corresponds to the character that would
1361 appear in e.g. a text zone if the user pressed the key in it. As such, its
1362 value depends on the current state of the Shift key and, for the letters,
1363 on the state of Caps Lock modifier. For example, if @c A key is pressed
1364 without Shift being held down, wxKeyEvent of type @c wxEVT_CHAR generated
1365 for this key press will return (from either GetKeyCode() or GetUnicodeKey()
1366 as their meanings coincide for ASCII characters) key code of 97
1367 corresponding the ASCII value of @c a. And if the same key is pressed but
1368 with Shift being held (or Caps Lock being active), then the key could would
1369 be 65, i.e. ASCII value of capital @c A.
1371 However for the key down and up events the returned key code will instead
1372 be @c A independently of the state of the modifier keys i.e. it depends
1373 only on physical key being pressed and is not translated to its logical
1374 representation using the current keyboard state. Such untranslated key
1375 codes are defined as follows:
1376 - For the letters they correspond to the @e upper case value of the
1378 - For the other alphanumeric keys (e.g. @c 7 or @c +), the untranslated
1379 key code corresponds to the character produced by the key when it is
1380 pressed without Shift. E.g. in standard US keyboard layout the
1381 untranslated key code for the key @c =/+ in the upper right corner of
1382 the keyboard is 61 which is the ASCII value of @c =.
1383 - For the rest of the keys (i.e. special non-printable keys) it is the
1384 same as the normal key code as no translation is used anyhow.
1386 Notice that the first rule applies to all Unicode letters, not just the
1387 usual Latin-1 ones. However for non-Latin-1 letters only GetUnicodeKey()
1388 can be used to retrieve the key code as GetKeyCode() just returns @c
1389 WXK_NONE in this case.
1391 To summarize: you should handle @c wxEVT_CHAR if you need the translated
1392 key and @c wxEVT_KEY_DOWN if you only need the value of the key itself,
1393 independent of the current keyboard state.
1395 @note Not all key down events may be generated by the user. As an example,
1396 @c wxEVT_KEY_DOWN with @c = key code can be generated using the
1397 standard US keyboard layout but not using the German one because the @c
1398 = key corresponds to Shift-0 key combination in this layout and the key
1399 code for it is @c 0, not @c =. Because of this you should avoid
1400 requiring your users to type key events that might be impossible to
1401 enter on their keyboard.
1404 Another difference between key and char events is that another kind of
1405 translation is done for the latter ones when the Control key is pressed:
1406 char events for ASCII letters in this case carry codes corresponding to the
1407 ASCII value of Ctrl-Latter, i.e. 1 for Ctrl-A, 2 for Ctrl-B and so on until
1408 26 for Ctrl-Z. This is convenient for terminal-like applications and can be
1409 completely ignored by all the other ones (if you need to handle Ctrl-A it
1410 is probably a better idea to use the key event rather than the char one).
1411 Notice that currently no translation is done for the presses of @c [, @c
1412 \\, @c ], @c ^ and @c _ keys which might be mapped to ASCII values from 27
1414 Since version 2.9.2, the enum values @c WXK_CONTROL_A - @c WXK_CONTROL_Z
1415 can be used instead of the non-descriptive constant values 1-26.
1417 Finally, modifier keys only generate key events but no char events at all.
1418 The modifiers keys are @c WXK_SHIFT, @c WXK_CONTROL, @c WXK_ALT and various
1419 @c WXK_WINDOWS_XXX from ::wxKeyCode enum.
1421 Modifier keys events are special in one additional aspect: usually the
1422 keyboard state associated with a key press is well defined, e.g.
1423 wxKeyboardState::ShiftDown() returns @c true only if the Shift key was held
1424 pressed when the key that generated this event itself was pressed. There is
1425 an ambiguity for the key press events for Shift key itself however. By
1426 convention, it is considered to be already pressed when it is pressed and
1427 already released when it is released. In other words, @c wxEVT_KEY_DOWN
1428 event for the Shift key itself will have @c wxMOD_SHIFT in GetModifiers()
1429 and ShiftDown() will return true while the @c wxEVT_KEY_UP event for Shift
1430 itself will not have @c wxMOD_SHIFT in its modifiers and ShiftDown() will
1434 @b Tip: You may discover the key codes and modifiers generated by all the
1435 keys on your system interactively by running the @ref
1436 page_samples_keyboard wxWidgets sample and pressing some keys in it.
1438 @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
1439 does not call @c event.Skip() then the corresponding char event
1440 (@c EVT_CHAR) will not happen. This is by design and enables the
1441 programs that handle both types of events to avoid processing the
1442 same key twice. As a consequence, if you do not want to suppress the
1443 @c wxEVT_CHAR events for the keys you handle, always call @c
1444 event.Skip() in your @c wxEVT_KEY_DOWN handler. Not doing may also
1445 prevent accelerators defined using this key from working.
1447 @note If a key is maintained in a pressed state, you will typically get a
1448 lot of (automatically generated) key down events but only one key up
1449 one at the end when the key is released so it is wrong to assume that
1450 there is one up event corresponding to each down one.
1452 @note For Windows programmers: The key and char events in wxWidgets are
1453 similar to but slightly different from Windows @c WM_KEYDOWN and
1454 @c WM_CHAR events. In particular, Alt-x combination will generate a
1455 char event in wxWidgets (unless it is used as an accelerator) and
1456 almost all keys, including ones without ASCII equivalents, generate
1460 @beginEventTable{wxKeyEvent}
1461 @event{EVT_KEY_DOWN(func)}
1462 Process a @c wxEVT_KEY_DOWN event (any key has been pressed). If this
1463 event is handled and not skipped, @c wxEVT_CHAR will not be generated
1464 at all for this key press (but @c wxEVT_KEY_UP will be).
1465 @event{EVT_KEY_UP(func)}
1466 Process a @c wxEVT_KEY_UP event (any key has been released).
1467 @event{EVT_CHAR(func)}
1468 Process a @c wxEVT_CHAR event.
1469 @event{EVT_CHAR_HOOK(func)}
1470 Process a @c wxEVT_CHAR_HOOK event. Unlike all the other key events,
1471 this event is propagated upwards the window hierarchy which allows
1472 intercepting it in the parent window of the focused window to which it
1473 is sent initially (if there is no focused window, this event is sent to
1474 the wxApp global object). It is also generated before any other key
1475 events and so gives the parent window an opportunity to modify the
1476 keyboard handling of its children, e.g. it is used internally by
1477 wxWidgets in some ports to intercept pressing Esc key in any child of a
1478 dialog to close the dialog itself when it's pressed. By default, if
1479 this event is handled, i.e. the handler doesn't call wxEvent::Skip(),
1480 neither @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR events will be generated
1481 (although @c wxEVT_KEY_UP still will be), i.e. it replaces the normal
1482 key events. However by calling the special DoAllowNextEvent() method
1483 you can handle @c wxEVT_CHAR_HOOK and still allow normal events
1484 generation. This is something that is rarely useful but can be required
1485 if you need to prevent a parent @c wxEVT_CHAR_HOOK handler from running
1486 without suppressing the normal key events. Finally notice that this
1487 event is not generated when the mouse is captured as it is considered
1488 that the window which has the capture should receive all the keyboard
1489 events too without allowing its parent wxTopLevelWindow to interfere
1490 with their processing.
1493 @see wxKeyboardState
1498 class wxKeyEvent
: public wxEvent
,
1499 public wxKeyboardState
1504 Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
1506 wxKeyEvent(wxEventType keyEventType
= wxEVT_NULL
);
1509 Returns the key code of the key that generated this event.
1511 ASCII symbols return normal ASCII values, while events from special
1512 keys such as "left cursor arrow" (@c WXK_LEFT) return values outside of
1513 the ASCII range. See ::wxKeyCode for a full list of the virtual key
1516 Note that this method returns a meaningful value only for special
1517 non-alphanumeric keys or if the user entered a Latin-1 character (this
1518 includes ASCII and the accented letters found in Western European
1519 languages but not letters of other alphabets such as e.g. Cyrillic).
1520 Otherwise it simply method returns @c WXK_NONE and GetUnicodeKey()
1521 should be used to obtain the corresponding Unicode character.
1523 Using GetUnicodeKey() is in general the right thing to do if you are
1524 interested in the characters typed by the user, GetKeyCode() should be
1525 only used for special keys (for which GetUnicodeKey() returns @c
1526 WXK_NONE). To handle both kinds of keys you might write:
1528 void MyHandler::OnChar(wxKeyEvent& event)
1530 wxChar uc = event.GetUnicodeKey();
1531 if ( uc != WXK_NONE )
1533 // It's a "normal" character. Notice that this includes
1534 // control characters in 1..31 range, e.g. WXK_RETURN or
1535 // WXK_BACK, so check for them explicitly.
1538 wxLogMessage("You pressed '%c'", uc);
1542 // It's a control character
1546 else // No Unicode equivalent.
1548 // It's a special key, deal with all the known ones:
1549 switch ( event.GetKeyCode() )
1564 int GetKeyCode() const;
1567 Returns true if the key is in the given key category.
1570 A bitwise combination of named ::wxKeyCategoryFlags constants.
1574 bool IsKeyInCategory(int category
) const;
1578 Obtains the position (in client coordinates) at which the key was pressed.
1580 Notice that under most platforms this position is simply the current
1581 mouse pointer position and has no special relationship to the key event
1584 @a x and @a y may be @NULL if the corresponding coordinate is not
1587 wxPoint
GetPosition() const;
1588 void GetPosition(wxCoord
* x
, wxCoord
* y
) const;
1592 Returns the raw key code for this event.
1594 The flags are platform-dependent and should only be used if the
1595 functionality provided by other wxKeyEvent methods is insufficient.
1597 Under MSW, the raw key code is the value of @c wParam parameter of the
1598 corresponding message.
1600 Under GTK, the raw key code is the @c keyval field of the corresponding
1603 Under OS X, the raw key code is the @c keyCode field of the
1604 corresponding NSEvent.
1606 @note Currently the raw key codes are not supported by all ports, use
1607 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
1609 wxUint32
GetRawKeyCode() const;
1612 Returns the low level key flags for this event.
1614 The flags are platform-dependent and should only be used if the
1615 functionality provided by other wxKeyEvent methods is insufficient.
1617 Under MSW, the raw flags are just the value of @c lParam parameter of
1618 the corresponding message.
1620 Under GTK, the raw flags contain the @c hardware_keycode field of the
1621 corresponding GDK event.
1623 Under OS X, the raw flags contain the modifiers state.
1625 @note Currently the raw key flags are not supported by all ports, use
1626 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
1628 wxUint32
GetRawKeyFlags() const;
1631 Returns the Unicode character corresponding to this key event.
1633 If the key pressed doesn't have any character value (e.g. a cursor key)
1634 this method will return @c WXK_NONE. In this case you should use
1635 GetKeyCode() to retrieve the value of the key.
1637 This function is only available in Unicode build, i.e. when
1638 @c wxUSE_UNICODE is 1.
1640 wxChar
GetUnicodeKey() const;
1643 Returns the X position (in client coordinates) of the event.
1647 wxCoord
GetX() const;
1650 Returns the Y position (in client coordinates) of the event.
1654 wxCoord
GetY() const;
1657 Allow normal key events generation.
1659 Can be called from @c wxEVT_CHAR_HOOK handler to indicate that the
1660 generation of normal events should @em not be suppressed, as it happens
1661 by default when this event is handled.
1663 The intended use of this method is to allow some window object to
1664 prevent @c wxEVT_CHAR_HOOK handler in its parent window from running by
1665 defining its own handler for this event. Without calling this method,
1666 this would result in not generating @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR
1667 events at all but by calling it you can ensure that these events would
1668 still be generated, even if @c wxEVT_CHAR_HOOK event was handled.
1672 void DoAllowNextEvent();
1675 Returns @true if DoAllowNextEvent() had been called, @false by default.
1677 This method is used by wxWidgets itself to determine whether the normal
1678 key events should be generated after @c wxEVT_CHAR_HOOK processing.
1682 bool IsNextEventAllowed() const;
1693 // Which button is down?
1696 wxJOY_BUTTON_ANY
= -1,
1705 @class wxJoystickEvent
1707 This event class contains information about joystick events, particularly
1708 events received by windows.
1710 @beginEventTable{wxJoystickEvent}
1711 @event{EVT_JOY_BUTTON_DOWN(func)}
1712 Process a @c wxEVT_JOY_BUTTON_DOWN event.
1713 @event{EVT_JOY_BUTTON_UP(func)}
1714 Process a @c wxEVT_JOY_BUTTON_UP event.
1715 @event{EVT_JOY_MOVE(func)}
1716 Process a @c wxEVT_JOY_MOVE event.
1717 @event{EVT_JOY_ZMOVE(func)}
1718 Process a @c wxEVT_JOY_ZMOVE event.
1719 @event{EVT_JOYSTICK_EVENTS(func)}
1720 Processes all joystick events.
1728 class wxJoystickEvent
: public wxEvent
1734 wxJoystickEvent(wxEventType eventType
= wxEVT_NULL
, int state
= 0,
1735 int joystick
= wxJOYSTICK1
,
1739 Returns @true if the event was a down event from the specified button
1743 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1744 indicate any button down event.
1746 bool ButtonDown(int button
= wxJOY_BUTTON_ANY
) const;
1749 Returns @true if the specified button (or any button) was in a down state.
1752 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1753 indicate any button down event.
1755 bool ButtonIsDown(int button
= wxJOY_BUTTON_ANY
) const;
1758 Returns @true if the event was an up event from the specified button
1762 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1763 indicate any button down event.
1765 bool ButtonUp(int button
= wxJOY_BUTTON_ANY
) const;
1768 Returns the identifier of the button changing state.
1770 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
1772 int GetButtonChange() const;
1775 Returns the down state of the buttons.
1777 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
1779 int GetButtonState() const;
1782 Returns the identifier of the joystick generating the event - one of
1783 wxJOYSTICK1 and wxJOYSTICK2.
1785 int GetJoystick() const;
1788 Returns the x, y position of the joystick event.
1790 These coordinates are valid for all the events except wxEVT_JOY_ZMOVE.
1792 wxPoint
GetPosition() const;
1795 Returns the z position of the joystick event.
1797 This method can only be used for wxEVT_JOY_ZMOVE events.
1799 int GetZPosition() const;
1802 Returns @true if this was a button up or down event
1803 (@e not 'is any button down?').
1805 bool IsButton() const;
1808 Returns @true if this was an x, y move event.
1810 bool IsMove() const;
1813 Returns @true if this was a z move event.
1815 bool IsZMove() const;
1821 @class wxScrollWinEvent
1823 A scroll event holds information about events sent from scrolling windows.
1825 Note that you can use the EVT_SCROLLWIN* macros for intercepting scroll window events
1826 from the receiving window.
1828 @beginEventTable{wxScrollWinEvent}
1829 @event{EVT_SCROLLWIN(func)}
1830 Process all scroll events.
1831 @event{EVT_SCROLLWIN_TOP(func)}
1832 Process @c wxEVT_SCROLLWIN_TOP scroll-to-top events.
1833 @event{EVT_SCROLLWIN_BOTTOM(func)}
1834 Process @c wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
1835 @event{EVT_SCROLLWIN_LINEUP(func)}
1836 Process @c wxEVT_SCROLLWIN_LINEUP line up events.
1837 @event{EVT_SCROLLWIN_LINEDOWN(func)}
1838 Process @c wxEVT_SCROLLWIN_LINEDOWN line down events.
1839 @event{EVT_SCROLLWIN_PAGEUP(func)}
1840 Process @c wxEVT_SCROLLWIN_PAGEUP page up events.
1841 @event{EVT_SCROLLWIN_PAGEDOWN(func)}
1842 Process @c wxEVT_SCROLLWIN_PAGEDOWN page down events.
1843 @event{EVT_SCROLLWIN_THUMBTRACK(func)}
1844 Process @c wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
1845 (frequent events sent as the user drags the thumbtrack).
1846 @event{EVT_SCROLLWIN_THUMBRELEASE(func)}
1847 Process @c wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
1854 @see wxScrollEvent, @ref overview_events
1856 class wxScrollWinEvent
: public wxEvent
1862 wxScrollWinEvent(wxEventType commandType
= wxEVT_NULL
, int pos
= 0,
1863 int orientation
= 0);
1866 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
1869 @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
1871 int GetOrientation() const;
1874 Returns the position of the scrollbar for the thumb track and release events.
1876 Note that this field can't be used for the other events, you need to query
1877 the window itself for the current position in that case.
1879 int GetPosition() const;
1881 void SetOrientation(int orient
);
1882 void SetPosition(int pos
);
1888 @class wxSysColourChangedEvent
1890 This class is used for system colour change events, which are generated
1891 when the user changes the colour settings using the control panel.
1892 This is only appropriate under Windows.
1895 The default event handler for this event propagates the event to child windows,
1896 since Windows only sends the events to top-level windows.
1897 If intercepting this event for a top-level window, remember to call the base
1898 class handler, or to pass the event on to the window's children explicitly.
1900 @beginEventTable{wxSysColourChangedEvent}
1901 @event{EVT_SYS_COLOUR_CHANGED(func)}
1902 Process a @c wxEVT_SYS_COLOUR_CHANGED event.
1908 @see @ref overview_events
1910 class wxSysColourChangedEvent
: public wxEvent
1916 wxSysColourChangedEvent();
1922 @class wxCommandEvent
1924 This event class contains information about command events, which originate
1925 from a variety of simple controls.
1927 Note that wxCommandEvents and wxCommandEvent-derived event classes by default
1928 and unlike other wxEvent-derived classes propagate upward from the source
1929 window (the window which emits the event) up to the first parent which processes
1930 the event. Be sure to read @ref overview_events_propagation.
1932 More complex controls, such as wxTreeCtrl, have separate command event classes.
1934 @beginEventTable{wxCommandEvent}
1935 @event{EVT_COMMAND(id, event, func)}
1936 Process a command, supplying the window identifier, command event identifier,
1937 and member function.
1938 @event{EVT_COMMAND_RANGE(id1, id2, event, func)}
1939 Process a command for a range of window identifiers, supplying the minimum and
1940 maximum window identifiers, command event identifier, and member function.
1941 @event{EVT_BUTTON(id, func)}
1942 Process a @c wxEVT_BUTTON command, which is generated by a wxButton control.
1943 @event{EVT_CHECKBOX(id, func)}
1944 Process a @c wxEVT_CHECKBOX command, which is generated by a wxCheckBox control.
1945 @event{EVT_CHOICE(id, func)}
1946 Process a @c wxEVT_CHOICE command, which is generated by a wxChoice control.
1947 @event{EVT_COMBOBOX(id, func)}
1948 Process a @c wxEVT_COMBOBOX command, which is generated by a wxComboBox control.
1949 @event{EVT_LISTBOX(id, func)}
1950 Process a @c wxEVT_LISTBOX command, which is generated by a wxListBox control.
1951 @event{EVT_LISTBOX_DCLICK(id, func)}
1952 Process a @c wxEVT_LISTBOX_DCLICK command, which is generated by a wxListBox control.
1953 @event{EVT_CHECKLISTBOX(id, func)}
1954 Process a @c wxEVT_CHECKLISTBOX command, which is generated by a wxCheckListBox control.
1955 @event{EVT_MENU(id, func)}
1956 Process a @c wxEVT_MENU command, which is generated by a menu item.
1957 @event{EVT_MENU_RANGE(id1, id2, func)}
1958 Process a @c wxEVT_MENU command, which is generated by a range of menu items.
1959 @event{EVT_CONTEXT_MENU(func)}
1960 Process the event generated when the user has requested a popup menu to appear by
1961 pressing a special keyboard key (under Windows) or by right clicking the mouse.
1962 @event{EVT_RADIOBOX(id, func)}
1963 Process a @c wxEVT_RADIOBOX command, which is generated by a wxRadioBox control.
1964 @event{EVT_RADIOBUTTON(id, func)}
1965 Process a @c wxEVT_RADIOBUTTON command, which is generated by a wxRadioButton control.
1966 @event{EVT_SCROLLBAR(id, func)}
1967 Process a @c wxEVT_SCROLLBAR command, which is generated by a wxScrollBar
1968 control. This is provided for compatibility only; more specific scrollbar event macros
1969 should be used instead (see wxScrollEvent).
1970 @event{EVT_SLIDER(id, func)}
1971 Process a @c wxEVT_SLIDER command, which is generated by a wxSlider control.
1972 @event{EVT_TEXT(id, func)}
1973 Process a @c wxEVT_TEXT command, which is generated by a wxTextCtrl control.
1974 @event{EVT_TEXT_ENTER(id, func)}
1975 Process a @c wxEVT_TEXT_ENTER command, which is generated by a wxTextCtrl control.
1976 Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
1977 to generate such events.
1978 @event{EVT_TEXT_MAXLEN(id, func)}
1979 Process a @c wxEVT_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
1980 when the user tries to enter more characters into it than the limit previously set
1981 with SetMaxLength().
1982 @event{EVT_TOGGLEBUTTON(id, func)}
1983 Process a @c wxEVT_TOGGLEBUTTON event.
1984 @event{EVT_TOOL(id, func)}
1985 Process a @c wxEVT_TOOL event (a synonym for @c wxEVT_MENU).
1986 Pass the id of the tool.
1987 @event{EVT_TOOL_RANGE(id1, id2, func)}
1988 Process a @c wxEVT_TOOL event for a range of identifiers. Pass the ids of the tools.
1989 @event{EVT_TOOL_RCLICKED(id, func)}
1990 Process a @c wxEVT_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.)
1991 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
1992 Process a @c wxEVT_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.)
1993 @event{EVT_TOOL_ENTER(id, func)}
1994 Process a @c wxEVT_TOOL_ENTER event. Pass the id of the toolbar itself.
1995 The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
1996 has moved off a tool. (Not available on wxOSX.)
1997 @event{EVT_COMMAND_LEFT_CLICK(id, func)}
1998 Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
1999 @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
2000 Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
2001 @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
2002 Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
2003 @event{EVT_COMMAND_SET_FOCUS(id, func)}
2004 Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
2005 @event{EVT_COMMAND_KILL_FOCUS(id, func)}
2006 Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
2007 @event{EVT_COMMAND_ENTER(id, func)}
2008 Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
2014 class wxCommandEvent
: public wxEvent
2020 wxCommandEvent(wxEventType commandEventType
= wxEVT_NULL
, int id
= 0);
2023 Returns client data pointer for a listbox or choice selection event
2024 (not valid for a deselection).
2026 void* GetClientData() const;
2029 Returns client object pointer for a listbox or choice selection event
2030 (not valid for a deselection).
2032 wxClientData
* GetClientObject() const;
2035 Returns extra information dependent on the event objects type.
2037 If the event comes from a listbox selection, it is a boolean
2038 determining whether the event was a selection (@true) or a
2039 deselection (@false). A listbox deselection only occurs for
2040 multiple-selection boxes, and in this case the index and string values
2041 are indeterminate and the listbox must be examined by the application.
2043 long GetExtraLong() const;
2046 Returns the integer identifier corresponding to a listbox, choice or
2047 radiobox selection (only if the event was a selection, not a deselection),
2048 or a boolean value representing the value of a checkbox.
2050 For a menu item, this method returns -1 if the item is not checkable or
2051 a boolean value (true or false) for checkable items indicating the new
2057 Returns item index for a listbox or choice selection event (not valid for
2060 int GetSelection() const;
2063 Returns item string for a listbox or choice selection event. If one
2064 or several items have been deselected, returns the index of the first
2065 deselected item. If some items have been selected and others deselected
2066 at the same time, it will return the index of the first selected item.
2068 wxString
GetString() const;
2071 This method can be used with checkbox and menu events: for the checkboxes, the
2072 method returns @true for a selection event and @false for a deselection one.
2073 For the menu events, this method indicates if the menu item just has become
2074 checked or unchecked (and thus only makes sense for checkable menu items).
2076 Notice that this method cannot be used with wxCheckListBox currently.
2078 bool IsChecked() const;
2081 For a listbox or similar event, returns @true if it is a selection, @false
2082 if it is a deselection. If some items have been selected and others deselected
2083 at the same time, it will return @true.
2085 bool IsSelection() const;
2088 Sets the client data for this event.
2090 void SetClientData(void* clientData
);
2093 Sets the client object for this event. The client object is not owned by the
2094 event object and the event object will not delete the client object in its destructor.
2096 The client object must be owned and deleted by another object (e.g. a control)
2097 that has longer life time than the event object.
2099 void SetClientObject(wxClientData
* clientObject
);
2102 Sets the @b m_extraLong member.
2104 void SetExtraLong(long extraLong
);
2107 Sets the @b m_commandInt member.
2109 void SetInt(int intCommand
);
2112 Sets the @b m_commandString member.
2114 void SetString(const wxString
& string
);
2120 @class wxWindowCreateEvent
2122 This event is sent just after the actual window associated with a wxWindow
2123 object has been created.
2125 Since it is derived from wxCommandEvent, the event propagates up
2126 the window hierarchy.
2128 @beginEventTable{wxWindowCreateEvent}
2129 @event{EVT_WINDOW_CREATE(func)}
2130 Process a @c wxEVT_CREATE event.
2136 @see @ref overview_events, wxWindowDestroyEvent
2138 class wxWindowCreateEvent
: public wxCommandEvent
2144 wxWindowCreateEvent(wxWindow
* win
= NULL
);
2146 /// Return the window being created.
2147 wxWindow
*GetWindow() const;
2155 A paint event is sent when a window's contents needs to be repainted.
2157 The handler of this event must create a wxPaintDC object and use it for
2158 painting the window contents. For example:
2160 void MyWindow::OnPaint(wxPaintEvent& event)
2168 Notice that you must @e not create other kinds of wxDC (e.g. wxClientDC or
2169 wxWindowDC) in EVT_PAINT handlers and also don't create wxPaintDC outside
2170 of this event handlers.
2173 You can optimize painting by retrieving the rectangles that have been damaged
2174 and only repainting these. The rectangles are in terms of the client area,
2175 and are unscrolled, so you will need to do some calculations using the current
2176 view position to obtain logical, scrolled units.
2177 Here is an example of using the wxRegionIterator class:
2179 // Called when window needs to be repainted.
2180 void MyWindow::OnPaint(wxPaintEvent& event)
2184 // Find Out where the window is scrolled to
2185 int vbX,vbY; // Top left corner of client
2186 GetViewStart(&vbX,&vbY);
2188 int vX,vY,vW,vH; // Dimensions of client area in pixels
2189 wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
2198 // Alternatively we can do this:
2199 // wxRect rect(upd.GetRect());
2201 // Repaint this rectangle
2210 Please notice that in general it is impossible to change the drawing of a
2211 standard control (such as wxButton) and so you shouldn't attempt to handle
2212 paint events for them as even if it might work on some platforms, this is
2213 inherently not portable and won't work everywhere.
2216 @beginEventTable{wxPaintEvent}
2217 @event{EVT_PAINT(func)}
2218 Process a @c wxEVT_PAINT event.
2224 @see @ref overview_events
2226 class wxPaintEvent
: public wxEvent
2232 wxPaintEvent(int id
= 0);
2238 @class wxMaximizeEvent
2240 An event being sent when a top level window is maximized. Notice that it is
2241 not sent when the window is restored to its original size after it had been
2242 maximized, only a normal wxSizeEvent is generated in this case.
2244 Currently this event is only generated in wxMSW, wxGTK, wxOSX/Cocoa and wxOS2
2245 ports so portable programs should only rely on receiving @c wxEVT_SIZE and
2246 not necessarily this event when the window is maximized.
2248 @beginEventTable{wxMaximizeEvent}
2249 @event{EVT_MAXIMIZE(func)}
2250 Process a @c wxEVT_MAXIMIZE event.
2256 @see @ref overview_events, wxTopLevelWindow::Maximize,
2257 wxTopLevelWindow::IsMaximized
2259 class wxMaximizeEvent
: public wxEvent
2263 Constructor. Only used by wxWidgets internally.
2265 wxMaximizeEvent(int id
= 0);
2269 The possibles modes to pass to wxUpdateUIEvent::SetMode().
2273 /** Send UI update events to all windows. */
2274 wxUPDATE_UI_PROCESS_ALL
,
2276 /** Send UI update events to windows that have
2277 the wxWS_EX_PROCESS_UI_UPDATES flag specified. */
2278 wxUPDATE_UI_PROCESS_SPECIFIED
2283 @class wxUpdateUIEvent
2285 This class is used for pseudo-events which are called by wxWidgets
2286 to give an application the chance to update various user interface elements.
2288 Without update UI events, an application has to work hard to check/uncheck,
2289 enable/disable, show/hide, and set the text for elements such as menu items
2290 and toolbar buttons. The code for doing this has to be mixed up with the code
2291 that is invoked when an action is invoked for a menu item or button.
2293 With update UI events, you define an event handler to look at the state of the
2294 application and change UI elements accordingly. wxWidgets will call your member
2295 functions in idle time, so you don't have to worry where to call this code.
2297 In addition to being a clearer and more declarative method, it also means you don't
2298 have to worry whether you're updating a toolbar or menubar identifier. The same
2299 handler can update a menu item and toolbar button, if the identifier is the same.
2300 Instead of directly manipulating the menu or button, you call functions in the event
2301 object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a
2302 call has been made, and which UI element to update.
2304 These events will work for popup menus as well as menubars. Just before a menu is
2305 popped up, wxMenu::UpdateUI is called to process any UI events for the window that
2308 If you find that the overhead of UI update processing is affecting your application,
2309 you can do one or both of the following:
2310 @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED,
2311 and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should
2312 receive update events. No other windows will receive update events.
2313 @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay
2314 between updates. You may need to call wxWindow::UpdateWindowUI at critical points,
2315 for example when a dialog is about to be shown, in case the user sees a slight
2316 delay before windows are updated.
2318 Note that although events are sent in idle time, defining a wxIdleEvent handler
2319 for a window does not affect this because the events are sent from wxWindow::OnInternalIdle
2320 which is always called in idle time.
2322 wxWidgets tries to optimize update events on some platforms.
2323 On Windows and GTK+, events for menubar items are only sent when the menu is about
2324 to be shown, and not in idle time.
2327 @beginEventTable{wxUpdateUIEvent}
2328 @event{EVT_UPDATE_UI(id, func)}
2329 Process a @c wxEVT_UPDATE_UI event for the command with the given id.
2330 @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}
2331 Process a @c wxEVT_UPDATE_UI event for any command with id included in the given range.
2337 @see @ref overview_events
2339 class wxUpdateUIEvent
: public wxCommandEvent
2345 wxUpdateUIEvent(wxWindowID commandId
= 0);
2348 Returns @true if it is appropriate to update (send UI update events to)
2351 This function looks at the mode used (see wxUpdateUIEvent::SetMode),
2352 the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events
2353 were last sent in idle time, and the update interval, to determine whether
2354 events should be sent to this window now. By default this will always
2355 return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL
2356 and the interval is set to 0; so update events will be sent as often as
2357 possible. You can reduce the frequency that events are sent by changing the
2358 mode and/or setting an update interval.
2360 @see ResetUpdateTime(), SetUpdateInterval(), SetMode()
2362 static bool CanUpdate(wxWindow
* window
);
2365 Check or uncheck the UI element.
2367 void Check(bool check
);
2370 Enable or disable the UI element.
2372 void Enable(bool enable
);
2375 Returns @true if the UI element should be checked.
2377 bool GetChecked() const;
2380 Returns @true if the UI element should be enabled.
2382 bool GetEnabled() const;
2385 Static function returning a value specifying how wxWidgets will send update
2386 events: to all windows, or only to those which specify that they will process
2391 static wxUpdateUIMode
GetMode();
2394 Returns @true if the application has called Check().
2395 For wxWidgets internal use only.
2397 bool GetSetChecked() const;
2400 Returns @true if the application has called Enable().
2401 For wxWidgets internal use only.
2403 bool GetSetEnabled() const;
2406 Returns @true if the application has called Show().
2407 For wxWidgets internal use only.
2409 bool GetSetShown() const;
2412 Returns @true if the application has called SetText().
2413 For wxWidgets internal use only.
2415 bool GetSetText() const;
2418 Returns @true if the UI element should be shown.
2420 bool GetShown() const;
2423 Returns the text that should be set for the UI element.
2425 wxString
GetText() const;
2428 Returns the current interval between updates in milliseconds.
2429 The value -1 disables updates, 0 updates as frequently as possible.
2431 @see SetUpdateInterval().
2433 static long GetUpdateInterval();
2436 Used internally to reset the last-updated time to the current time.
2438 It is assumed that update events are normally sent in idle time, so this
2439 is called at the end of idle processing.
2441 @see CanUpdate(), SetUpdateInterval(), SetMode()
2443 static void ResetUpdateTime();
2446 Specify how wxWidgets will send update events: to all windows, or only to
2447 those which specify that they will process the events.
2450 this parameter may be one of the ::wxUpdateUIMode enumeration values.
2451 The default mode is wxUPDATE_UI_PROCESS_ALL.
2453 static void SetMode(wxUpdateUIMode mode
);
2456 Sets the text for this UI element.
2458 void SetText(const wxString
& text
);
2461 Sets the interval between updates in milliseconds.
2463 Set to -1 to disable updates, or to 0 to update as frequently as possible.
2466 Use this to reduce the overhead of UI update events if your application
2467 has a lot of windows. If you set the value to -1 or greater than 0,
2468 you may also need to call wxWindow::UpdateWindowUI at appropriate points
2469 in your application, such as when a dialog is about to be shown.
2471 static void SetUpdateInterval(long updateInterval
);
2474 Show or hide the UI element.
2476 void Show(bool show
);
2482 @class wxClipboardTextEvent
2484 This class represents the events generated by a control (typically a
2485 wxTextCtrl but other windows can generate these events as well) when its
2486 content gets copied or cut to, or pasted from the clipboard.
2488 There are three types of corresponding events @c wxEVT_TEXT_COPY,
2489 @c wxEVT_TEXT_CUT and @c wxEVT_TEXT_PASTE.
2491 If any of these events is processed (without being skipped) by an event
2492 handler, the corresponding operation doesn't take place which allows to
2493 prevent the text from being copied from or pasted to a control. It is also
2494 possible to examine the clipboard contents in the PASTE event handler and
2495 transform it in some way before inserting in a control -- for example,
2496 changing its case or removing invalid characters.
2498 Finally notice that a CUT event is always preceded by the COPY event which
2499 makes it possible to only process the latter if it doesn't matter if the
2500 text was copied or cut.
2503 These events are currently only generated by wxTextCtrl in wxGTK and wxOSX
2504 but are also generated by wxComboBox without wxCB_READONLY style in wxMSW.
2506 @beginEventTable{wxClipboardTextEvent}
2507 @event{EVT_TEXT_COPY(id, func)}
2508 Some or all of the controls content was copied to the clipboard.
2509 @event{EVT_TEXT_CUT(id, func)}
2510 Some or all of the controls content was cut (i.e. copied and
2512 @event{EVT_TEXT_PASTE(id, func)}
2513 Clipboard content was pasted into the control.
2522 class wxClipboardTextEvent
: public wxCommandEvent
2528 wxClipboardTextEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
2532 Possible axis values for mouse wheel scroll events.
2536 enum wxMouseWheelAxis
2538 wxMOUSE_WHEEL_VERTICAL
, ///< Vertical scroll event.
2539 wxMOUSE_WHEEL_HORIZONTAL
///< Horizontal scroll event.
2546 This event class contains information about the events generated by the mouse:
2547 they include mouse buttons press and release events and mouse move events.
2549 All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the
2550 left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and
2551 @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more
2552 buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events
2553 can also be generated. Note that not all mice have even a middle button so a
2554 portable application should avoid relying on the events from it (but the right
2555 button click can be emulated using the left mouse button with the control key
2556 under Mac platforms with a single button mouse).
2558 For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events
2559 purposes, the mouse is considered to be inside the window if it is in the
2560 window client area and not inside one of its children. In other words, the
2561 parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
2562 mouse leaves the window entirely but also when it enters one of its children.
2564 The position associated with a mouse event is expressed in the window
2565 coordinates of the window which generated the event, you can use
2566 wxWindow::ClientToScreen() to convert it to screen coordinates and possibly
2567 call wxWindow::ScreenToClient() next to convert it to window coordinates of
2570 @note Note that under Windows CE mouse enter and leave events are not natively
2571 supported by the system but are generated by wxWidgets itself. This has several
2572 drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
2573 left the window and the state variables for it may have changed during this time.
2575 @note Note the difference between methods like wxMouseEvent::LeftDown and
2576 the inherited wxMouseState::LeftIsDown: the former returns @true when
2577 the event corresponds to the left mouse button click while the latter
2578 returns @true if the left mouse button is currently being pressed.
2579 For example, when the user is dragging the mouse you can use
2580 wxMouseEvent::LeftIsDown to test whether the left mouse button is
2581 (still) depressed. Also, by convention, if wxMouseEvent::LeftDown
2582 returns @true, wxMouseEvent::LeftIsDown will also return @true in
2583 wxWidgets whatever the underlying GUI behaviour is (which is
2584 platform-dependent). The same applies, of course, to other mouse
2588 @beginEventTable{wxMouseEvent}
2589 @event{EVT_LEFT_DOWN(func)}
2590 Process a @c wxEVT_LEFT_DOWN event. The handler of this event should normally
2591 call event.Skip() to allow the default processing to take place as otherwise
2592 the window under mouse wouldn't get the focus.
2593 @event{EVT_LEFT_UP(func)}
2594 Process a @c wxEVT_LEFT_UP event.
2595 @event{EVT_LEFT_DCLICK(func)}
2596 Process a @c wxEVT_LEFT_DCLICK event.
2597 @event{EVT_MIDDLE_DOWN(func)}
2598 Process a @c wxEVT_MIDDLE_DOWN event.
2599 @event{EVT_MIDDLE_UP(func)}
2600 Process a @c wxEVT_MIDDLE_UP event.
2601 @event{EVT_MIDDLE_DCLICK(func)}
2602 Process a @c wxEVT_MIDDLE_DCLICK event.
2603 @event{EVT_RIGHT_DOWN(func)}
2604 Process a @c wxEVT_RIGHT_DOWN event.
2605 @event{EVT_RIGHT_UP(func)}
2606 Process a @c wxEVT_RIGHT_UP event.
2607 @event{EVT_RIGHT_DCLICK(func)}
2608 Process a @c wxEVT_RIGHT_DCLICK event.
2609 @event{EVT_MOUSE_AUX1_DOWN(func)}
2610 Process a @c wxEVT_AUX1_DOWN event.
2611 @event{EVT_MOUSE_AUX1_UP(func)}
2612 Process a @c wxEVT_AUX1_UP event.
2613 @event{EVT_MOUSE_AUX1_DCLICK(func)}
2614 Process a @c wxEVT_AUX1_DCLICK event.
2615 @event{EVT_MOUSE_AUX2_DOWN(func)}
2616 Process a @c wxEVT_AUX2_DOWN event.
2617 @event{EVT_MOUSE_AUX2_UP(func)}
2618 Process a @c wxEVT_AUX2_UP event.
2619 @event{EVT_MOUSE_AUX2_DCLICK(func)}
2620 Process a @c wxEVT_AUX2_DCLICK event.
2621 @event{EVT_MOTION(func)}
2622 Process a @c wxEVT_MOTION event.
2623 @event{EVT_ENTER_WINDOW(func)}
2624 Process a @c wxEVT_ENTER_WINDOW event.
2625 @event{EVT_LEAVE_WINDOW(func)}
2626 Process a @c wxEVT_LEAVE_WINDOW event.
2627 @event{EVT_MOUSEWHEEL(func)}
2628 Process a @c wxEVT_MOUSEWHEEL event.
2629 @event{EVT_MOUSE_EVENTS(func)}
2630 Process all mouse events.
2638 class wxMouseEvent
: public wxEvent
,
2643 Constructor. Valid event types are:
2645 @li @c wxEVT_ENTER_WINDOW
2646 @li @c wxEVT_LEAVE_WINDOW
2647 @li @c wxEVT_LEFT_DOWN
2648 @li @c wxEVT_LEFT_UP
2649 @li @c wxEVT_LEFT_DCLICK
2650 @li @c wxEVT_MIDDLE_DOWN
2651 @li @c wxEVT_MIDDLE_UP
2652 @li @c wxEVT_MIDDLE_DCLICK
2653 @li @c wxEVT_RIGHT_DOWN
2654 @li @c wxEVT_RIGHT_UP
2655 @li @c wxEVT_RIGHT_DCLICK
2656 @li @c wxEVT_AUX1_DOWN
2657 @li @c wxEVT_AUX1_UP
2658 @li @c wxEVT_AUX1_DCLICK
2659 @li @c wxEVT_AUX2_DOWN
2660 @li @c wxEVT_AUX2_UP
2661 @li @c wxEVT_AUX2_DCLICK
2663 @li @c wxEVT_MOUSEWHEEL
2665 wxMouseEvent(wxEventType mouseEventType
= wxEVT_NULL
);
2668 Returns @true if the event was a first extra button double click.
2670 bool Aux1DClick() const;
2673 Returns @true if the first extra button mouse button changed to down.
2675 bool Aux1Down() const;
2678 Returns @true if the first extra button mouse button changed to up.
2680 bool Aux1Up() const;
2683 Returns @true if the event was a second extra button double click.
2685 bool Aux2DClick() const;
2688 Returns @true if the second extra button mouse button changed to down.
2690 bool Aux2Down() const;
2693 Returns @true if the second extra button mouse button changed to up.
2695 bool Aux2Up() const;
2698 Returns @true if the event was generated by the specified button.
2700 @see wxMouseState::ButtoinIsDown()
2702 bool Button(wxMouseButton but
) const;
2705 If the argument is omitted, this returns @true if the event was a mouse
2706 double click event. Otherwise the argument specifies which double click event
2707 was generated (see Button() for the possible values).
2709 bool ButtonDClick(wxMouseButton but
= wxMOUSE_BTN_ANY
) const;
2712 If the argument is omitted, this returns @true if the event was a mouse
2713 button down event. Otherwise the argument specifies which button-down event
2714 was generated (see Button() for the possible values).
2716 bool ButtonDown(wxMouseButton but
= wxMOUSE_BTN_ANY
) const;
2719 If the argument is omitted, this returns @true if the event was a mouse
2720 button up event. Otherwise the argument specifies which button-up event
2721 was generated (see Button() for the possible values).
2723 bool ButtonUp(wxMouseButton but
= wxMOUSE_BTN_ANY
) const;
2726 Returns @true if this was a dragging event (motion while a button is depressed).
2730 bool Dragging() const;
2733 Returns @true if the mouse was entering the window.
2737 bool Entering() const;
2740 Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE
2741 if no button is involved (for mouse move, enter or leave event, for example).
2742 Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and
2743 double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT
2744 for the same events for the middle and the right buttons respectively.
2746 int GetButton() const;
2749 Returns the number of mouse clicks for this event: 1 for a simple click, 2
2750 for a double-click, 3 for a triple-click and so on.
2752 Currently this function is implemented only in wxMac and returns -1 for the
2753 other platforms (you can still distinguish simple clicks from double-clicks as
2754 they generate different kinds of events however).
2758 int GetClickCount() const;
2761 Returns the configured number of lines (or whatever) to be scrolled per
2764 Default value under most platforms is three.
2766 @see GetColumnsPerAction()
2768 int GetLinesPerAction() const;
2771 Returns the configured number of columns (or whatever) to be scrolled per
2774 Default value under most platforms is three.
2776 @see GetLinesPerAction()
2780 int GetColumnsPerAction() const;
2783 Returns the logical mouse position in pixels (i.e.\ translated according to the
2784 translation set for the DC, which usually indicates that the window has been
2787 wxPoint
GetLogicalPosition(const wxDC
& dc
) const;
2790 Get wheel delta, normally 120.
2792 This is the threshold for action to be taken, and one such action
2793 (for example, scrolling one increment) should occur for each delta.
2795 int GetWheelDelta() const;
2798 Get wheel rotation, positive or negative indicates direction of rotation.
2800 Current devices all send an event when rotation is at least +/-WheelDelta, but
2801 finer resolution devices can be created in the future.
2803 Because of this you shouldn't assume that one event is equal to 1 line, but you
2804 should be able to either do partial line scrolling or wait until several
2805 events accumulate before scrolling.
2807 int GetWheelRotation() const;
2810 Gets the axis the wheel operation concerns.
2812 Usually the mouse wheel is used to scroll vertically so @c
2813 wxMOUSE_WHEEL_VERTICAL is returned but some mice (and most trackpads)
2814 also allow to use the wheel to scroll horizontally in which case
2815 @c wxMOUSE_WHEEL_HORIZONTAL is returned.
2817 Notice that before wxWidgets 2.9.4 this method returned @c int.
2819 wxMouseWheelAxis
GetWheelAxis() const;
2822 Returns @true if the event was a mouse button event (not necessarily a button
2823 down event - that may be tested using ButtonDown()).
2825 bool IsButton() const;
2828 Returns @true if the system has been setup to do page scrolling with
2829 the mouse wheel instead of line scrolling.
2831 bool IsPageScroll() const;
2834 Returns @true if the mouse was leaving the window.
2838 bool Leaving() const;
2841 Returns @true if the event was a left double click.
2843 bool LeftDClick() const;
2846 Returns @true if the left mouse button changed to down.
2848 bool LeftDown() const;
2851 Returns @true if the left mouse button changed to up.
2853 bool LeftUp() const;
2856 Returns @true if the Meta key was down at the time of the event.
2858 bool MetaDown() const;
2861 Returns @true if the event was a middle double click.
2863 bool MiddleDClick() const;
2866 Returns @true if the middle mouse button changed to down.
2868 bool MiddleDown() const;
2871 Returns @true if the middle mouse button changed to up.
2873 bool MiddleUp() const;
2876 Returns @true if this was a motion event and no mouse buttons were pressed.
2877 If any mouse button is held pressed, then this method returns @false and
2878 Dragging() returns @true.
2880 bool Moving() const;
2883 Returns @true if the event was a right double click.
2885 bool RightDClick() const;
2888 Returns @true if the right mouse button changed to down.
2890 bool RightDown() const;
2893 Returns @true if the right mouse button changed to up.
2895 bool RightUp() const;
2901 @class wxDropFilesEvent
2903 This class is used for drop files events, that is, when files have been dropped
2904 onto the window. This functionality is currently only available under Windows.
2906 The window must have previously been enabled for dropping by calling
2907 wxWindow::DragAcceptFiles().
2909 Important note: this is a separate implementation to the more general drag and drop
2910 implementation documented in the @ref overview_dnd. It uses the older, Windows
2911 message-based approach of dropping files.
2913 @beginEventTable{wxDropFilesEvent}
2914 @event{EVT_DROP_FILES(func)}
2915 Process a @c wxEVT_DROP_FILES event.
2923 @see @ref overview_events
2925 class wxDropFilesEvent
: public wxEvent
2931 wxDropFilesEvent(wxEventType id
= 0, int noFiles
= 0,
2932 wxString
* files
= NULL
);
2935 Returns an array of filenames.
2937 wxString
* GetFiles() const;
2940 Returns the number of files dropped.
2942 int GetNumberOfFiles() const;
2945 Returns the position at which the files were dropped.
2946 Returns an array of filenames.
2948 wxPoint
GetPosition() const;
2954 @class wxActivateEvent
2956 An activate event is sent when a window or application is being activated
2959 @beginEventTable{wxActivateEvent}
2960 @event{EVT_ACTIVATE(func)}
2961 Process a @c wxEVT_ACTIVATE event.
2962 @event{EVT_ACTIVATE_APP(func)}
2963 Process a @c wxEVT_ACTIVATE_APP event.
2964 This event is received by the wxApp-derived instance only.
2965 @event{EVT_HIBERNATE(func)}
2966 Process a hibernate event, supplying the member function. This event applies
2967 to wxApp only, and only on Windows SmartPhone and PocketPC.
2968 It is generated when the system is low on memory; the application should free
2969 up as much memory as possible, and restore full working state when it receives
2970 a @c wxEVT_ACTIVATE or @c wxEVT_ACTIVATE_APP event.
2976 @see @ref overview_events, wxApp::IsActive
2978 class wxActivateEvent
: public wxEvent
2984 wxActivateEvent(wxEventType eventType
= wxEVT_NULL
, bool active
= true,
2988 Returns @true if the application or window is being activated, @false otherwise.
2990 bool GetActive() const;
2996 @class wxContextMenuEvent
2998 This class is used for context menu events, sent to give
2999 the application a chance to show a context (popup) menu for a wxWindow.
3001 Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this
3002 means that the event originated from a keyboard context button event, and you
3003 should compute a suitable position yourself, for example by calling wxGetMousePosition().
3005 Notice that the exact sequence of mouse events is different across the
3006 platforms. For example, under MSW the context menu event is generated after
3007 @c EVT_RIGHT_UP event and only if it was not handled but under GTK the
3008 context menu event is generated after @c EVT_RIGHT_DOWN event. This is
3009 correct in the sense that it ensures that the context menu is shown
3010 according to the current platform UI conventions and also means that you
3011 must not handle (or call wxEvent::Skip() in your handler if you do have
3012 one) neither right mouse down nor right mouse up event if you plan on
3013 handling @c EVT_CONTEXT_MENU event.
3015 @beginEventTable{wxContextMenuEvent}
3016 @event{EVT_CONTEXT_MENU(func)}
3017 A right click (or other context menu command depending on platform) has been detected.
3024 @see wxCommandEvent, @ref overview_events
3026 class wxContextMenuEvent
: public wxCommandEvent
3032 wxContextMenuEvent(wxEventType type
= wxEVT_NULL
, int id
= 0,
3033 const wxPoint
& pos
= wxDefaultPosition
);
3036 Returns the position in screen coordinates at which the menu should be shown.
3037 Use wxWindow::ScreenToClient to convert to client coordinates.
3039 You can also omit a position from wxWindow::PopupMenu in order to use
3040 the current mouse pointer position.
3042 If the event originated from a keyboard event, the value returned from this
3043 function will be wxDefaultPosition.
3045 const wxPoint
& GetPosition() const;
3048 Sets the position at which the menu should be shown.
3050 void SetPosition(const wxPoint
& point
);
3058 An erase event is sent when a window's background needs to be repainted.
3060 On some platforms, such as GTK+, this event is simulated (simply generated just
3061 before the paint event) and may cause flicker. It is therefore recommended that
3062 you set the text background colour explicitly in order to prevent flicker.
3063 The default background colour under GTK+ is grey.
3065 To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
3068 You must use the device context returned by GetDC() to draw on, don't create
3069 a wxPaintDC in the event handler.
3071 @beginEventTable{wxEraseEvent}
3072 @event{EVT_ERASE_BACKGROUND(func)}
3073 Process a @c wxEVT_ERASE_BACKGROUND event.
3079 @see @ref overview_events
3081 class wxEraseEvent
: public wxEvent
3087 wxEraseEvent(int id
= 0, wxDC
* dc
= NULL
);
3090 Returns the device context associated with the erase event to draw on.
3092 The returned pointer is never @NULL.
3094 wxDC
* GetDC() const;
3102 A focus event is sent when a window's focus changes. The window losing focus
3103 receives a "kill focus" event while the window gaining it gets a "set focus" one.
3105 Notice that the set focus event happens both when the user gives focus to the
3106 window (whether using the mouse or keyboard) and when it is done from the
3107 program itself using wxWindow::SetFocus.
3109 The focus event handlers should almost invariably call wxEvent::Skip() on
3110 their event argument to allow the default handling to take place. Failure
3111 to do this may result in incorrect behaviour of the native controls. Also
3112 note that wxEVT_KILL_FOCUS handler must not call wxWindow::SetFocus() as
3113 this, again, is not supported by all native controls. If you need to do
3114 this, consider using the @ref sec_delayed_action described in wxIdleEvent
3117 @beginEventTable{wxFocusEvent}
3118 @event{EVT_SET_FOCUS(func)}
3119 Process a @c wxEVT_SET_FOCUS event.
3120 @event{EVT_KILL_FOCUS(func)}
3121 Process a @c wxEVT_KILL_FOCUS event.
3127 @see @ref overview_events
3129 class wxFocusEvent
: public wxEvent
3135 wxFocusEvent(wxEventType eventType
= wxEVT_NULL
, int id
= 0);
3138 Returns the window associated with this event, that is the window which had the
3139 focus before for the @c wxEVT_SET_FOCUS event and the window which is
3140 going to receive focus for the @c wxEVT_KILL_FOCUS one.
3142 Warning: the window pointer may be @NULL!
3144 wxWindow
*GetWindow() const;
3146 void SetWindow(wxWindow
*win
);
3152 @class wxChildFocusEvent
3154 A child focus event is sent to a (parent-)window when one of its child windows
3155 gains focus, so that the window could restore the focus back to its corresponding
3156 child if it loses it now and regains later.
3158 Notice that child window is the direct child of the window receiving event.
3159 Use wxWindow::FindFocus() to retrieve the window which is actually getting focus.
3161 @beginEventTable{wxChildFocusEvent}
3162 @event{EVT_CHILD_FOCUS(func)}
3163 Process a @c wxEVT_CHILD_FOCUS event.
3169 @see @ref overview_events
3171 class wxChildFocusEvent
: public wxCommandEvent
3178 The direct child which is (or which contains the window which is) receiving
3181 wxChildFocusEvent(wxWindow
* win
= NULL
);
3184 Returns the direct child which receives the focus, or a (grand-)parent of the
3185 control receiving the focus.
3187 To get the actually focused control use wxWindow::FindFocus.
3189 wxWindow
*GetWindow() const;
3195 @class wxMouseCaptureLostEvent
3197 A mouse capture lost event is sent to a window that had obtained mouse capture,
3198 which was subsequently lost due to an "external" event (for example, when a dialog
3199 box is shown or if another application captures the mouse).
3201 If this happens, this event is sent to all windows that are on the capture stack
3202 (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is
3203 not sent if the capture changes because of a call to CaptureMouse or
3206 This event is currently emitted under Windows only.
3208 @beginEventTable{wxMouseCaptureLostEvent}
3209 @event{EVT_MOUSE_CAPTURE_LOST(func)}
3210 Process a @c wxEVT_MOUSE_CAPTURE_LOST event.
3218 @see wxMouseCaptureChangedEvent, @ref overview_events,
3219 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
3221 class wxMouseCaptureLostEvent
: public wxEvent
3227 wxMouseCaptureLostEvent(wxWindowID windowId
= 0);
3232 class wxDisplayChangedEvent
: public wxEvent
3235 wxDisplayChangedEvent();
3239 class wxPaletteChangedEvent
: public wxEvent
3242 wxPaletteChangedEvent(wxWindowID winid
= 0);
3244 void SetChangedWindow(wxWindow
* win
);
3245 wxWindow
* GetChangedWindow() const;
3249 class wxQueryNewPaletteEvent
: public wxEvent
3252 wxQueryNewPaletteEvent(wxWindowID winid
= 0);
3254 void SetPaletteRealized(bool realized
);
3255 bool GetPaletteRealized();
3262 @class wxNotifyEvent
3264 This class is not used by the event handlers by itself, but is a base class
3265 for other event classes (such as wxBookCtrlEvent).
3267 It (or an object of a derived class) is sent when the controls state is being
3268 changed and allows the program to wxNotifyEvent::Veto() this change if it wants
3269 to prevent it from happening.
3274 @see wxBookCtrlEvent
3276 class wxNotifyEvent
: public wxCommandEvent
3280 Constructor (used internally by wxWidgets only).
3282 wxNotifyEvent(wxEventType eventType
= wxEVT_NULL
, int id
= 0);
3285 This is the opposite of Veto(): it explicitly allows the event to be processed.
3286 For most events it is not necessary to call this method as the events are allowed
3287 anyhow but some are forbidden by default (this will be mentioned in the corresponding
3293 Returns @true if the change is allowed (Veto() hasn't been called) or @false
3294 otherwise (if it was).
3296 bool IsAllowed() const;
3299 Prevents the change announced by this event from happening.
3301 It is in general a good idea to notify the user about the reasons for vetoing
3302 the change because otherwise the applications behaviour (which just refuses to
3303 do what the user wants) might be quite surprising.
3310 @class wxThreadEvent
3312 This class adds some simple functionality to wxEvent to facilitate
3313 inter-thread communication.
3315 This event is not natively emitted by any control/class: it is just
3316 a helper class for the user.
3317 Its most important feature is the GetEventCategory() implementation which
3318 allows thread events @b NOT to be processed by wxEventLoopBase::YieldFor calls
3319 (unless the @c wxEVT_CATEGORY_THREAD is specified - which is never in wx code).
3322 @category{events,threading}
3324 @see @ref overview_thread, wxEventLoopBase::YieldFor
3328 class wxThreadEvent
: public wxEvent
3334 wxThreadEvent(wxEventType eventType
= wxEVT_THREAD
, int id
= wxID_ANY
);
3337 Clones this event making sure that all internal members which use
3338 COW (only @c m_commandString for now; see @ref overview_refcount)
3339 are unshared (see wxObject::UnShare).
3341 virtual wxEvent
*Clone() const;
3344 Returns @c wxEVT_CATEGORY_THREAD.
3346 This is important to avoid unwanted processing of thread events
3347 when calling wxEventLoopBase::YieldFor().
3349 virtual wxEventCategory
GetEventCategory() const;
3352 Sets custom data payload.
3354 The @a payload argument may be of any type that wxAny can handle
3355 (i.e. pretty much anything). Note that T's copy constructor must be
3356 thread-safe, i.e. create a copy that doesn't share anything with
3357 the original (see Clone()).
3359 @note This method is not available with Visual C++ 6.
3363 @see GetPayload(), wxAny
3365 template<typename T
>
3366 void SetPayload(const T
& payload
);
3369 Get custom data payload.
3371 Correct type is checked in debug builds.
3373 @note This method is not available with Visual C++ 6.
3377 @see SetPayload(), wxAny
3379 template<typename T
>
3380 T
GetPayload() const;
3383 Returns extra information integer value.
3385 long GetExtraLong() const;
3388 Returns stored integer value.
3393 Returns stored string value.
3395 wxString
GetString() const;
3399 Sets the extra information value.
3401 void SetExtraLong(long extraLong
);
3404 Sets the integer value.
3406 void SetInt(int intCommand
);
3409 Sets the string value.
3411 void SetString(const wxString
& string
);
3418 A help event is sent when the user has requested context-sensitive help.
3419 This can either be caused by the application requesting context-sensitive help mode
3420 via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when
3421 the user pressed F1 or clicked on the query button in a dialog caption.
3423 A help event is sent to the window that the user clicked on, and is propagated
3424 up the window hierarchy until the event is processed or there are no more event
3427 The application should call wxEvent::GetId to check the identity of the
3428 clicked-on window, and then either show some suitable help or call wxEvent::Skip()
3429 if the identifier is unrecognised.
3431 Calling Skip is important because it allows wxWidgets to generate further
3432 events for ancestors of the clicked-on window. Otherwise it would be impossible to
3433 show help for container windows, since processing would stop after the first window
3436 @beginEventTable{wxHelpEvent}
3437 @event{EVT_HELP(id, func)}
3438 Process a @c wxEVT_HELP event.
3439 @event{EVT_HELP_RANGE(id1, id2, func)}
3440 Process a @c wxEVT_HELP event for a range of ids.
3446 @see wxContextHelp, wxDialog, @ref overview_events
3448 class wxHelpEvent
: public wxCommandEvent
3452 Indicates how a wxHelpEvent was generated.
3456 Origin_Unknown
, /**< unrecognized event source. */
3457 Origin_Keyboard
, /**< event generated from F1 key press. */
3459 /** event generated by wxContextHelp or from the [?] button on
3460 the title bar (Windows). */
3467 wxHelpEvent(wxEventType type
= wxEVT_NULL
,
3468 wxWindowID winid
= 0,
3469 const wxPoint
& pt
= wxDefaultPosition
,
3470 wxHelpEvent::Origin origin
= Origin_Unknown
);
3473 Returns the origin of the help event which is one of the wxHelpEvent::Origin
3476 The application may handle events generated using the keyboard or mouse
3477 differently, e.g. by using wxGetMousePosition() for the mouse events.
3481 wxHelpEvent::Origin
GetOrigin() const;
3484 Returns the left-click position of the mouse, in screen coordinates.
3485 This allows the application to position the help appropriately.
3487 const wxPoint
& GetPosition() const;
3490 Set the help event origin, only used internally by wxWidgets normally.
3494 void SetOrigin(wxHelpEvent::Origin origin
);
3497 Sets the left-click position of the mouse, in screen coordinates.
3499 void SetPosition(const wxPoint
& pt
);
3505 @class wxScrollEvent
3507 A scroll event holds information about events sent from stand-alone
3508 scrollbars (see wxScrollBar) and sliders (see wxSlider).
3510 Note that scrolled windows send the wxScrollWinEvent which does not derive from
3511 wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of
3512 events and use the event table macros mentioned below only for the scrollbar-like
3515 @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
3517 The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
3518 using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
3519 by an EVT_SCROLL_CHANGED event).
3521 The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb
3522 position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE
3523 event does not happen).
3525 In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished
3526 independently of the way it had started. Please see the widgets sample ("Slider" page)
3527 to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action.
3530 Note that unless specifying a scroll control identifier, you will need to test for scrollbar
3531 orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events
3532 are processed using the same event handler.
3534 @beginEventTable{wxScrollEvent}
3535 You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
3536 scroll events from controls, or EVT_SCROLL... macros without window IDs for
3537 intercepting scroll events from the receiving window -- except for this, the
3538 macros behave exactly the same.
3539 @event{EVT_SCROLL(func)}
3540 Process all scroll events.
3541 @event{EVT_SCROLL_TOP(func)}
3542 Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
3543 @event{EVT_SCROLL_BOTTOM(func)}
3544 Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
3545 @event{EVT_SCROLL_LINEUP(func)}
3546 Process @c wxEVT_SCROLL_LINEUP line up events.
3547 @event{EVT_SCROLL_LINEDOWN(func)}
3548 Process @c wxEVT_SCROLL_LINEDOWN line down events.
3549 @event{EVT_SCROLL_PAGEUP(func)}
3550 Process @c wxEVT_SCROLL_PAGEUP page up events.
3551 @event{EVT_SCROLL_PAGEDOWN(func)}
3552 Process @c wxEVT_SCROLL_PAGEDOWN page down events.
3553 @event{EVT_SCROLL_THUMBTRACK(func)}
3554 Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the
3555 user drags the thumbtrack).
3556 @event{EVT_SCROLL_THUMBRELEASE(func)}
3557 Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events.
3558 @event{EVT_SCROLL_CHANGED(func)}
3559 Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
3560 @event{EVT_COMMAND_SCROLL(id, func)}
3561 Process all scroll events.
3562 @event{EVT_COMMAND_SCROLL_TOP(id, func)}
3563 Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
3564 @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
3565 Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
3566 @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
3567 Process @c wxEVT_SCROLL_LINEUP line up events.
3568 @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
3569 Process @c wxEVT_SCROLL_LINEDOWN line down events.
3570 @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
3571 Process @c wxEVT_SCROLL_PAGEUP page up events.
3572 @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
3573 Process @c wxEVT_SCROLL_PAGEDOWN page down events.
3574 @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
3575 Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent
3576 as the user drags the thumbtrack).
3577 @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
3578 Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events.
3579 @event{EVT_COMMAND_SCROLL_CHANGED(func)}
3580 Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
3586 @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_events
3588 class wxScrollEvent
: public wxCommandEvent
3594 wxScrollEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0, int pos
= 0,
3595 int orientation
= 0);
3598 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
3601 int GetOrientation() const;
3604 Returns the position of the scrollbar.
3606 int GetPosition() const;
3609 void SetOrientation(int orient
);
3610 void SetPosition(int pos
);
3618 See wxIdleEvent::SetMode() for more info.
3622 /** Send idle events to all windows */
3625 /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */
3626 wxIDLE_PROCESS_SPECIFIED
3633 This class is used for idle events, which are generated when the system becomes
3634 idle. Note that, unless you do something specifically, the idle events are not
3635 sent if the system remains idle once it has become it, e.g. only a single idle
3636 event will be generated until something else resulting in more normal events
3637 happens and only then is the next idle event sent again.
3639 If you need to ensure a continuous stream of idle events, you can either use
3640 wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically
3641 (for example from a timer event handler), but note that both of these approaches
3642 (and especially the first one) increase the system load and so should be avoided
3645 By default, idle events are sent to all windows, including even the hidden
3646 ones because they may be shown if some condition is met from their @c
3647 wxEVT_IDLE (or related @c wxEVT_UPDATE_UI) handler. The children of hidden
3648 windows do not receive idle events however as they can't change their state
3649 in any way noticeable by the user. Finally, the global wxApp object also
3650 receives these events, as usual, so it can be used for any global idle time
3653 If sending idle events to all windows is causing a significant overhead in
3654 your application, you can call wxIdleEvent::SetMode with the value
3655 wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra window
3656 style for every window which should receive idle events, all the other ones
3657 will not receive them in this case.
3659 @beginEventTable{wxIdleEvent}
3660 @event{EVT_IDLE(func)}
3661 Process a @c wxEVT_IDLE event.
3667 @section sec_delayed_action Delayed Action Mechanism
3669 wxIdleEvent can be used to perform some action "at slightly later time".
3670 This can be necessary in several circumstances when, for whatever reason,
3671 something can't be done in the current event handler. For example, if a
3672 mouse event handler is called with the mouse button pressed, the mouse can
3673 be currently captured and some operations with it -- notably capturing it
3674 again -- might be impossible or lead to undesirable results. If you still
3675 want to capture it, you can do it from @c wxEVT_IDLE handler when it is
3676 called the next time instead of doing it immediately.
3678 This can be achieved in two different ways: when using static event tables,
3679 you will need a flag indicating to the (always connected) idle event
3680 handler whether the desired action should be performed. The originally
3681 called handler would then set it to indicate that it should indeed be done
3682 and the idle handler itself would reset it to prevent it from doing the
3685 Using dynamically connected event handlers things are even simpler as the
3686 original event handler can simply wxEvtHandler::Connect() or
3687 wxEvtHandler::Bind() the idle event handler which would only be executed
3688 then and could wxEvtHandler::Disconnect() or wxEvtHandler::Unbind() itself.
3691 @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle
3693 class wxIdleEvent
: public wxEvent
3702 Static function returning a value specifying how wxWidgets will send idle
3703 events: to all windows, or only to those which specify that they
3704 will process the events.
3708 static wxIdleMode
GetMode();
3711 Returns @true if the OnIdle function processing this event requested more
3716 bool MoreRequested() const;
3719 Tells wxWidgets that more processing is required.
3721 This function can be called by an OnIdle handler for a window or window event
3722 handler to indicate that wxApp::OnIdle should forward the OnIdle event once
3723 more to the application windows.
3725 If no window calls this function during OnIdle, then the application will
3726 remain in a passive event loop (not calling OnIdle) until a new event is
3727 posted to the application by the windowing system.
3729 @see MoreRequested()
3731 void RequestMore(bool needMore
= true);
3734 Static function for specifying how wxWidgets will send idle events: to
3735 all windows, or only to those which specify that they will process the events.
3738 Can be one of the ::wxIdleMode values.
3739 The default is wxIDLE_PROCESS_ALL.
3741 static void SetMode(wxIdleMode mode
);
3744 #endif // wxUSE_BASE
3749 @class wxInitDialogEvent
3751 A wxInitDialogEvent is sent as a dialog or panel is being initialised.
3752 Handlers for this event can transfer data to the window.
3754 The default handler calls wxWindow::TransferDataToWindow.
3756 @beginEventTable{wxInitDialogEvent}
3757 @event{EVT_INIT_DIALOG(func)}
3758 Process a @c wxEVT_INIT_DIALOG event.
3764 @see @ref overview_events
3766 class wxInitDialogEvent
: public wxEvent
3772 wxInitDialogEvent(int id
= 0);
3778 @class wxWindowDestroyEvent
3780 This event is sent as early as possible during the window destruction
3783 For the top level windows, as early as possible means that this is done by
3784 wxFrame or wxDialog destructor, i.e. after the destructor of the derived
3785 class was executed and so any methods specific to the derived class can't
3786 be called any more from this event handler. If you need to do this, you
3787 must call wxWindow::SendDestroyEvent() from your derived class destructor.
3789 For the child windows, this event is generated just before deleting the
3790 window from wxWindow::Destroy() (which is also called when the parent
3791 window is deleted) or from the window destructor if operator @c delete was
3792 used directly (which is not recommended for this very reason).
3794 It is usually pointless to handle this event in the window itself but it ca
3795 be very useful to receive notifications about the window destruction in the
3796 parent window or in any other object interested in this window.
3801 @see @ref overview_events, wxWindowCreateEvent
3803 class wxWindowDestroyEvent
: public wxCommandEvent
3809 wxWindowDestroyEvent(wxWindow
* win
= NULL
);
3811 /// Return the window being destroyed.
3812 wxWindow
*GetWindow() const;
3817 @class wxNavigationKeyEvent
3819 This event class contains information about navigation events,
3820 generated by navigation keys such as tab and page down.
3822 This event is mainly used by wxWidgets implementations.
3823 A wxNavigationKeyEvent handler is automatically provided by wxWidgets
3824 when you enable keyboard navigation inside a window by inheriting it from
3825 wxNavigationEnabled<>.
3827 @beginEventTable{wxNavigationKeyEvent}
3828 @event{EVT_NAVIGATION_KEY(func)}
3829 Process a navigation key event.
3835 @see wxWindow::Navigate, wxWindow::NavigateIn
3837 class wxNavigationKeyEvent
: public wxEvent
3841 Flags which can be used with wxNavigationKeyEvent.
3843 enum wxNavigationKeyEventFlags
3845 IsBackward
= 0x0000,
3851 wxNavigationKeyEvent();
3852 wxNavigationKeyEvent(const wxNavigationKeyEvent
& event
);
3855 Returns the child that has the focus, or @NULL.
3857 wxWindow
* GetCurrentFocus() const;
3860 Returns @true if the navigation was in the forward direction.
3862 bool GetDirection() const;
3865 Returns @true if the navigation event was from a tab key.
3866 This is required for proper navigation over radio buttons.
3868 bool IsFromTab() const;
3871 Returns @true if the navigation event represents a window change
3872 (for example, from Ctrl-Page Down in a notebook).
3874 bool IsWindowChange() const;
3877 Sets the current focus window member.
3879 void SetCurrentFocus(wxWindow
* currentFocus
);
3882 Sets the direction to forward if @a direction is @true, or backward
3885 void SetDirection(bool direction
);
3888 Sets the flags for this event.
3889 The @a flags can be a combination of the
3890 wxNavigationKeyEvent::wxNavigationKeyEventFlags values.
3892 void SetFlags(long flags
);
3895 Marks the navigation event as from a tab key.
3897 void SetFromTab(bool fromTab
);
3900 Marks the event as a window change event.
3902 void SetWindowChange(bool windowChange
);
3908 @class wxMouseCaptureChangedEvent
3910 An mouse capture changed event is sent to a window that loses its
3911 mouse capture. This is called even if wxWindow::ReleaseMouse
3912 was called by the application code. Handling this event allows
3913 an application to cater for unexpected capture releases which
3914 might otherwise confuse mouse handling code.
3918 @beginEventTable{wxMouseCaptureChangedEvent}
3919 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
3920 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event.
3926 @see wxMouseCaptureLostEvent, @ref overview_events,
3927 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
3929 class wxMouseCaptureChangedEvent
: public wxEvent
3935 wxMouseCaptureChangedEvent(wxWindowID windowId
= 0,
3936 wxWindow
* gainedCapture
= NULL
);
3939 Returns the window that gained the capture, or @NULL if it was a
3940 non-wxWidgets window.
3942 wxWindow
* GetCapturedWindow() const;
3950 This event class contains information about window and session close events.
3952 The handler function for EVT_CLOSE is called when the user has tried to close a
3953 a frame or dialog box using the window manager (X) or system menu (Windows).
3954 It can also be invoked by the application itself programmatically, for example by
3955 calling the wxWindow::Close function.
3957 You should check whether the application is forcing the deletion of the window
3958 using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window
3959 using wxWindow::Destroy.
3961 If the return value is @true, it is up to you whether you respond by destroying
3964 If you don't destroy the window, you should call wxCloseEvent::Veto to
3965 let the calling code know that you did not destroy the window.
3966 This allows the wxWindow::Close function to return @true or @false depending
3967 on whether the close instruction was honoured or not.
3969 Example of a wxCloseEvent handler:
3972 void MyFrame::OnClose(wxCloseEvent& event)
3974 if ( event.CanVeto() && m_bFileNotSaved )
3976 if ( wxMessageBox("The file has not been saved... continue closing?",
3978 wxICON_QUESTION | wxYES_NO) != wxYES )
3985 Destroy(); // you may also do: event.Skip();
3986 // since the default event handler does call Destroy(), too
3990 The EVT_END_SESSION event is slightly different as it is sent by the system
3991 when the user session is ending (e.g. because of log out or shutdown) and
3992 so all windows are being forcefully closed. At least under MSW, after the
3993 handler for this event is executed the program is simply killed by the
3994 system. Because of this, the default handler for this event provided by
3995 wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so
3996 that it could still be executed and exit()s the process itself, without
3997 waiting for being killed. If this behaviour is for some reason undesirable,
3998 make sure that you define a handler for this event in your wxApp-derived
3999 class and do not call @c event.Skip() in it (but be aware that the system
4000 will still kill your application).
4002 @beginEventTable{wxCloseEvent}
4003 @event{EVT_CLOSE(func)}
4004 Process a @c wxEVT_CLOSE_WINDOW command event, supplying the member function.
4005 This event applies to wxFrame and wxDialog classes.
4006 @event{EVT_QUERY_END_SESSION(func)}
4007 Process a @c wxEVT_QUERY_END_SESSION session event, supplying the member function.
4008 This event can be handled in wxApp-derived class only.
4009 @event{EVT_END_SESSION(func)}
4010 Process a @c wxEVT_END_SESSION session event, supplying the member function.
4011 This event can be handled in wxApp-derived class only.
4017 @see wxWindow::Close, @ref overview_windowdeletion
4019 class wxCloseEvent
: public wxEvent
4025 wxCloseEvent(wxEventType commandEventType
= wxEVT_NULL
, int id
= 0);
4028 Returns @true if you can veto a system shutdown or a window close event.
4029 Vetoing a window close event is not possible if the calling code wishes to
4030 force the application to exit, and so this function must be called to check this.
4032 bool CanVeto() const;
4035 Returns @true if the user is just logging off or @false if the system is
4036 shutting down. This method can only be called for end session and query end
4037 session events, it doesn't make sense for close window event.
4039 bool GetLoggingOff() const;
4042 Sets the 'can veto' flag.
4044 void SetCanVeto(bool canVeto
);
4047 Sets the 'logging off' flag.
4049 void SetLoggingOff(bool loggingOff
);
4052 Call this from your event handler to veto a system shutdown or to signal
4053 to the calling application that a window close did not happen.
4055 You can only veto a shutdown if CanVeto() returns @true.
4057 void Veto(bool veto
= true);
4065 This class is used for a variety of menu-related events. Note that
4066 these do not include menu command events, which are
4067 handled using wxCommandEvent objects.
4069 The default handler for @c wxEVT_MENU_HIGHLIGHT displays help
4070 text in the first field of the status bar.
4072 @beginEventTable{wxMenuEvent}
4073 @event{EVT_MENU_OPEN(func)}
4074 A menu is about to be opened. On Windows, this is only sent once for each
4075 navigation of the menubar (up until all menus have closed).
4076 @event{EVT_MENU_CLOSE(func)}
4077 A menu has been just closed.
4078 @event{EVT_MENU_HIGHLIGHT(id, func)}
4079 The menu item with the specified id has been highlighted: used to show
4080 help prompts in the status bar by wxFrame
4081 @event{EVT_MENU_HIGHLIGHT_ALL(func)}
4082 A menu item has been highlighted, i.e. the currently selected menu item has changed.
4088 @see wxCommandEvent, @ref overview_events
4090 class wxMenuEvent
: public wxEvent
4096 wxMenuEvent(wxEventType type
= wxEVT_NULL
, int id
= 0, wxMenu
* menu
= NULL
);
4099 Returns the menu which is being opened or closed.
4101 This method can only be used with the @c OPEN and @c CLOSE events.
4103 The returned value is never @NULL in the ports implementing this
4104 function, which currently includes all the major ones.
4106 wxMenu
* GetMenu() const;
4109 Returns the menu identifier associated with the event.
4110 This method should be only used with the @c HIGHLIGHT events.
4112 int GetMenuId() const;
4115 Returns @true if the menu which is being opened or closed is a popup menu,
4116 @false if it is a normal one.
4118 This method should only be used with the @c OPEN and @c CLOSE events.
4120 bool IsPopup() const;
4126 An event being sent when the window is shown or hidden.
4127 The event is triggered by calls to wxWindow::Show(), and any user
4128 action showing a previously hidden window or vice versa (if allowed by
4129 the current platform and/or window manager).
4130 Notice that the event is not triggered when the application is iconized
4131 (minimized) or restored under wxMSW.
4133 @onlyfor{wxmsw,wxgtk,wxos2}
4135 @beginEventTable{wxShowEvent}
4136 @event{EVT_SHOW(func)}
4137 Process a @c wxEVT_SHOW event.
4143 @see @ref overview_events, wxWindow::Show,
4147 class wxShowEvent
: public wxEvent
4153 wxShowEvent(int winid
= 0, bool show
= false);
4156 Set whether the windows was shown or hidden.
4158 void SetShow(bool show
);
4161 Return @true if the window has been shown, @false if it has been
4164 bool IsShown() const;
4167 @deprecated This function is deprecated in favour of IsShown().
4169 bool GetShow() const;
4175 @class wxIconizeEvent
4177 An event being sent when the frame is iconized (minimized) or restored.
4179 Currently only wxMSW and wxGTK generate such events.
4181 @onlyfor{wxmsw,wxgtk}
4183 @beginEventTable{wxIconizeEvent}
4184 @event{EVT_ICONIZE(func)}
4185 Process a @c wxEVT_ICONIZE event.
4191 @see @ref overview_events, wxTopLevelWindow::Iconize,
4192 wxTopLevelWindow::IsIconized
4194 class wxIconizeEvent
: public wxEvent
4200 wxIconizeEvent(int id
= 0, bool iconized
= true);
4203 Returns @true if the frame has been iconized, @false if it has been
4206 bool IsIconized() const;
4209 @deprecated This function is deprecated in favour of IsIconized().
4211 bool Iconized() const;
4219 A move event holds information about wxTopLevelWindow move change events.
4221 These events are currently only generated by wxMSW port.
4223 @beginEventTable{wxMoveEvent}
4224 @event{EVT_MOVE(func)}
4225 Process a @c wxEVT_MOVE event, which is generated when a window is moved.
4226 @event{EVT_MOVE_START(func)}
4227 Process a @c wxEVT_MOVE_START event, which is generated when the user starts
4228 to move or size a window. wxMSW only.
4229 @event{EVT_MOVING(func)}
4230 Process a @c wxEVT_MOVING event, which is generated while the user is
4231 moving the window. wxMSW only.
4232 @event{EVT_MOVE_END(func)}
4233 Process a @c wxEVT_MOVE_END event, which is generated when the user stops
4234 moving or sizing a window. wxMSW only.
4240 @see wxPoint, @ref overview_events
4242 class wxMoveEvent
: public wxEvent
4248 wxMoveEvent(const wxPoint
& pt
, int id
= 0);
4251 Returns the position of the window generating the move change event.
4253 wxPoint
GetPosition() const;
4255 wxRect
GetRect() const;
4256 void SetRect(const wxRect
& rect
);
4257 void SetPosition(const wxPoint
& pos
);
4264 A size event holds information about size change events of wxWindow.
4266 The EVT_SIZE handler function will be called when the window has been resized.
4268 You may wish to use this for frames to resize their child windows as appropriate.
4270 Note that the size passed is of the whole window: call wxWindow::GetClientSize()
4271 for the area which may be used by the application.
4273 When a window is resized, usually only a small part of the window is damaged
4274 and you may only need to repaint that area. However, if your drawing depends on the
4275 size of the window, you may need to clear the DC explicitly and repaint the whole window.
4276 In which case, you may need to call wxWindow::Refresh to invalidate the entire window.
4278 @b Important : Sizers ( see @ref overview_sizer ) rely on size events to function
4279 correctly. Therefore, in a sizer-based layout, do not forget to call Skip on all
4280 size events you catch (and don't catch size events at all when you don't need to).
4282 @beginEventTable{wxSizeEvent}
4283 @event{EVT_SIZE(func)}
4284 Process a @c wxEVT_SIZE event.
4290 @see wxSize, @ref overview_events
4292 class wxSizeEvent
: public wxEvent
4298 wxSizeEvent(const wxSize
& sz
, int id
= 0);
4301 Returns the entire size of the window generating the size change event.
4303 This is the new total size of the window, i.e. the same size as would
4304 be returned by wxWindow::GetSize() if it were called now. Use
4305 wxWindow::GetClientSize() if you catch this event in a top level window
4306 such as wxFrame to find the size available for the window contents.
4308 wxSize
GetSize() const;
4309 void SetSize(wxSize size
);
4311 wxRect
GetRect() const;
4312 void SetRect(wxRect rect
);
4318 @class wxSetCursorEvent
4320 A wxSetCursorEvent is generated from wxWindow when the mouse cursor is about
4321 to be set as a result of mouse motion.
4323 This event gives the application the chance to perform specific mouse cursor
4324 processing based on the current position of the mouse within the window.
4325 Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed.
4327 @beginEventTable{wxSetCursorEvent}
4328 @event{EVT_SET_CURSOR(func)}
4329 Process a @c wxEVT_SET_CURSOR event.
4335 @see ::wxSetCursor, wxWindow::SetCursor
4337 class wxSetCursorEvent
: public wxEvent
4341 Constructor, used by the library itself internally to initialize the event
4344 wxSetCursorEvent(wxCoord x
= 0, wxCoord y
= 0);
4347 Returns a reference to the cursor specified by this event.
4349 const wxCursor
& GetCursor() const;
4352 Returns the X coordinate of the mouse in client coordinates.
4354 wxCoord
GetX() const;
4357 Returns the Y coordinate of the mouse in client coordinates.
4359 wxCoord
GetY() const;
4362 Returns @true if the cursor specified by this event is a valid cursor.
4364 @remarks You cannot specify wxNullCursor with this event, as it is not
4365 considered a valid cursor.
4367 bool HasCursor() const;
4370 Sets the cursor associated with this event.
4372 void SetCursor(const wxCursor
& cursor
);
4377 // ============================================================================
4378 // Global functions/macros
4379 // ============================================================================
4381 /** @addtogroup group_funcmacro_events */
4387 A value uniquely identifying the type of the event.
4389 The values of this type should only be created using wxNewEventType().
4391 See the macro DEFINE_EVENT_TYPE() for more info.
4393 @see @ref overview_events
4395 typedef int wxEventType
;
4398 A special event type usually used to indicate that some wxEvent has yet
4401 wxEventType wxEVT_NULL
;
4403 wxEventType wxEVT_ANY
;
4406 Generates a new unique event type.
4408 Usually this function is only used by wxDEFINE_EVENT() and not called
4411 wxEventType
wxNewEventType();
4414 Define a new event type associated with the specified event class.
4416 This macro defines a new unique event type @a name associated with the
4421 wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
4423 class MyCustomEvent : public wxEvent { ... };
4424 wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
4427 @see wxDECLARE_EVENT(), @ref overview_events_custom
4429 #define wxDEFINE_EVENT(name, cls) \
4430 const wxEventTypeTag< cls > name(wxNewEventType())
4433 Declares a custom event type.
4435 This macro declares a variable called @a name which must be defined
4436 elsewhere using wxDEFINE_EVENT().
4438 The class @a cls must be the wxEvent-derived class associated with the
4439 events of this type and its full declaration must be visible from the point
4440 of use of this macro.
4444 wxDECLARE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
4446 class MyCustomEvent : public wxEvent { ... };
4447 wxDECLARE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
4450 #define wxDECLARE_EVENT(name, cls) \
4451 wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls)
4454 Variant of wxDECLARE_EVENT() used for event types defined inside a shared
4457 This is mostly used by wxWidgets internally, e.g.
4459 wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_BUTTON, wxCommandEvent)
4462 #define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \
4463 extern const expdecl wxEventTypeTag< cls > name;
4466 Helper macro for definition of custom event table macros.
4468 This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise
4469 it is better and more clear to just use the address of the function
4470 directly as this is all this macro does in this case. However it needs to
4471 explicitly cast @a func to @a functype, which is the type of wxEvtHandler
4472 member function taking the custom event argument when
4473 wxEVENTS_COMPATIBILITY_2_8 is 0.
4475 See wx__DECLARE_EVT0 for an example of use.
4477 @see @ref overview_events_custom_ownclass
4479 #define wxEVENT_HANDLER_CAST(functype, func) (&func)
4482 This macro is used to define event table macros for handling custom
4487 class MyEvent : public wxEvent { ... };
4489 // note that this is not necessary unless using old compilers: for the
4490 // reasonably new ones just use &func instead of MyEventHandler(func)
4491 typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&);
4492 #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func)
4494 wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent);
4496 #define EVT_MY(id, func) \
4497 wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func))
4501 wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
4502 EVT_MY(wxID_ANY, MyFrame::OnMyEvent)
4507 The event type to handle.
4509 The identifier of events to handle.
4511 The event handler method.
4513 #define wx__DECLARE_EVT1(evt, id, fn) \
4514 wx__DECLARE_EVT2(evt, id, wxID_ANY, fn)
4517 Generalized version of the wx__DECLARE_EVT1() macro taking a range of
4518 IDs instead of a single one.
4519 Argument @a id1 is the first identifier of the range, @a id2 is the
4520 second identifier of the range.
4522 #define wx__DECLARE_EVT2(evt, id1, id2, fn) \
4523 DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
4526 Simplified version of the wx__DECLARE_EVT1() macro, to be used when the
4527 event type must be handled regardless of the ID associated with the
4528 specific event instances.
4530 #define wx__DECLARE_EVT0(evt, fn) \
4531 wx__DECLARE_EVT1(evt, wxID_ANY, fn)
4534 Use this macro inside a class declaration to declare a @e static event table
4537 In the implementation file you'll need to use the wxBEGIN_EVENT_TABLE()
4538 and the wxEND_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro
4541 Note that this macro requires a final semicolon.
4543 @see @ref overview_events_eventtables
4545 #define wxDECLARE_EVENT_TABLE()
4548 Use this macro in a source file to start listing @e static event handlers
4549 for a specific class.
4551 Use wxEND_EVENT_TABLE() to terminate the event-declaration block.
4553 @see @ref overview_events_eventtables
4555 #define wxBEGIN_EVENT_TABLE(theClass, baseClass)
4558 Use this macro in a source file to end listing @e static event handlers
4559 for a specific class.
4561 Use wxBEGIN_EVENT_TABLE() to start the event-declaration block.
4563 @see @ref overview_events_eventtables
4565 #define wxEND_EVENT_TABLE()
4568 In a GUI application, this function posts @a event to the specified @e dest
4569 object using wxEvtHandler::AddPendingEvent().
4571 Otherwise, it dispatches @a event immediately using
4572 wxEvtHandler::ProcessEvent(). See the respective documentation for details
4573 (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent()
4574 this function is not thread-safe for event objects having wxString fields,
4575 use wxQueueEvent() instead.
4579 void wxPostEvent(wxEvtHandler
* dest
, const wxEvent
& event
);
4582 Queue an event for processing on the given object.
4584 This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation
4590 The object to queue the event on, can't be @c NULL.
4592 The heap-allocated and non-@c NULL event to queue, the function takes
4595 void wxQueueEvent(wxEvtHandler
* dest
, wxEvent
*event
);
4597 #endif // wxUSE_BASE
4601 wxEventType wxEVT_BUTTON
;
4602 wxEventType wxEVT_CHECKBOX
;
4603 wxEventType wxEVT_CHOICE
;
4604 wxEventType wxEVT_LISTBOX
;
4605 wxEventType wxEVT_LISTBOX_DCLICK
;
4606 wxEventType wxEVT_CHECKLISTBOX
;
4607 wxEventType wxEVT_MENU
;
4608 wxEventType wxEVT_SLIDER
;
4609 wxEventType wxEVT_RADIOBOX
;
4610 wxEventType wxEVT_RADIOBUTTON
;
4611 wxEventType wxEVT_SCROLLBAR
;
4612 wxEventType wxEVT_VLBOX
;
4613 wxEventType wxEVT_COMBOBOX
;
4614 wxEventType wxEVT_TOOL_RCLICKED
;
4615 wxEventType wxEVT_TOOL_DROPDOWN
;
4616 wxEventType wxEVT_TOOL_ENTER
;
4617 wxEventType wxEVT_COMBOBOX_DROPDOWN
;
4618 wxEventType wxEVT_COMBOBOX_CLOSEUP
;
4619 wxEventType wxEVT_THREAD
;
4620 wxEventType wxEVT_LEFT_DOWN
;
4621 wxEventType wxEVT_LEFT_UP
;
4622 wxEventType wxEVT_MIDDLE_DOWN
;
4623 wxEventType wxEVT_MIDDLE_UP
;
4624 wxEventType wxEVT_RIGHT_DOWN
;
4625 wxEventType wxEVT_RIGHT_UP
;
4626 wxEventType wxEVT_MOTION
;
4627 wxEventType wxEVT_ENTER_WINDOW
;
4628 wxEventType wxEVT_LEAVE_WINDOW
;
4629 wxEventType wxEVT_LEFT_DCLICK
;
4630 wxEventType wxEVT_MIDDLE_DCLICK
;
4631 wxEventType wxEVT_RIGHT_DCLICK
;
4632 wxEventType wxEVT_SET_FOCUS
;
4633 wxEventType wxEVT_KILL_FOCUS
;
4634 wxEventType wxEVT_CHILD_FOCUS
;
4635 wxEventType wxEVT_MOUSEWHEEL
;
4636 wxEventType wxEVT_AUX1_DOWN
;
4637 wxEventType wxEVT_AUX1_UP
;
4638 wxEventType wxEVT_AUX1_DCLICK
;
4639 wxEventType wxEVT_AUX2_DOWN
;
4640 wxEventType wxEVT_AUX2_UP
;
4641 wxEventType wxEVT_AUX2_DCLICK
;
4642 wxEventType wxEVT_CHAR
;
4643 wxEventType wxEVT_CHAR_HOOK
;
4644 wxEventType wxEVT_NAVIGATION_KEY
;
4645 wxEventType wxEVT_KEY_DOWN
;
4646 wxEventType wxEVT_KEY_UP
;
4647 wxEventType wxEVT_HOTKEY
;
4648 wxEventType wxEVT_SET_CURSOR
;
4649 wxEventType wxEVT_SCROLL_TOP
;
4650 wxEventType wxEVT_SCROLL_BOTTOM
;
4651 wxEventType wxEVT_SCROLL_LINEUP
;
4652 wxEventType wxEVT_SCROLL_LINEDOWN
;
4653 wxEventType wxEVT_SCROLL_PAGEUP
;
4654 wxEventType wxEVT_SCROLL_PAGEDOWN
;
4655 wxEventType wxEVT_SCROLL_THUMBTRACK
;
4656 wxEventType wxEVT_SCROLL_THUMBRELEASE
;
4657 wxEventType wxEVT_SCROLL_CHANGED
;
4658 wxEventType wxEVT_SPIN_UP
;
4659 wxEventType wxEVT_SPIN_DOWN
;
4660 wxEventType wxEVT_SPIN
;
4661 wxEventType wxEVT_SCROLLWIN_TOP
;
4662 wxEventType wxEVT_SCROLLWIN_BOTTOM
;
4663 wxEventType wxEVT_SCROLLWIN_LINEUP
;
4664 wxEventType wxEVT_SCROLLWIN_LINEDOWN
;
4665 wxEventType wxEVT_SCROLLWIN_PAGEUP
;
4666 wxEventType wxEVT_SCROLLWIN_PAGEDOWN
;
4667 wxEventType wxEVT_SCROLLWIN_THUMBTRACK
;
4668 wxEventType wxEVT_SCROLLWIN_THUMBRELEASE
;
4669 wxEventType wxEVT_SIZE
;
4670 wxEventType wxEVT_MOVE
;
4671 wxEventType wxEVT_CLOSE_WINDOW
;
4672 wxEventType wxEVT_END_SESSION
;
4673 wxEventType wxEVT_QUERY_END_SESSION
;
4674 wxEventType wxEVT_ACTIVATE_APP
;
4675 wxEventType wxEVT_ACTIVATE
;
4676 wxEventType wxEVT_CREATE
;
4677 wxEventType wxEVT_DESTROY
;
4678 wxEventType wxEVT_SHOW
;
4679 wxEventType wxEVT_ICONIZE
;
4680 wxEventType wxEVT_MAXIMIZE
;
4681 wxEventType wxEVT_MOUSE_CAPTURE_CHANGED
;
4682 wxEventType wxEVT_MOUSE_CAPTURE_LOST
;
4683 wxEventType wxEVT_PAINT
;
4684 wxEventType wxEVT_ERASE_BACKGROUND
;
4685 wxEventType wxEVT_NC_PAINT
;
4686 wxEventType wxEVT_MENU_OPEN
;
4687 wxEventType wxEVT_MENU_CLOSE
;
4688 wxEventType wxEVT_MENU_HIGHLIGHT
;
4689 wxEventType wxEVT_CONTEXT_MENU
;
4690 wxEventType wxEVT_SYS_COLOUR_CHANGED
;
4691 wxEventType wxEVT_DISPLAY_CHANGED
;
4692 wxEventType wxEVT_QUERY_NEW_PALETTE
;
4693 wxEventType wxEVT_PALETTE_CHANGED
;
4694 wxEventType wxEVT_JOY_BUTTON_DOWN
;
4695 wxEventType wxEVT_JOY_BUTTON_UP
;
4696 wxEventType wxEVT_JOY_MOVE
;
4697 wxEventType wxEVT_JOY_ZMOVE
;
4698 wxEventType wxEVT_DROP_FILES
;
4699 wxEventType wxEVT_INIT_DIALOG
;
4700 wxEventType wxEVT_IDLE
;
4701 wxEventType wxEVT_UPDATE_UI
;
4702 wxEventType wxEVT_SIZING
;
4703 wxEventType wxEVT_MOVING
;
4704 wxEventType wxEVT_MOVE_START
;
4705 wxEventType wxEVT_MOVE_END
;
4706 wxEventType wxEVT_HIBERNATE
;
4707 wxEventType wxEVT_TEXT_COPY
;
4708 wxEventType wxEVT_TEXT_CUT
;
4709 wxEventType wxEVT_TEXT_PASTE
;
4710 wxEventType wxEVT_COMMAND_LEFT_CLICK
;
4711 wxEventType wxEVT_COMMAND_LEFT_DCLICK
;
4712 wxEventType wxEVT_COMMAND_RIGHT_CLICK
;
4713 wxEventType wxEVT_COMMAND_RIGHT_DCLICK
;
4714 wxEventType wxEVT_COMMAND_SET_FOCUS
;
4715 wxEventType wxEVT_COMMAND_KILL_FOCUS
;
4716 wxEventType wxEVT_COMMAND_ENTER
;
4717 wxEventType wxEVT_HELP
;
4718 wxEventType wxEVT_DETAILED_HELP
;
4719 wxEventType wxEVT_TOOL
;
4720 wxEventType wxEVT_WINDOW_MODAL_DIALOG_CLOSED
;