Returns a copy of the event.
Any event that is posted to the wxWidgets event system for later action
- (via wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement
- this method.
+ (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
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.
+ @name Event handler chaining
- @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
+ 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
*/
- void SetPreviousHandler(wxEvtHandler* handler);
+ 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;
+
+ //@}
};
Constructor.
*/
wxWindowCreateEvent(wxWindow* win = NULL);
+
+ /// Retutn the window being created.
+ wxWindow *GetWindow() const;
};
parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
mouse leaves the window entirely but also when it enters one of its children.
+ The position associated with a mouse event is expressed in the window
+ coordinates of the window which generated the event, you can use
+ wxWindow::ClientToScreen() to convert it to screen coordinates and possibly
+ call wxWindow::ScreenToClient() next to convert it to window coordinates of
+ another window.
+
@note Note that under Windows CE mouse enter and leave events are not natively
supported by the system but are generated by wxWidgets itself. This has several
drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
/**
@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.
+
+ 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.
- 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 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).
- 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.
+ 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;
};
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_events */
+/** @addtogroup group_funcmacro_events */
//@{
+/**
+ A special event type usually used to indicate that some wxEvent has yet
+ no type assigned.
+*/
+wxEventType wxEVT_NULL;
+
/**
Each wxEvent-derived class has an @e event-type associated.
See the macro DEFINE_EVENT_TYPE() for more info.
projects / wxWidgets.git / blobdiff