From 71abf17edb285a2a028b473e723cd52f79d1fb29 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Mon, 29 Oct 2012 15:15:33 +0000 Subject: [PATCH] Split documentation of non-GUI wxEvent-related classes. Separate GUI from base classes to make it easier to generate wrappers for just the latter using e.g. SWIG. Closes #14785. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72817 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/event.h | 1624 ++----------------------------------- interface/wx/event_base.h | 1535 +++++++++++++++++++++++++++++++++++ 2 files changed, 1594 insertions(+), 1565 deletions(-) create mode 100644 interface/wx/event_base.h diff --git a/interface/wx/event.h b/interface/wx/event.h index 237e8480e8..6c0a98695c 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -1,1264 +1,96 @@ ///////////////////////////////////////////////////////////////////////////// // Name: event.h -// Purpose: interface of wxEvtHandler, wxEventBlocker and many -// wxEvent-derived classes +// Purpose: interface of wxEvent-derived classes, +// see event_base.h for wxEvtHandler and wxEvent. // 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} - - @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 wxEventBlocker - - This class is a special event handler which allows to discard - any event (or a set of event types) directed to a specific window. - - Example: - - @code - void MyWindow::DoSomething() - { - { - // block all events directed to this window while - // we do the 1000 FunctionWhichSendsEvents() calls - wxEventBlocker blocker(this); - - for ( int i = 0; i 1000; i++ ) - FunctionWhichSendsEvents(i); - - } // ~wxEventBlocker called, old event handler is restored - - // the event generated by this call will be processed: - FunctionWhichSendsEvents(0) - } - @endcode - - @library{wxcore} - @category{events} - - @see @ref overview_events_processing, wxEvtHandler -*/ -class wxEventBlocker : public wxEvtHandler -{ -public: - /** - Constructs the blocker for the given window and for the given event type. - - If @a type is @c wxEVT_ANY, then all events for that window are blocked. - You can call Block() after creation to add other event types to the list - of events to block. - - Note that the @a win window @b must remain alive until the - wxEventBlocker object destruction. - */ - wxEventBlocker(wxWindow* win, wxEventType type = -1); - - /** - Destructor. The blocker will remove itself from the chain of event handlers for - the window provided in the constructor, thus restoring normal processing of events. - */ - virtual ~wxEventBlocker(); - - /** - Adds to the list of event types which should be blocked the given @a eventType. - */ - void Block(wxEventType eventType); -}; - - - -/** - Helper class to temporarily change an event to not propagate. -*/ -class wxPropagationDisabler -{ -public: - wxPropagationDisabler(wxEvent& event); - ~wxPropagationDisabler(); -}; - - -/** - Helper class to temporarily lower propagation level. -*/ -class wxPropagateOnce -{ -public: - wxPropagateOnce(wxEvent& event); - ~wxPropagateOnce(); -}; - - - -/** - @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 - it is imperative that the wxEvtHandler(-derived) class is the first - class inherited 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} - - @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 - 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 - 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 - 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 - 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 - 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. +/** + @class wxEventBlocker - @param enabled - @true if the event handler is to be enabled, @false if it is to be disabled. + This class is a special event handler which allows to discard + any event (or a set of event types) directed to a specific window. - @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. + Example: - @see GetEvtHandlerEnabled() - */ - void SetEvtHandlerEnabled(bool enabled); + @code + void MyWindow::DoSomething() + { + { + // block all events directed to this window while + // we do the 1000 FunctionWhichSendsEvents() calls + wxEventBlocker blocker(this); - /** - Sets the pointer to the next handler. + for ( int i = 0; i 1000; i++ ) + FunctionWhichSendsEvents(i); - @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 + } // ~wxEventBlocker called, old event handler is restored - @param handler - The event handler to be set as the next handler. - Cannot be @NULL. + // the event generated by this call will be processed: + FunctionWhichSendsEvents(0) + } + @endcode - @see @ref overview_events_processing - */ - virtual void SetNextHandler(wxEvtHandler* handler); + @library{wxcore} + @category{events} + @see @ref overview_events_processing, wxEvtHandler +*/ +class wxEventBlocker : public wxEvtHandler +{ +public: /** - Sets the pointer to the previous handler. - All remarks about SetNextHandler() apply to this function as well. + Constructs the blocker for the given window and for the given event type. - @param handler - The event handler to be set as the previous handler. - Cannot be @NULL. + If @a type is @c wxEVT_ANY, then all events for that window are blocked. + You can call Block() after creation to add other event types to the list + of events to block. - @see @ref overview_events_processing + Note that the @a win window @b must remain alive until the + wxEventBlocker object destruction. */ - virtual void SetPreviousHandler(wxEvtHandler* handler); + wxEventBlocker(wxWindow* win, wxEventType type = -1); /** - 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 + Destructor. The blocker will remove itself from the chain of event handlers for + the window provided in the constructor, thus restoring normal processing of events. */ - void Unlink(); + virtual ~wxEventBlocker(); /** - Returns @true if the next and the previous handler pointers of this - event handler instance are @NULL. - - @since 2.9.0 - - @see SetPreviousHandler(), SetNextHandler() + Adds to the list of event types which should be blocked the given @a eventType. */ - 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); + void Block(wxEventType eventType); +}; - /** - 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; +/** + Helper class to temporarily change an event to not propagate. +*/ +class wxPropagationDisabler +{ +public: + wxPropagationDisabler(wxEvent& event); + ~wxPropagationDisabler(); +}; - return MyPostProcess(event); - } - }; - @endcode - @see ProcessEvent() - */ - virtual bool TryAfter(wxEvent& event); +/** + Helper class to temporarily lower propagation level. +*/ +class wxPropagateOnce +{ +public: + wxPropagateOnce(wxEvent& event); + ~wxPropagateOnce(); }; + /** Flags for categories of keys. @@ -3544,132 +2376,6 @@ public: void SetPosition(int pos); }; -/** - 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} - - @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); -}; @@ -4308,218 +3014,6 @@ public: /** @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); - - wxEventType wxEVT_COMMAND_BUTTON_CLICKED; wxEventType wxEVT_COMMAND_CHECKBOX_CLICKED; diff --git a/interface/wx/event_base.h b/interface/wx/event_base.h new file mode 100644 index 0000000000..536b013024 --- /dev/null +++ b/interface/wx/event_base.h @@ -0,0 +1,1535 @@ +///////////////////////////////////////////////////////////////////////////// +// 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 + it is imperative that the wxEvtHandler(-derived) class is the first + class inherited 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 + 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 + 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 + 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 + 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 + 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); + + +//@} -- 2.45.2