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