wxEvtHandler

A class that can handle events from the windowing system. wxWindow (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 it is imperative that the wxEvtHandler(-derived) class be the first class inherited such that the "this" pointer for the overall object will be identical to the "this" pointer for the wxEvtHandler portion.

Derived from

wxObject

Include files

<wx/event.h>

See also

Event handling overview

Members

wxEvtHandler::wxEvtHandler
wxEvtHandler::~wxEvtHandler
wxEvtHandler::AddPendingEvent
wxEvtHandler::Connect
wxEvtHandler::Disconnect
wxEvtHandler::GetClientData
wxEvtHandler::GetClientObject
wxEvtHandler::GetEvtHandlerEnabled
wxEvtHandler::GetNextHandler
wxEvtHandler::GetPreviousHandler
wxEvtHandler::ProcessEvent
wxEvtHandler::SearchEventTable
wxEvtHandler::SetClientData
wxEvtHandler::SetClientObject
wxEvtHandler::SetEvtHandlerEnabled
wxEvtHandler::SetNextHandler
wxEvtHandler::SetPreviousHandler

wxEvtHandler::wxEvtHandler

wxEvtHandler()

Constructor.

wxEvtHandler::~wxEvtHandler

~wxEvtHandler()

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.

wxEvtHandler::AddPendingEvent

void AddPendingEvent(wxEvent& event)

This function posts an event to be processed later.

Parameters

event

Event to add to process queue.

Remarks

The difference between sending an event (using the ProcessEvent method) and posting it is that in the first case the event is processed before the function returns, while in the second case, the function returns immediately and the event will be processed sometime later (usually during the next event loop iteration).

A copy of 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.

This is also the method to call for inter-thread communication---it will post events safely between different threads which means that this method is thread-safe by using critical sections where needed. In a multi-threaded program, you often need to inform the main GUI thread about the status of other working threads and such notification should be done using this method.

This method automatically wakes up idle handling if the underlying window system is currently idle and thus would not send any idle events. (Waking up idle handling is done calling ::wxWakeUpIdle.)

wxEvtHandler::Connect

void Connect(int id, wxEventType eventType, wxObjectEventFunction function, wxObject* userData = NULL, wxEvtHandler* eventSink = NULL)

void Connect(int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject* userData = NULL, wxEvtHandler* eventSink = NULL)

Connects the given function dynamically with the event handler, id and event type. This is an alternative to the use of static event tables. See the 'event' or the old 'dynamic' sample for usage.

Parameters

id

The identifier (or first of the identifier range) to be associated with the event handler function.

lastId

The second part of the identifier range to be associated with the event handler function.

eventType

The event type to be associated with this event handler.

function

The event handler function.

userData

Data to be associated with the event table entry.

eventSink

Object whose member function should be called. If this is NULL, 'this' will be used.

Example

  frame->Connect( wxID_EXIT,
    wxEVT_COMMAND_MENU_SELECTED,
    (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) &MyFrame::OnQuit );

wxEvtHandler::Disconnect

bool Disconnect(int id, wxEventType eventType = wxEVT_NULL, wxObjectEventFunction function = NULL, wxObject* userData = NULL, wxEvtHandler* eventSink = NULL)

bool Disconnect(int id, int lastId = -1, wxEventType eventType = wxEVT_NULL, wxObjectEventFunction function = NULL, 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 wxEvtHandler::Connect method. There is no way to disconnect functions connected using the (static) event tables.

Parameters

id

The identifier (or first of the identifier range) associated with the event handler function.

lastId

The second part of the identifier range associated with the event handler function.

eventType

The event type associated with this event handler.

function

The event handler function.

userData

Data associated with the event table entry.

eventSink

Object whose member function should be called.

wxPerl note: In wxPerl this function takes 3 arguments: id, lastid, type.

wxEvtHandler::GetClientData

void* GetClientData()

Gets 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 also

wxEvtHandler::SetClientData

wxEvtHandler::GetClientObject

wxClientData* GetClientObject() const

Get a pointer to the user-supplied client data object.

See also

wxEvtHandler::SetClientObject, wxClientData

wxEvtHandler::GetEvtHandlerEnabled

bool GetEvtHandlerEnabled()

Returns true if the event handler is enabled, false otherwise.

See also

wxEvtHandler::SetEvtHandlerEnabled

wxEvtHandler::GetNextHandler

wxEvtHandler* GetNextHandler()

Gets the pointer to the next handler in the chain.

See also

wxEvtHandler::SetNextHandler, wxEvtHandler::GetPreviousHandler, wxEvtHandler::SetPreviousHandler, wxWindow::PushEventHandler, wxWindow::PopEventHandler

wxEvtHandler::GetPreviousHandler

wxEvtHandler* GetPreviousHandler()

Gets the pointer to the previous handler in the chain.

See also

wxEvtHandler::SetPreviousHandler, wxEvtHandler::GetNextHandler, wxEvtHandler::SetNextHandler, wxWindow::PushEventHandler, wxWindow::PopEventHandler

wxEvtHandler::ProcessEvent

virtual bool ProcessEvent(wxEvent& event)

Processes an event, searching event tables and calling zero or more suitable event handler function(s).

Parameters

event

Event to process.

Return value

true if a suitable event handler function was found and executed, and the function did not call wxEvent::Skip.

Remarks

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:

1. If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) the function skips to step (6).
2. If the object is a wxWindow, ProcessEvent is recursively called on the window's wxValidator. If this returns true, the function exits.
3. 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.
4. 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.
5. 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.
6. Finally, ProcessEvent is called on the wxApp object.

See also

wxEvtHandler::SearchEventTable

wxEvtHandler::SearchEventTable

bool SearchEventTable(wxEventTable& table, wxEvent& event)

Searches the event table, executing an event handler function if an appropriate one is found.

Parameters

table

Event table to be searched.

event

Event to be matched against an event table entry.

Return value

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:

1. The event type matches, and
2. 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 also

wxEvtHandler::ProcessEvent

wxEvtHandler::SetClientData

void SetClientData(void* data)

Sets user-supplied client data.

Parameters

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 also

wxEvtHandler::GetClientData

wxEvtHandler::SetClientObject

void SetClientObject(wxClientData* data)

Set the client data object. Any previous object will be deleted.

See also

wxEvtHandler::GetClientObject, wxClientData

wxEvtHandler::SetEvtHandlerEnabled

void SetEvtHandlerEnabled(bool enabled)

Enables or disables the event handler.

Parameters

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 also

wxEvtHandler::GetEvtHandlerEnabled

wxEvtHandler::SetNextHandler

void SetNextHandler(wxEvtHandler* handler)

Sets the pointer to the next handler.

Parameters

handler

Event handler to be set as the next handler.

See also

wxEvtHandler::GetNextHandler, wxEvtHandler::SetPreviousHandler, wxEvtHandler::GetPreviousHandler, wxWindow::PushEventHandler, wxWindow::PopEventHandler

wxEvtHandler::SetPreviousHandler

void SetPreviousHandler(wxEvtHandler* handler)

Sets the pointer to the previous handler.

Parameters

handler

Event handler to be set as the previous handler.

See also

wxEvtHandler::GetPreviousHandler, wxEvtHandler::SetNextHandler, wxEvtHandler::GetNextHandler, wxWindow::PushEventHandler, wxWindow::PopEventHandler