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
Process a command for a range of window identifiers, supplying the minimum and
maximum window identifiers, command event identifier, and member function.
@event{EVT_BUTTON(id, func)}
- Process a wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
+ Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
@event{EVT_CHECKBOX(id, func)}
- Process a wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
+ Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
@event{EVT_CHOICE(id, func)}
- Process a wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
+ Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
@event{EVT_COMBOBOX(id, func)}
- Process a wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
+ Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
@event{EVT_LISTBOX(id, func)}
- Process a wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
+ Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
@event{EVT_LISTBOX_DCLICK(id, func)}
- Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
+ Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
@event{EVT_MENU(id, func)}
- Process a wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
+ Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
@event{EVT_MENU_RANGE(id1, id2, func)}
- Process a wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
+ Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
@event{EVT_CONTEXT_MENU(func)}
Process the event generated when the user has requested a popup menu to appear by
pressing a special keyboard key (under Windows) or by right clicking the mouse.
@event{EVT_RADIOBOX(id, func)}
- Process a wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
+ Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
@event{EVT_RADIOBUTTON(id, func)}
- Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
+ Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
@event{EVT_SCROLLBAR(id, func)}
- Process a wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
+ Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
control. This is provided for compatibility only; more specific scrollbar event macros
should be used instead (see wxScrollEvent).
@event{EVT_SLIDER(id, func)}
- Process a wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
+ Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
@event{EVT_TEXT(id, func)}
- Process a wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
+ Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
@event{EVT_TEXT_ENTER(id, func)}
- Process a wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
+ Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
to generate such events.
@event{EVT_TEXT_MAXLEN(id, func)}
- Process a wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
+ Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
when the user tries to enter more characters into it than the limit previously set
with SetMaxLength().
@event{EVT_TOGGLEBUTTON(id, func)}
- Process a wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
+ Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
@event{EVT_TOOL(id, func)}
- Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for wxEVT_COMMAND_MENU_SELECTED).
+ Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED).
Pass the id of the tool.
@event{EVT_TOOL_RANGE(id1, id2, func)}
- Process a wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
+ Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
@event{EVT_TOOL_RCLICKED(id, func)}
- Process a wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
+ Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
@event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
- Process a wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
+ Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
@event{EVT_TOOL_ENTER(id, func)}
- Process a wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
+ Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
has moved off a tool.
@event{EVT_COMMAND_LEFT_CLICK(id, func)}
- Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
+ Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_LEFT_DCLICK(id, func)}
- Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
+ Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_RIGHT_CLICK(id, func)}
- Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
+ Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_SET_FOCUS(id, func)}
- Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
+ Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_KILL_FOCUS(id, func)}
- Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
+ Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_ENTER(id, func)}
- Process a wxEVT_COMMAND_ENTER command, which is generated by a control.
+ Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
@endEventTable
@library{wxcore}
/**
@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;
};
these do not include menu command events, which are
handled using wxCommandEvent objects.
- The default handler for wxEVT_MENU_HIGHLIGHT displays help
+ The default handler for @c wxEVT_MENU_HIGHLIGHT displays help
text in the first field of the status bar.
@beginEventTable{wxMenuEvent}
// 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