IHandler

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.

AIX Considerations

If none of the handlers returns true, nothing happens.

OS/2 Considerations

If none of the handlers returns true, the original window procedure for the underlying Presentation Manager window is called.

Windows Considerations

If none of the handlers returns true, the original window procedure for the underlying Presentation Manager window is called.


IHandler - Member Functions and Data by Group

Constructors & Destructor

Only derived classes can call constructors of this class.


[view class]
~IHandler
public:
virtual ~IHandler()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IHandler
public:
IHandler()

Derived classes call this default constructor from their constructors. This constructor initializes the handler in an enabled state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Diagnostics

These members provide diagnostic information.


[view class]
asDebugInfo
public:
virtual IString asDebugInfo() const

Returns diagnostic information about the handler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asString
public:
virtual IString asString() const

Returns the string "IHandler(enabled)" or "IHandler(disabled)".

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Enabling and Disabling Handlers

Use these members to enable and disable the handler.


[view class]
disable
public:
virtual IHandler& disable()

Disables the handler so that it processes no window events.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enable
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isEnabled
public:
bool isEnabled() const

Returns whether the handler is currently enabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

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.


[view class]
handleEventsFor
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stopHandlingEventsFor
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dispatchHandlerEvent
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

Event-processing members provide the interface or implementation for handling an event.


[view class]
defaultProcedure
protected:
virtual IEventResult defaultProcedure(IEvent& event)

Sends the specified IEvent object to the original window procedure for the underlying window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support this function.


IHandler - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data