X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b21126db7a8232fa9e64b29f916d73d6b0153bef..d8efd2198ff050ca5a5726bcad0f42692fe872df:/interface/wx/event.h diff --git a/interface/wx/event.h b/interface/wx/event.h index 5a4a49bc2f..8f76631f11 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -284,6 +284,12 @@ public: */ virtual ~wxEvtHandler(); + + /** + @name Event queuing and processing + */ + //@{ + /** Queue event for a later processing. @@ -354,6 +360,101 @@ public: */ 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). 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. + + @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. @@ -467,6 +568,13 @@ public: wxObjectEventFunction function = NULL, wxObject* userData = NULL, wxEvtHandler* eventSink = NULL); + //@} + + + /** + @name User-supplied data + */ + //@{ /** Returns user-supplied client data. @@ -487,136 +595,57 @@ public: 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. - - @see wxWindow::HandleWindowEvent + @name Event handler chain */ - 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. @@ -650,6 +679,8 @@ public: Event handler to be set as the previous handler. */ void SetPreviousHandler(wxEvtHandler* handler); + + //@} }; @@ -1030,6 +1061,9 @@ public: Constructor. */ wxWindowCreateEvent(wxWindow* win = NULL); + + /// Retutn the window being created. + wxWindow *GetWindow() const; }; @@ -2718,17 +2752,23 @@ public: /** @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} @@ -2742,6 +2782,9 @@ public: Constructor. */ wxWindowDestroyEvent(wxWindow* win = NULL); + + /// Retutn the window being destroyed. + wxWindow *GetWindow() const; };