+/////////////////////////////////////////////////////////////////////////////
+// Name: interface/wx/event_base.h
+// Purpose: Documentation of wxEvtHandler, wxEvent, wxIdleEvent and other
+// non-GUI event-related classes declared in include/wx/event.h
+// (see interface/wx/event.h for the GUI event classes)
+// Author: wxWidgets team
+// RCS-ID: $Id$
+// Licence: wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+ The predefined constants for the number of times we propagate event
+ upwards window child-parent chain.
+*/
+enum wxEventPropagation
+{
+ /// don't propagate it at all
+ wxEVENT_PROPAGATE_NONE = 0,
+
+ /// propagate it until it is processed
+ wxEVENT_PROPAGATE_MAX = INT_MAX
+};
+
+/**
+ The different categories for a wxEvent; see wxEvent::GetEventCategory.
+
+ @note They are used as OR-combinable flags by wxEventLoopBase::YieldFor.
+*/
+enum wxEventCategory
+{
+ /**
+ This is the category for those events which are generated to update
+ the appearance of the GUI but which (usually) do not comport data
+ processing, i.e. which do not provide input or output data
+ (e.g. size events, scroll events, etc).
+ They are events NOT directly generated by the user's input devices.
+ */
+ wxEVT_CATEGORY_UI = 1,
+
+ /**
+ This category groups those events which are generated directly from the
+ user through input devices like mouse and keyboard and usually result in
+ data to be processed from the application
+ (e.g. mouse clicks, key presses, etc).
+ */
+ wxEVT_CATEGORY_USER_INPUT = 2,
+
+ /// This category is for wxSocketEvent
+ wxEVT_CATEGORY_SOCKET = 4,
+
+ /// This category is for wxTimerEvent
+ wxEVT_CATEGORY_TIMER = 8,
+
+ /**
+ This category is for any event used to send notifications from the
+ secondary threads to the main one or in general for notifications among
+ different threads (which may or may not be user-generated).
+ See e.g. wxThreadEvent.
+ */
+ wxEVT_CATEGORY_THREAD = 16,
+
+ /**
+ This mask is used in wxEventLoopBase::YieldFor to specify that all event
+ categories should be processed.
+ */
+ wxEVT_CATEGORY_ALL =
+ wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT|wxEVT_CATEGORY_SOCKET| \
+ wxEVT_CATEGORY_TIMER|wxEVT_CATEGORY_THREAD
+};
+
+/**
+ @class wxEvent
+
+ An event is a structure holding information about an event passed to a
+ callback or member function.
+
+ wxEvent used to be a multipurpose event object, and is an abstract base class
+ for other event classes (see below).
+
+ For more information about events, see the @ref overview_events overview.
+
+ @beginWxPerlOnly
+ In wxPerl custom event classes should be derived from
+ @c Wx::PlEvent and @c Wx::PlCommandEvent.
+ @endWxPerlOnly
+
+ @library{wxbase}
+ @category{events}
+ @header{wx/event.h}
+
+ @see wxCommandEvent, wxMouseEvent
+*/
+class wxEvent : public wxObject
+{
+public:
+ /**
+ Constructor.
+
+ Notice that events are usually created by wxWidgets itself and creating
+ e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl
+ will not usually affect it at all as native controls have no specific
+ knowledge about wxWidgets events. However you may construct objects of
+ specific types and pass them to wxEvtHandler::ProcessEvent() if you
+ want to create your own custom control and want to process its events
+ in the same manner as the standard ones.
+
+ Also please notice that the order of parameters in this constructor is
+ different from almost all the derived classes which specify the event
+ type as the first argument.
+
+ @param id
+ The identifier of the object (window, timer, ...) which generated
+ this event.
+ @param eventType
+ The unique type of event, e.g. @c wxEVT_PAINT, @c wxEVT_SIZE or
+ @c wxEVT_COMMAND_BUTTON_CLICKED.
+ */
+ wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL);
+
+ /**
+ Returns a copy of the event.
+
+ Any event that is posted to the wxWidgets event system for later action
+ (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent())
+ must implement this method.
+
+ All wxWidgets events fully implement this method, but any derived events
+ implemented by the user should also implement this method just in case they
+ (or some event derived from them) are ever posted.
+
+ All wxWidgets events implement a copy constructor, so the easiest way of
+ implementing the Clone function is to implement a copy constructor for
+ a new event (call it MyEvent) and then define the Clone function like this:
+
+ @code
+ wxEvent *Clone() const { return new MyEvent(*this); }
+ @endcode
+ */
+ virtual wxEvent* Clone() const = 0;
+
+ /**
+ Returns the object (usually a window) associated with the event, if any.
+ */
+ wxObject* GetEventObject() const;
+
+ /**
+ Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED.
+ */
+ wxEventType GetEventType() const;
+
+ /**
+ Returns a generic category for this event.
+ wxEvent implementation returns @c wxEVT_CATEGORY_UI by default.
+
+ This function is used to selectively process events in wxEventLoopBase::YieldFor.
+ */
+ virtual wxEventCategory GetEventCategory() const;
+
+ /**
+ Returns the identifier associated with this event, such as a button command id.
+ */
+ int GetId() const;
+
+ /**
+ Return the user data associated with a dynamically connected event handler.
+
+ wxEvtHandler::Connect() and wxEvtHandler::Bind() allow associating
+ optional @c userData pointer with the handler and this method returns
+ the value of this pointer.
+
+ The returned pointer is owned by wxWidgets and must not be deleted.
+
+ @since 2.9.5
+ */
+ wxObject *GetEventUserData() const;
+
+ /**
+ Returns @true if the event handler should be skipped, @false otherwise.
+ */
+ bool GetSkipped() const;
+
+ /**
+ Gets the timestamp for the event. The timestamp is the time in milliseconds
+ since some fixed moment (not necessarily the standard Unix Epoch, so only
+ differences between the timestamps and not their absolute values usually make sense).
+
+ @warning
+ wxWidgets returns a non-NULL timestamp only for mouse and key events
+ (see wxMouseEvent and wxKeyEvent).
+ */
+ long GetTimestamp() const;
+
+ /**
+ Returns @true if the event is or is derived from wxCommandEvent else it returns @false.
+
+ @note exists only for optimization purposes.
+ */
+ bool IsCommandEvent() const;
+
+ /**
+ Sets the propagation level to the given value (for example returned from an
+ earlier call to wxEvent::StopPropagation).
+ */
+ void ResumePropagation(int propagationLevel);
+
+ /**
+ Sets the originating object.
+ */
+ void SetEventObject(wxObject* object);
+
+ /**
+ Sets the event type.
+ */
+ void SetEventType(wxEventType type);
+
+ /**
+ Sets the identifier associated with this event, such as a button command id.
+ */
+ void SetId(int id);
+
+ /**
+ Sets the timestamp for the event.
+ */
+ void SetTimestamp(long timeStamp = 0);
+
+ /**
+ Test if this event should be propagated or not, i.e. if the propagation level
+ is currently greater than 0.
+ */
+ bool ShouldPropagate() const;
+
+ /**
+ This method can be used inside an event handler to control whether further
+ event handlers bound to this event will be called after the current one returns.
+
+ Without Skip() (or equivalently if Skip(@false) is used), the event will not
+ be processed any more. If Skip(@true) is called, the event processing system
+ continues searching for a further handler function for this event, even though
+ it has been processed already in the current handler.
+
+ In general, it is recommended to skip all non-command events to allow the
+ default handling to take place. The command events are, however, normally not
+ skipped as usually a single command such as a button click or menu item
+ selection must only be processed by one handler.
+ */
+ void Skip(bool skip = true);
+
+ /**
+ Stop the event from propagating to its parent window.
+
+ Returns the old propagation level value which may be later passed to
+ ResumePropagation() to allow propagating the event again.
+ */
+ int StopPropagation();
+
+protected:
+ /**
+ Indicates how many levels the event can propagate.
+
+ This member is protected and should typically only be set in the constructors
+ of the derived classes. It may be temporarily changed by StopPropagation()
+ and ResumePropagation() and tested with ShouldPropagate().
+
+ The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default)
+ meaning that the event shouldn't be propagated at all or to
+ @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be
+ propagated as much as necessary.
+
+ Any positive number means that the event should be propagated but no more than
+ the given number of times. E.g. the propagation level may be set to 1 to
+ propagate the event to its parent only, but not to its grandparent.
+ */
+ int m_propagationLevel;
+};
+
+
+
+
+/**
+ @class wxEvtHandler
+
+ A class that can handle events from the windowing system.
+ wxWindow is (and therefore all window classes are) derived from this class.
+
+ When events are received, wxEvtHandler invokes the method listed in the
+ event table using itself as the object. When using multiple inheritance
+ <b>it is imperative that the wxEvtHandler(-derived) class is the first
+ class inherited</b> such that the @c this pointer for the overall object
+ will be identical to the @c this pointer of the wxEvtHandler portion.
+
+ @library{wxbase}
+ @category{events}
+ @header{wx/event.h}
+
+ @see @ref overview_events_processing, wxEventBlocker, wxEventLoopBase
+*/
+class wxEvtHandler : public wxObject, public wxTrackable
+{
+public:
+ /**
+ Constructor.
+ */
+ wxEvtHandler();
+
+ /**
+ Destructor.
+
+ If the handler is part of a chain, the destructor will unlink itself
+ (see Unlink()).
+ */
+ virtual ~wxEvtHandler();
+
+
+ /**
+ @name Event queuing and processing
+ */
+ //@{
+
+ /**
+ Queue event for a later processing.
+
+ This method is similar to ProcessEvent() but while the latter is
+ synchronous, i.e. the event is processed immediately, before the
+ function returns, this one is asynchronous and returns immediately
+ while the event will be processed at some later time (usually during
+ the next event loop iteration).
+
+ Another important difference is that this method takes ownership of the
+ @a event parameter, i.e. it will delete it itself. This implies that
+ the event should be allocated on the heap and that the pointer can't be
+ used any more after the function returns (as it can be deleted at any
+ moment).
+
+ QueueEvent() can be used for inter-thread communication from the worker
+ threads to the main thread, it is safe in the sense that it uses
+ locking internally and avoids the problem mentioned in AddPendingEvent()
+ documentation by ensuring that the @a event object is not used by the
+ calling thread any more. Care should still be taken to avoid that some
+ fields of this object are used by it, notably any wxString members of
+ the event object must not be shallow copies of another wxString object
+ as this would result in them still using the same string buffer behind
+ the scenes. For example:
+ @code
+ void FunctionInAWorkerThread(const wxString& str)
+ {
+ wxCommandEvent* evt = new wxCommandEvent;
+
+ // NOT evt->SetString(str) as this would be a shallow copy
+ evt->SetString(str.c_str()); // make a deep copy
+
+ wxTheApp->QueueEvent( evt );
+ }
+ @endcode
+
+ Note that you can use wxThreadEvent instead of wxCommandEvent
+ to avoid this problem:
+ @code
+ void FunctionInAWorkerThread(const wxString& str)
+ {
+ wxThreadEvent evt;
+ evt->SetString(str);
+
+ // wxThreadEvent::Clone() makes sure that the internal wxString
+ // member is not shared by other wxString instances:
+ wxTheApp->QueueEvent( evt.Clone() );
+ }
+ @endcode
+
+ Finally notice that this method automatically wakes up the event loop
+ if it is currently idle by calling ::wxWakeUpIdle() so there is no need
+ to do it manually when using it.
+
+ @since 2.9.0
+
+ @param event
+ A heap-allocated event to be queued, QueueEvent() takes ownership
+ of it. This parameter shouldn't be @c NULL.
+ */
+ virtual void QueueEvent(wxEvent *event);
+
+ /**
+ Post an event to be processed later.
+
+ This function is similar to QueueEvent() but can't be used to post
+ events from worker threads for the event objects with wxString fields
+ (i.e. in practice most of them) because of an unsafe use of the same
+ wxString object which happens because the wxString field in the
+ original @a event object and its copy made internally by this function
+ share the same string buffer internally. Use QueueEvent() to avoid
+ this.
+
+ A copy of @a event is made by the function, so the original can be deleted
+ as soon as function returns (it is common that the original is created
+ on the stack). This requires that the wxEvent::Clone() method be
+ implemented by event so that it can be duplicated and stored until it
+ gets processed.
+
+ @param event
+ Event to add to the pending events queue.
+ */
+ virtual void AddPendingEvent(const wxEvent& event);
+
+ /**
+ Asynchronously call the given method.
+
+ Calling this function on an object schedules an asynchronous call to
+ the method specified as CallAfter() argument at a (slightly) later
+ time. This is useful when processing some events as certain actions
+ typically can't be performed inside their handlers, e.g. you shouldn't
+ show a modal dialog from a mouse click event handler as this would
+ break the mouse capture state -- but you can call a method showing
+ this message dialog after the current event handler completes.
+
+ The method being called must be the method of the object on which
+ CallAfter() itself is called.
+
+ Notice that it is safe to use CallAfter() from other, non-GUI,
+ threads, but that the method will be always called in the main, GUI,
+ thread context.
+
+ Example of use:
+ @code
+ class MyFrame : public wxFrame {
+ void OnClick(wxMouseEvent& event) {
+ CallAfter(&MyFrame::ShowPosition, event.GetPosition());
+ }
+
+ void ShowPosition(const wxPoint& pos) {
+ if ( wxMessageBox(
+ wxString::Format("Perform click at (%d, %d)?",
+ pos.x, pos.y), "", wxYES_NO) == wxYES )
+ {
+ ... do take this click into account ...
+ }
+ }
+ };
+ @endcode
+
+ @param method The method to call.
+ @param x1 The (optional) first parameter to pass to the method.
+ @param x2 The (optional) second parameter to pass to the method.
+
+ Note that currently only up to 2 arguments can be passed.
+
+ @note This method is not available with Visual C++ 6 which doesn't
+ have the required support for C++ templates to implement it.
+
+ @since 2.9.5
+ */
+ template<typename T, typename T1, ...>
+ void CallAfter(void (T::*method)(T1, ...), T1 x1, ...);
+
+ /**
+ Processes an event, searching event tables and calling zero or more suitable
+ event handler function(s).
+
+ Normally, your application would not call this function: it is called in the
+ wxWidgets implementation to dispatch incoming user interface events to the
+ framework (and application).
+
+ However, you might need to call it if implementing new functionality
+ (such as a new control) where you define new event types, as opposed to
+ allowing the user to override virtual functions.
+
+ Notice that you don't usually need to override ProcessEvent() to
+ customize the event handling, overriding the specially provided
+ TryBefore() and TryAfter() functions is usually enough. For example,
+ wxMDIParentFrame may override TryBefore() to ensure that the menu
+ events are processed in the active child frame before being processed
+ in the parent frame itself.
+
+ The normal order of event table searching is as follows:
+ -# wxApp::FilterEvent() is called. If it returns anything but @c -1
+ (default) the processing stops here.
+ -# TryBefore() is called (this is where wxValidator are taken into
+ account for wxWindow objects). If this returns @true, the function exits.
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (7).
+ -# Dynamic event table of the handlers bound using Bind<>() is
+ searched. If a handler is found, it is executed and the function
+ returns @true unless the handler used wxEvent::Skip() to indicate
+ that it didn't handle the event in which case the search continues.
+ -# Static events table of the handlers bound using event table
+ macros is searched for this event handler. If this fails, the base
+ class event table is tried, and so on until no more tables
+ exist or an appropriate function was found. If a handler is found,
+ the same logic as in the previous step applies.
+ -# The search is applied down the entire chain of event handlers (usually the
+ chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler():
+ @image html overview_events_chain.png
+ (referring to the image, if @c A->ProcessEvent is called and it doesn't handle
+ the event, @c B->ProcessEvent will be called and so on...).
+ Note that in the case of wxWindow you can build a stack of event handlers
+ (see wxWindow::PushEventHandler() for more info).
+ If any of the handlers of the chain return @true, the function exits.
+ -# TryAfter() is called: for the wxWindow object this may propagate the
+ event to the window parent (recursively). If the event is still not
+ processed, ProcessEvent() on wxTheApp object is called as the last
+ step.
+
+ Notice that steps (2)-(6) are performed in ProcessEventLocally()
+ which is called by this function.
+
+ @param event
+ Event to process.
+ @return
+ @true if a suitable event handler function was found and executed,
+ and the function did not call wxEvent::Skip.
+
+ @see SearchEventTable()
+ */
+ virtual bool ProcessEvent(wxEvent& event);
+
+ /**
+ Try to process the event in this handler and all those chained to it.
+
+ As explained in ProcessEvent() documentation, the event handlers may be
+ chained in a doubly-linked list. This function tries to process the
+ event in this handler (including performing any pre-processing done in
+ TryBefore(), e.g. applying validators) and all those following it in
+ the chain until the event is processed or the chain is exhausted.
+
+ This function is called from ProcessEvent() and, in turn, calls
+ TryBefore() and TryAfter(). It is not virtual and so cannot be
+ overridden but can, and should, be called to forward an event to
+ another handler instead of ProcessEvent() which would result in a
+ duplicate call to TryAfter(), e.g. resulting in all unprocessed events
+ being sent to the application object multiple times.
+
+ @since 2.9.1
+
+ @param event
+ Event to process.
+ @return
+ @true if this handler of one of those chained to it processed the
+ event.
+ */
+ bool ProcessEventLocally(wxEvent& event);
+
+ /**
+ Processes an event by calling ProcessEvent() and handles any exceptions
+ that occur in the process.
+ If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
+
+ @param event
+ Event to process.
+
+ @return @true if the event was processed, @false if no handler was found
+ or an exception was thrown.
+
+ @see wxWindow::HandleWindowEvent
+ */
+ bool SafelyProcessEvent(wxEvent& event);
+
+ /**
+ Processes the pending events previously queued using QueueEvent() or
+ AddPendingEvent(); you must call this function only if you are sure
+ there are pending events for this handler, otherwise a @c wxCHECK
+ will fail.
+
+ The real processing still happens in ProcessEvent() which is called by this
+ function.
+
+ Note that this function needs a valid application object (see
+ wxAppConsole::GetInstance()) because wxApp holds the list of the event
+ handlers with pending events and this function manipulates that list.
+ */
+ void ProcessPendingEvents();
+
+ /**
+ Deletes all events queued on this event handler using QueueEvent() or
+ AddPendingEvent().
+
+ Use with care because the events which are deleted are (obviously) not
+ processed and this may have unwanted consequences (e.g. user actions events
+ will be lost).
+ */
+ void DeletePendingEvents();
+
+ /**
+ Searches the event table, executing an event handler function if an appropriate
+ one is found.
+
+ @param table
+ Event table to be searched.
+ @param event
+ Event to be matched against an event table entry.
+
+ @return @true if a suitable event handler function was found and
+ executed, and the function did not call wxEvent::Skip.
+
+ @remarks This function looks through the object's event table and tries
+ to find an entry that will match the event.
+ An entry will match if:
+ @li The event type matches, and
+ @li the identifier or identifier range matches, or the event table
+ entry's identifier is zero.
+
+ If a suitable function is called but calls wxEvent::Skip, this
+ function will fail, and searching will continue.
+
+ @todo this function in the header is listed as an "implementation only" function;
+ are we sure we want to document it?
+
+ @see ProcessEvent()
+ */
+ virtual bool SearchEventTable(wxEventTable& table,
+ wxEvent& event);
+
+ //@}
+
+
+ /**
+ @name Connecting and disconnecting
+ */
+ //@{
+
+ /**
+ Connects the given function dynamically with the event handler, id and
+ event type.
+
+ Notice that Bind() provides a more flexible and safer way to do the
+ same thing as Connect(), please use it in any new code -- while
+ Connect() is not formally deprecated due to its existing widespread
+ usage, it has no advantages compared to Bind().
+
+ This is an alternative to the use of static event tables. It is more
+ flexible as it allows to connect events generated by some object to an
+ event handler defined in a different object of a different class (which
+ is impossible to do directly with the event tables -- the events can be
+ only handled in another object if they are propagated upwards to it).
+ Do make sure to specify the correct @a eventSink when connecting to an
+ event of a different object.
+
+ See @ref overview_events_bind for more detailed explanation
+ of this function and the @ref page_samples_event sample for usage
+ examples.
+
+ This specific overload allows you to connect an event handler to a @e range
+ of @e source IDs.
+ Do not confuse @e source IDs with event @e types: source IDs identify the
+ event generator objects (typically wxMenuItem or wxWindow objects) while the
+ event @e type identify which type of events should be handled by the
+ given @e function (an event generator object may generate many different
+ types of events!).
+
+ @param id
+ The first ID of the identifier range to be associated with the event
+ handler function.
+ @param lastId
+ The last ID of the identifier range to be associated with the event
+ handler function.
+ @param eventType
+ The event type to be associated with this event handler.
+ @param function
+ The event handler function. Note that this function should
+ be explicitly converted to the correct type which can be done using a macro
+ called @c wxFooEventHandler for the handler for any @c wxFooEvent.
+ @param userData
+ Optional data to be associated with the event table entry.
+ wxWidgets will take ownership of this pointer, i.e. it will be
+ destroyed when the event handler is disconnected or at the program
+ termination. This pointer can be retrieved using
+ wxEvent::GetEventUserData() later.
+ @param eventSink
+ Object whose member function should be called. It must be specified
+ when connecting an event generated by one object to a member
+ function of a different object. If it is omitted, @c this is used.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes 4 arguments: @a id, @a lastid,
+ @a type, @a method; if @a method is undef, the handler is
+ disconnected.}
+ @endWxPerlOnly
+
+ @see Bind<>()
+ */
+ void Connect(int id, int lastId, wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload can be used to attach an event handler to a single source ID:
+
+ Example:
+ @code
+ frame->Connect( wxID_EXIT,
+ wxEVT_COMMAND_MENU_SELECTED,
+ wxCommandEventHandler(MyFrame::OnQuit) );
+ @endcode
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ void Connect(int id, wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload will connect the given event handler so that regardless of the
+ ID of the event source, the handler will be called.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ void Connect(wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ Disconnects the given function dynamically from the event handler, using the
+ specified parameters as search criteria and returning @true if a matching
+ function has been found and removed.
+
+ This method can only disconnect functions which have been added using the
+ Connect() method. There is no way to disconnect functions connected using
+ the (static) event tables.
+
+ @param eventType
+ The event type associated with this event handler.
+ @param function
+ The event handler function.
+ @param userData
+ Data associated with the event table entry.
+ @param eventSink
+ Object whose member function should be called.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ bool Disconnect(wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload takes the additional @a id parameter.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ bool Disconnect(int id = wxID_ANY,
+ wxEventType eventType = wxEVT_NULL,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload takes an additional range of source IDs.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes 3 arguments: @a id,
+ @a lastid, @a type.
+ @endWxPerlOnly
+ */
+ bool Disconnect(int id, int lastId,
+ wxEventType eventType,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+ //@}
+
+
+ /**
+ @name Binding and Unbinding
+ */
+ //@{
+
+ /**
+ Binds the given function, functor or method dynamically with the event.
+
+ This offers basically the same functionality as Connect(), but it is
+ more flexible as it also allows you to use ordinary functions and
+ arbitrary functors as event handlers. It is also less restrictive then
+ Connect() because you can use an arbitrary method as an event handler,
+ whereas Connect() requires a wxEvtHandler derived handler.
+
+ See @ref overview_events_bind for more detailed explanation
+ of this function and the @ref page_samples_event sample for usage
+ examples.
+
+ @param eventType
+ The event type to be associated with this event handler.
+ @param functor
+ The event handler functor. This can be an ordinary function but also
+ an arbitrary functor like boost::function<>.
+ @param id
+ The first ID of the identifier range to be associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range to be associated with the event
+ handler.
+ @param userData
+ Optional data to be associated with the event table entry.
+ wxWidgets will take ownership of this pointer, i.e. it will be
+ destroyed when the event handler is disconnected or at the program
+ termination. This pointer can be retrieved using
+ wxEvent::GetEventUserData() later.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Functor>
+ void Bind(const EventTag& eventType,
+ Functor functor,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL);
+
+ /**
+ See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for
+ more info.
+
+ This overload will bind the given method as the event handler.
+
+ @param eventType
+ The event type to be associated with this event handler.
+ @param method
+ The event handler method. This can be an arbitrary method (doesn't need
+ to be from a wxEvtHandler derived class).
+ @param handler
+ Object whose method should be called. It must always be specified
+ so it can be checked at compile time whether the given method is an
+ actual member of the given handler.
+ @param id
+ The first ID of the identifier range to be associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range to be associated with the event
+ handler.
+ @param userData
+ Optional data to be associated with the event table entry.
+ wxWidgets will take ownership of this pointer, i.e. it will be
+ destroyed when the event handler is disconnected or at the program
+ termination. This pointer can be retrieved using
+ wxEvent::GetEventUserData() later.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
+ void Bind(const EventTag &eventType,
+ void (Class::*method)(EventArg &),
+ EventHandler *handler,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL);
+ /**
+ Unbinds the given function, functor or method dynamically from the
+ event handler, using the specified parameters as search criteria and
+ returning @true if a matching function has been found and removed.
+
+ This method can only unbind functions, functors or methods which have
+ been added using the Bind<>() method. There is no way to unbind
+ functions bound using the (static) event tables.
+
+ @param eventType
+ The event type associated with this event handler.
+ @param functor
+ The event handler functor. This can be an ordinary function but also
+ an arbitrary functor like boost::function<>.
+ @param id
+ The first ID of the identifier range associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range associated with the event
+ handler.
+ @param userData
+ Data associated with the event table entry.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Functor>
+ bool Unbind(const EventTag& eventType,
+ Functor functor,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL);
+
+ /**
+ See the Unbind<>(const EventTag&, Functor, int, int, wxObject*)
+ overload for more info.
+
+ This overload unbinds the given method from the event..
+
+ @param eventType
+ The event type associated with this event handler.
+ @param method
+ The event handler method associated with this event.
+ @param handler
+ Object whose method was called.
+ @param id
+ The first ID of the identifier range associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range associated with the event
+ handler.
+ @param userData
+ Data associated with the event table entry.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
+ bool Unbind(const EventTag &eventType,
+ void (Class::*method)(EventArg&),
+ EventHandler *handler,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL );
+ //@}
+ /**
+ @name User-supplied data
+ */
+ //@{
+
+ /**
+ Returns user-supplied client data.
+
+ @remarks Normally, any extra data the programmer wishes to associate with
+ the object should be made available by deriving a new class with
+ new data members.
+
+ @see SetClientData()
+ */
+ void* GetClientData() const;
+
+ /**
+ Returns a pointer to the user-supplied client data object.
+
+ @see SetClientObject(), wxClientData
+ */
+ wxClientData* GetClientObject() const;
+
+ /**
+ Sets user-supplied client data.
+
+ @param data
+ Data to be associated with the event handler.
+
+ @remarks Normally, any extra data the programmer wishes to associate
+ with the object should be made available by deriving a new
+ class with new data members. You must not call this method
+ and SetClientObject on the same class - only one of them.
+
+ @see GetClientData()
+ */
+ void SetClientData(void* data);
+
+ /**
+ Set the client data object. Any previous object will be deleted.
+
+ @see GetClientObject(), wxClientData
+ */
+ void SetClientObject(wxClientData* data);
+
+ //@}
+
+
+ /**
+ @name Event handler chaining
+
+ wxEvtHandler can be arranged in a double-linked list of handlers
+ which is automatically iterated by ProcessEvent() if needed.
+ */
+ //@{
+
+ /**
+ Returns @true if the event handler is enabled, @false otherwise.
+
+ @see SetEvtHandlerEnabled()
+ */
+ bool GetEvtHandlerEnabled() const;
+
+ /**
+ Returns the pointer to the next handler in the chain.
+
+ @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetNextHandler() const;
+
+ /**
+ Returns the pointer to the previous handler in the chain.
+
+ @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetPreviousHandler() const;
+
+ /**
+ Enables or disables the event handler.
+
+ @param enabled
+ @true if the event handler is to be enabled, @false if it is to be disabled.
+
+ @remarks You can use this function to avoid having to remove the event
+ handler from the chain, for example when implementing a
+ dialog editor and changing from edit to test mode.
+
+ @see GetEvtHandlerEnabled()
+ */
+ void SetEvtHandlerEnabled(bool enabled);
+
+ /**
+ Sets the pointer to the next handler.
+
+ @remarks
+ See ProcessEvent() for more info about how the chains of event handlers
+ are internally used.
+ Also remember that wxEvtHandler uses double-linked lists and thus if you
+ use this function, you should also call SetPreviousHandler() on the
+ argument passed to this function:
+ @code
+ handlerA->SetNextHandler(handlerB);
+ handlerB->SetPreviousHandler(handlerA);
+ @endcode
+
+ @param handler
+ The event handler to be set as the next handler.
+ Cannot be @NULL.
+
+ @see @ref overview_events_processing
+ */
+ virtual void SetNextHandler(wxEvtHandler* handler);
+
+ /**
+ Sets the pointer to the previous handler.
+ All remarks about SetNextHandler() apply to this function as well.
+
+ @param handler
+ The event handler to be set as the previous handler.
+ Cannot be @NULL.
+
+ @see @ref overview_events_processing
+ */
+ virtual void SetPreviousHandler(wxEvtHandler* handler);
+
+ /**
+ Unlinks this event handler from the chain it's part of (if any);
+ then links the "previous" event handler to the "next" one
+ (so that the chain won't be interrupted).
+
+ E.g. if before calling Unlink() you have the following chain:
+ @image html evthandler_unlink_before.png
+ then after calling @c B->Unlink() you'll have:
+ @image html evthandler_unlink_after.png
+
+ @since 2.9.0
+ */
+ void Unlink();
+
+ /**
+ Returns @true if the next and the previous handler pointers of this
+ event handler instance are @NULL.
+
+ @since 2.9.0
+
+ @see SetPreviousHandler(), SetNextHandler()
+ */
+ bool IsUnlinked() const;
+
+ //@}
+
+ /**
+ @name Global event filters.
+
+ Methods for working with the global list of event filters.
+
+ Event filters can be defined to pre-process all the events that happen
+ in an application, see wxEventFilter documentation for more information.
+ */
+ //@{
+
+ /**
+ Add an event filter whose FilterEvent() method will be called for each
+ and every event processed by wxWidgets.
+
+ The filters are called in LIFO order and wxApp is registered as an
+ event filter by default. The pointer must remain valid until it's
+ removed with RemoveFilter() and is not deleted by wxEvtHandler.
+
+ @since 2.9.3
+ */
+ static void AddFilter(wxEventFilter* filter);
+
+ /**
+ Remove a filter previously installed with AddFilter().
+
+ It's an error to remove a filter that hadn't been previously added or
+ was already removed.
+
+ @since 2.9.3
+ */
+ static void RemoveFilter(wxEventFilter* filter);
+
+ //@}
+
+protected:
+ /**
+ Method called by ProcessEvent() before examining this object event
+ tables.
+
+ This method can be overridden to hook into the event processing logic
+ as early as possible. You should usually call the base class version
+ when overriding this method, even if wxEvtHandler itself does nothing
+ here, some derived classes do use this method, e.g. wxWindow implements
+ support for wxValidator in it.
+
+ Example:
+ @code
+ class MyClass : public BaseClass // inheriting from wxEvtHandler
+ {
+ ...
+ protected:
+ virtual bool TryBefore(wxEvent& event)
+ {
+ if ( MyPreProcess(event) )
+ return true;
+
+ return BaseClass::TryBefore(event);
+ }
+ };
+ @endcode
+
+ @see ProcessEvent()
+ */
+ virtual bool TryBefore(wxEvent& event);
+
+ /**
+ Method called by ProcessEvent() as last resort.
+
+ This method can be overridden to implement post-processing for the
+ events which were not processed anywhere else.
+
+ The base class version handles forwarding the unprocessed events to
+ wxApp at wxEvtHandler level and propagating them upwards the window
+ child-parent chain at wxWindow level and so should usually be called
+ when overriding this method:
+ @code
+ class MyClass : public BaseClass // inheriting from wxEvtHandler
+ {
+ ...
+ protected:
+ virtual bool TryAfter(wxEvent& event)
+ {
+ if ( BaseClass::TryAfter(event) )
+ return true;
+
+ return MyPostProcess(event);
+ }
+ };
+ @endcode
+
+ @see ProcessEvent()
+ */
+ virtual bool TryAfter(wxEvent& event);
+};
+
+
+
+/**
+ See wxIdleEvent::SetMode() for more info.
+*/
+enum wxIdleMode
+{
+ /** Send idle events to all windows */
+ wxIDLE_PROCESS_ALL,
+
+ /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */
+ wxIDLE_PROCESS_SPECIFIED
+};
+
+
+/**
+ @class wxIdleEvent
+
+ This class is used for idle events, which are generated when the system becomes
+ idle. Note that, unless you do something specifically, the idle events are not
+ sent if the system remains idle once it has become it, e.g. only a single idle
+ event will be generated until something else resulting in more normal events
+ happens and only then is the next idle event sent again.
+
+ If you need to ensure a continuous stream of idle events, you can either use
+ wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically
+ (for example from a timer event handler), but note that both of these approaches
+ (and especially the first one) increase the system load and so should be avoided
+ if possible.
+
+ By default, idle events are sent to all windows, including even the hidden
+ ones because they may be shown if some condition is met from their @c
+ wxEVT_IDLE (or related @c wxEVT_UPDATE_UI) handler. The children of hidden
+ windows do not receive idle events however as they can't change their state
+ in any way noticeable by the user. Finally, the global wxApp object also
+ receives these events, as usual, so it can be used for any global idle time
+ processing.
+
+ If sending idle events to all windows is causing a significant overhead in
+ your application, you can call wxIdleEvent::SetMode with the value
+ wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra window
+ style for every window which should receive idle events, all the other ones
+ will not receive them in this case.
+
+ @beginEventTable{wxIdleEvent}
+ @event{EVT_IDLE(func)}
+ Process a @c wxEVT_IDLE event.
+ @endEventTable
+
+ @library{wxbase}
+ @category{events}
+ @header{wx/event.h}
+
+ @section sec_delayed_action Delayed Action Mechanism
+
+ wxIdleEvent can be used to perform some action "at slightly later time".
+ This can be necessary in several circumstances when, for whatever reason,
+ something can't be done in the current event handler. For example, if a
+ mouse event handler is called with the mouse button pressed, the mouse can
+ be currently captured and some operations with it -- notably capturing it
+ again -- might be impossible or lead to undesirable results. If you still
+ want to capture it, you can do it from @c wxEVT_IDLE handler when it is
+ called the next time instead of doing it immediately.
+
+ This can be achieved in two different ways: when using static event tables,
+ you will need a flag indicating to the (always connected) idle event
+ handler whether the desired action should be performed. The originally
+ called handler would then set it to indicate that it should indeed be done
+ and the idle handler itself would reset it to prevent it from doing the
+ same action again.
+
+ Using dynamically connected event handlers things are even simpler as the
+ original event handler can simply wxEvtHandler::Connect() or
+ wxEvtHandler::Bind() the idle event handler which would only be executed
+ then and could wxEvtHandler::Disconnect() or wxEvtHandler::Unbind() itself.
+
+
+ @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle
+*/
+class wxIdleEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxIdleEvent();
+
+ /**
+ Static function returning a value specifying how wxWidgets will send idle
+ events: to all windows, or only to those which specify that they
+ will process the events.
+
+ @see SetMode().
+ */
+ static wxIdleMode GetMode();
+
+ /**
+ Returns @true if the OnIdle function processing this event requested more
+ processing time.
+
+ @see RequestMore()
+ */
+ bool MoreRequested() const;
+
+ /**
+ Tells wxWidgets that more processing is required.
+
+ This function can be called by an OnIdle handler for a window or window event
+ handler to indicate that wxApp::OnIdle should forward the OnIdle event once
+ more to the application windows.
+
+ If no window calls this function during OnIdle, then the application will
+ remain in a passive event loop (not calling OnIdle) until a new event is
+ posted to the application by the windowing system.
+
+ @see MoreRequested()
+ */
+ void RequestMore(bool needMore = true);
+
+ /**
+ Static function for specifying how wxWidgets will send idle events: to
+ all windows, or only to those which specify that they will process the events.
+
+ @param mode
+ Can be one of the ::wxIdleMode values.
+ The default is wxIDLE_PROCESS_ALL.
+ */
+ static void SetMode(wxIdleMode mode);
+};
+
+
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
+/** @addtogroup group_funcmacro_events */
+//@{
+
+/**
+ A value uniquely identifying the type of the event.
+
+ The values of this type should only be created using wxNewEventType().
+
+ See the macro DEFINE_EVENT_TYPE() for more info.
+
+ @see @ref overview_events_introduction
+*/
+typedef int wxEventType;
+
+/**
+ A special event type usually used to indicate that some wxEvent has yet
+ no type assigned.
+*/
+wxEventType wxEVT_NULL;
+
+wxEventType wxEVT_ANY;
+
+/**
+ Generates a new unique event type.
+
+ Usually this function is only used by wxDEFINE_EVENT() and not called
+ directly.
+*/
+wxEventType wxNewEventType();
+
+/**
+ Define a new event type associated with the specified event class.
+
+ This macro defines a new unique event type @a name associated with the
+ event class @a cls.
+
+ For example:
+ @code
+ wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
+
+ class MyCustomEvent : public wxEvent { ... };
+ wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
+ @endcode
+
+ @see wxDECLARE_EVENT(), @ref overview_events_custom
+ */
+#define wxDEFINE_EVENT(name, cls) \
+ const wxEventTypeTag< cls > name(wxNewEventType())
+
+/**
+ Declares a custom event type.
+
+ This macro declares a variable called @a name which must be defined
+ elsewhere using wxDEFINE_EVENT().
+
+ The class @a cls must be the wxEvent-derived class associated with the
+ events of this type and its full declaration must be visible from the point
+ of use of this macro.
+
+ For example:
+ @code
+ wxDECLARE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
+
+ class MyCustomEvent : public wxEvent { ... };
+ wxDECLARE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
+ @endcode
+ */
+#define wxDECLARE_EVENT(name, cls) \
+ wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls)
+
+/**
+ Variant of wxDECLARE_EVENT() used for event types defined inside a shared
+ library.
+
+ This is mostly used by wxWidgets internally, e.g.
+ @code
+ wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_COMMAND_BUTTON_CLICKED, wxCommandEvent)
+ @endcode
+ */
+#define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \
+ extern const expdecl wxEventTypeTag< cls > name;
+
+/**
+ Helper macro for definition of custom event table macros.
+
+ This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise
+ it is better and more clear to just use the address of the function
+ directly as this is all this macro does in this case. However it needs to
+ explicitly cast @a func to @a functype, which is the type of wxEvtHandler
+ member function taking the custom event argument when
+ wxEVENTS_COMPATIBILITY_2_8 is 0.
+
+ See wx__DECLARE_EVT0 for an example of use.
+
+ @see @ref overview_events_custom_ownclass
+ */
+#define wxEVENT_HANDLER_CAST(functype, func) (&func)
+
+/**
+ This macro is used to define event table macros for handling custom
+ events.
+
+ Example of use:
+ @code
+ class MyEvent : public wxEvent { ... };
+
+ // note that this is not necessary unless using old compilers: for the
+ // reasonably new ones just use &func instead of MyEventHandler(func)
+ typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&);
+ #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func)
+
+ wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent);
+
+ #define EVT_MY(id, func) \
+ wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func))
+
+ ...
+
+ wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+ EVT_MY(wxID_ANY, MyFrame::OnMyEvent)
+ wxEND_EVENT_TABLE()
+ @endcode
+
+ @param evt
+ The event type to handle.
+ @param id
+ The identifier of events to handle.
+ @param fn
+ The event handler method.
+ */
+#define wx__DECLARE_EVT1(evt, id, fn) \
+ wx__DECLARE_EVT2(evt, id, wxID_ANY, fn)
+
+/**
+ Generalized version of the wx__DECLARE_EVT1() macro taking a range of
+ IDs instead of a single one.
+ Argument @a id1 is the first identifier of the range, @a id2 is the
+ second identifier of the range.
+*/
+#define wx__DECLARE_EVT2(evt, id1, id2, fn) \
+ DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
+
+/**
+ Simplified version of the wx__DECLARE_EVT1() macro, to be used when the
+ event type must be handled regardless of the ID associated with the
+ specific event instances.
+*/
+#define wx__DECLARE_EVT0(evt, fn) \
+ wx__DECLARE_EVT1(evt, wxID_ANY, fn)
+
+/**
+ Use this macro inside a class declaration to declare a @e static event table
+ for that class.
+
+ In the implementation file you'll need to use the wxBEGIN_EVENT_TABLE()
+ and the wxEND_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro
+ to capture events.
+
+ Note that this macro requires a final semicolon.
+
+ @see @ref overview_events_eventtables
+*/
+#define wxDECLARE_EVENT_TABLE()
+
+/**
+ Use this macro in a source file to start listing @e static event handlers
+ for a specific class.
+
+ Use wxEND_EVENT_TABLE() to terminate the event-declaration block.
+
+ @see @ref overview_events_eventtables
+*/
+#define wxBEGIN_EVENT_TABLE(theClass, baseClass)
+
+/**
+ Use this macro in a source file to end listing @e static event handlers
+ for a specific class.
+
+ Use wxBEGIN_EVENT_TABLE() to start the event-declaration block.
+
+ @see @ref overview_events_eventtables
+*/
+#define wxEND_EVENT_TABLE()
+
+/**
+ In a GUI application, this function posts @a event to the specified @e dest
+ object using wxEvtHandler::AddPendingEvent().
+
+ Otherwise, it dispatches @a event immediately using
+ wxEvtHandler::ProcessEvent(). See the respective documentation for details
+ (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent()
+ this function is not thread-safe for event objects having wxString fields,
+ use wxQueueEvent() instead.
+
+ @header{wx/event.h}
+*/
+void wxPostEvent(wxEvtHandler* dest, const wxEvent& event);
+
+/**
+ Queue an event for processing on the given object.
+
+ This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation
+ for more details.
+
+ @header{wx/event.h}
+
+ @param dest
+ The object to queue the event on, can't be @c NULL.
+ @param event
+ The heap-allocated and non-@c NULL event to queue, the function takes
+ ownership of it.
+ */
+void wxQueueEvent(wxEvtHandler* dest, wxEvent *event);
+
+
+//@}
projects / wxWidgets.git / commitdiff
