The IHandler class is an abstract base class for window event handlers. You can write derived classes to handle specific window events, such as GUI window messages. Windows (or the objects that create windows) add objects of these handler classes to themselves by using IHandler::handleEventsFor. Windows can also add handlers by using IWindow::addHandler.
You can add multiple handlers to a given window. The handlers are called in turn until one of them indicates that further handlers are not to be called. The handler achieves this by returning true from its dispatchHandlerEvent.
The handler that processes a given event is also responsible for setting the appropriate event result. The handler does this by using IEvent::setResult. In general, a handler that returns true from dispatchHandlerEvent must call IEvent::setResult on the event passed to it. This result is returned to the sender of the event.
Handlers can be detached from windows by using either IHandler::stopHandlingEventsFor or IWindow::removeHandler. Ensure that you detach the handler from the windows it is handling prior to destroying the handler object. Typically, a window removes its handlers in its destructor.
Handlers can be disabled to suppress their handling of events without removing them from the window handler chain.
If none of the handlers returns true, nothing happens.
If none of the handlers returns true, the original window procedure for the underlying Presentation Manager window is called.
If none of the handlers returns true, the original window procedure for the underlying Presentation Manager window is called.
Only derived classes can call constructors of this class.
![]() |
public:
virtual ~IHandler()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IHandler()
Derived classes call this default constructor from their constructors. This constructor initializes the handler in an enabled state.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
These members provide diagnostic information.
![]() |
public:
virtual IString asDebugInfo() const
Returns diagnostic information about the handler.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IString asString() const
Returns the string "IHandler(enabled)" or "IHandler(disabled)".
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Use these members to enable and disable the handler.
![]() |
public:
virtual IHandler& disable()
Disables the handler so that it processes no window events.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IHandler& enable(bool enable = true)
Enables the handler, by default. It accepts an optional boolean parameter that, when false, causes the handler to be disabled.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool isEnabled() const
Returns whether the handler is currently enabled.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The Open Class Library dispatches events that have been sent or posted to a window to the handlers attached to that window. It does this by calling the event-dispatching function of the handler objects.
![]() |
public:
virtual IHandler& handleEventsFor(IWindow* window)
Attaches the handler to the specified IWindow object. The handler's dispatchHandlerEvent function is called to process all events sent or posted to the window.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IHandler& stopHandlingEventsFor(IWindow* window)
Detaches the handler from the specified IWindow object. The handler's dispatchHandlerEvent function is no longer called to process events sent or posted to the window.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool dispatchHandlerEvent(IEvent& event) = 0
IWindow calls this function when a window event occurs. A given handler should return true if the event should not be dispatched to other handlers. In such cases, a result can be placed in the specified IEvent object.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Event-processing members provide the interface or implementation for handling an event.
![]() |
protected:
virtual IEventResult defaultProcedure(IEvent& event)
Sends the specified IEvent object to the original window procedure for the underlying window.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
AIX does not support this function.