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
+ 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.
/**
Destructor.
- If the handler is part of a chain, the destructor will unlink itself and
- restore the previous and next handlers so that they point to each other.
+ 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.
*/
virtual void AddPendingEvent(const wxEvent& event);
+ /**
+ 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.
+
+ An instance where you might actually override the ProcessEvent() function is where
+ you want to direct event processing to event handlers not normally noticed by
+ wxWidgets. For example, in the document/view architecture, documents and views
+ are potential event handlers. When an event reaches a frame, ProcessEvent() will
+ need to be called on the associated document and view in case event handler functions
+ are associated with these objects. The property classes library (wxProperty) also
+ overrides ProcessEvent() for similar reasons.
+
+ The normal order of event table searching is as follows:
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (6).
+ -# If the object is a wxWindow, ProcessEvent() is recursively called on the
+ window's wxValidator. If this returns @true, the function exits.
+ -# SearchEventTable() is called for this event handler. If this fails, the base
+ class table is tried, and so on until no more tables exist or an appropriate
+ function was found, in which case the function exits.
+ -# 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_eventhandling_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.
+ -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
+ is recursively applied to the parent window's event handler.
+ If this returns @true, the function exits.
+ -# Finally, ProcessEvent() is called on the wxApp object.
+
+ @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);
+
+ /**
+ 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);
+
+ /**
+ 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.
+
+ @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.
This is an alternative to the use of static event tables.
wxObjectEventFunction function = NULL,
wxObject* userData = NULL,
wxEvtHandler* eventSink = NULL);
+ //@}
+
+
+ /**
+ @name User-supplied data
+ */
+ //@{
/**
Returns user-supplied client data.
wxClientData* GetClientObject() const;
/**
- Returns @true if the event handler is enabled, @false otherwise.
+ Sets user-supplied client data.
- @see SetEvtHandlerEnabled()
- */
- bool GetEvtHandlerEnabled() const;
+ @param data
+ Data to be associated with the event handler.
- /**
- Returns the pointer to the next handler in the chain.
+ @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 SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
- wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ @see GetClientData()
*/
- wxEvtHandler* GetNextHandler() const;
+ void SetClientData(void* data);
/**
- Returns the pointer to the previous handler in the chain.
+ Set the client data object. Any previous object will be deleted.
- @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
- wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ @see GetClientObject(), wxClientData
*/
- wxEvtHandler* GetPreviousHandler() const;
-
- /**
- 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.
-
- An instance where you might actually override the ProcessEvent() function is where
- you want to direct event processing to event handlers not normally noticed by
- wxWidgets. For example, in the document/view architecture, documents and views
- are potential event handlers. When an event reaches a frame, ProcessEvent() will
- need to be called on the associated document and view in case event handler functions
- are associated with these objects. The property classes library (wxProperty) also
- overrides ProcessEvent() for similar reasons.
-
- The normal order of event table searching is as follows:
- -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
- the function skips to step (6).
- -# If the object is a wxWindow, ProcessEvent() is recursively called on the
- window's wxValidator. If this returns @true, the function exits.
- -# SearchEventTable() is called for this event handler. If this fails, the base
- class table is tried, and so on until no more tables exist or an appropriate
- function was found, in which case the function exits.
- -# The search is applied down the entire chain of event handlers (usually the
- chain has a length of one). If this succeeds, the function exits.
- -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
- is recursively applied to the parent window's event handler.
- If this returns true, the function exits.
- -# Finally, ProcessEvent() is called on the wxApp object.
-
- @param event
- Event to process.
+ void SetClientObject(wxClientData* data);
- @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);
/**
- 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.
+ @name Event handler chaining
- @see wxWindow::HandleWindowEvent
+ wxEvtHandler can be arranged in a double-linked list of handlers
+ which is automatically iterated by ProcessEvent() if needed.
*/
- bool SafelyProcessEvent(wxEvent& event);
+ //@{
/**
- 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.
+ Returns @true if the event handler is enabled, @false otherwise.
- @see ProcessEvent()
+ @see SetEvtHandlerEnabled()
*/
- virtual bool SearchEventTable(wxEventTable& table,
- wxEvent& event);
+ bool GetEvtHandlerEnabled() 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.
+ Returns the pointer to the next handler in the chain.
- @see GetClientData()
+ @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
*/
- void SetClientData(void* data);
+ wxEvtHandler* GetNextHandler() const;
/**
- Set the client data object. Any previous object will be deleted.
+ Returns the pointer to the previous handler in the chain.
- @see GetClientObject(), wxClientData
+ @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
*/
- void SetClientObject(wxClientData* data);
+ wxEvtHandler* GetPreviousHandler() const;
/**
Enables or disables the event handler.
/**
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
- Event handler to be set as the next handler.
+ The event handler to be set as the next handler.
+ Cannot be @NULL.
- @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(),
- wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ @see @ref overview_eventhandling_processing
*/
- void SetNextHandler(wxEvtHandler* handler);
+ virtual void SetNextHandler(wxEvtHandler* handler);
/**
Sets the pointer to the previous handler.
+ All remarks about SetNextHandler() apply to this function as well.
@param handler
- Event handler to be set as the previous handler.
+ The event handler to be set as the previous handler.
+ Cannot be @NULL.
+
+ @see @ref overview_eventhandling_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()
*/
- void SetPreviousHandler(wxEvtHandler* handler);
+ bool IsUnlinked() const;
+
+ //@}
};
Constructor.
*/
wxWindowCreateEvent(wxWindow* win = NULL);
+
+ /// Retutn the window being created.
+ wxWindow *GetWindow() const;
};
/**
@class wxWindowDestroyEvent
- This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a
- window is destroyed.
+ This event is sent as early as possible during the window destruction
+ process.
- When a class derived from wxWindow is destroyed its destructor will have
- already run by the time this event is sent. Therefore this event will not
- usually be received at all.
+ For the top level windows, as early as possible means that this is done by
+ wxFrame or wxDialog destructor, i.e. after the destructor of the derived
+ class was executed and so any methods specific to the derived class can't
+ be called any more from this event handler. If you need to do this, you
+ must call wxWindow::SendDestroyEvent() from your derived class destructor.
- To receive this event wxEvtHandler::Connect() must be used (using an event
- table macro will not work). Since it is received after the destructor has run,
- an object should not handle its own wxWindowDestroyEvent, but it can be used
- to get notification of the destruction of another window.
+ For the child windows, this event is generated just before deleting the
+ window from wxWindow::Destroy() (which is also called when the parent
+ window is deleted) or from the window destructor if operator @c delete was
+ used directly (which is not recommended for this very reason).
+
+ It is usually pointless to handle this event in the window itself but it ca
+ be very useful to receive notifications about the window destruction in the
+ parent window or in any other object interested in this window.
@library{wxcore}
@category{events}
Constructor.
*/
wxWindowDestroyEvent(wxWindow* win = NULL);
+
+ /// Retutn the window being destroyed.
+ wxWindow *GetWindow() const;
};
projects / wxWidgets.git / blobdiff