Events and Event Handlers

The Open Class Class Library uses events and event handlers to encapsulate and hide the message architectures of Windows, OS/2 Presentation Manager (PM) and Motif in an object-oriented way. The Open Class Class Library reserves message IDs beginning at 0xFF00. If you use the Open Class Class Library, define user messages only in the range of WM_USER (0x1000) through 0xFEFF.

The Windows operating system defines messages above the WM_USER range. Refer to your Windows documentation to ensure that you are not conflicting with these messages. OS/2 developers should also verify their user messages if developing portable applications.

The following figure shows the relationships between window, event, and handler classes.

Handlers are registered with the window.
Messages are encapsulated in event objects, which are passed to the window or control that had the event.
The window then invokes the handlers attached to it, passing the event object as a parameter.
The handlers are called sequentially with the most recently added handler invoked first. A handler indicates when processing for the event is complete by returning a Boolean value of true.
If none of the handlers process the event, it is passed up the owner chain.

The distinction between window classes and handler classes lets you separate the event-handling logic from the rest of the application. This enables reuse of this logic. For example, you can reuse a handler to verify telephone numbers wherever an entry field accepts telephone numbers.

Processing Events Using Handlers

Each handler class has one or more virtual functions that are called to process the event. When an application processes events, it normally creates a class derived from a handler class, and overrides the virtual function to provide its own application-specific logic.

When you are within a handler member function, do not delete the IWindow object to which the handler is attached.

The order in which you attach handlers can cause a handler to not receive events because handlers are called in the reverse order that they are attached.

As a rule, ensure that handlers return from virtual functions within 1/10 second to avoid locking up the system by delaying the PM message processing.

The following figure shows how the ICommandHandler works. All handler classes contain a dispatchHandlerEvent function to determine whether the handler needs to process the event or return it. If the event needs processing, it creates the appropriate event object and calls the appropriate virtual function to process the event.

The numbers represent the following:

	Number	Description
	1	Window creates an event.
	2	IEvent is passed to ICommandHandler.
	3a	IEvent is not processed.
	3b	ICommandEvent is generated.
	4	ICommandEvent is processed by command().

The IEvent class acts as the base class for more specialized event classes. It provides general member functions to extract the message ID and message parameters. The IEvent derived classes generally add more specialized functions for extracting information specific to that type of event. The IEvent class provides a member function, setResult, for those events that require a value to be returned.

Windows
Controls

Creating a Frame Window
Adding Events and Event Handlers

ICommandEvent
ICommandHandler
IEvent
IHandler