Contents Up Previous Next

wxEvtHandler

A class that can handle events from the windowing system. wxWindow (and therefore all window classes) are derived from this class.

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::GetEvtHandlerEnabled
wxEvtHandler::GetNextHandler
wxEvtHandler::GetPreviousHandler
wxEvtHandler::ProcessEvent
wxEvtHandler::SearchEventTable
wxEvtHandler::SetClientData
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

virtual void AddPendingEvent(wxEvent& event)

Adds an event to be processed later. The function will return immediately and the event will get processed in idle time using the wxEvtHandler::ProcessEvent method.

Parameters

event

Remarks

Note that this requires that the event has a fully implemented Clone() method so that the event can be duplicated and stored until it gets processed later. Not all events in wxWindows currently have a fully implemented Clone() method, so you may have to look at the source to verify this.

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

This is also the method to call for inter-thread communication. In a multi-threaded program, you will often have to inform the main GUI thread about the status of other working threads and this has to be done using this method - which also means that this method is thread safe by means of using crtical sections where needed.

Furthermore, it may be noted that some ports of wxWindows will probably move to using this method more and more in preference over calling ProcessEvent() directly so as to avoid problems with reentrant code.


wxEvtHandler::Connect

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

void Connect(int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject* userData = 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 'dynamic' sample for usage.

Parameters

id

lastId

eventType

function

userData

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)

bool Disconnect(int id, int lastId = -1, wxEventType eventType = wxEVT_NULL, wxObjectEventFunction function = NULL, wxObject* userData = 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

lastId

eventType

function

userData


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::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

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 wxWindows 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 wxWindows. 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

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

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::GetClientData


wxEvtHandler::SetEvtHandlerEnabled

void SetEvtHandlerEnabled(bool enabled)

Enables or disables the event handler.

Parameters

enabled

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

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

See also

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