Developer

API Reference

IHandler_SetHandler()

Brew Release
Brew MP 1.0.2
See Also
- IHandler Interface
- HandlerDesc
- HANDLERDESC_Call()
Description
This function allows an application to subclass an object by installing a new event handler. IHandler_SetHandler() is passed a pointer to a handler descriptor which contains a pointer to the new event handler, an optional context pointer, and an optional callback pointer used to free private memory associated with the object. On return, the handler descriptor will be filled with the previous event handler, context pointer and free callback (usually NULL).
The new event handler must pass unhandled events to the previous event handler by calling the previous event handler stored in the handler descriptor using the macro HANDLERDESC_Call().
Applications can 'chain' multiple event handlers on an object by calling IHandler_SetHandler() multiple times with different HandlerDesc data structures.
To uninstall a handler from the chain, call IHandler_SetHandler() a second time with the same HandlerDesc data structure. This will swap the new and previous event handlers back to the state they were before the handler was installed. If multiple handlers are installed, they must be uninstalled in the reverse order from which they were installed. The following example may help to illustrate. (Note that chaining multiple handlers in this way is not likely to be useful, it is only shown here to demonstrate the mechanics of multiple handlers.)
   
   HandlerDesc hdNew1, hdNew2, hdNew3;

   // install 3 handlers
   IForm_SetHandler(po, &hdNew1);
   IForm_SetHandler(po, &hdNew2);
   IForm_SetHandler(po, &hdNew3);
   
   // later, undo the above handler chaining
   IForm_SetHandler(po, &hdNew3);
   IForm_SetHandler(po, &hdNew2);
   IForm_SetHandler(po, &hdNew1);


Parameters
  • pif
    []:
    [in] A pointer to an IHandler interface object.
  • phd
    []:
    [out] Pointer to the data structure that contains the event handler, context pointer and a callback used to free private memory.
Interface
Prototype
   void IHandler_SetHandler(IHandler *pif, HandlerDesc *pd);
Return
IHandler_SetHandler() fills the HandlerDesc data structure pointed to by 'pd' with the previous event handler, context pointer and free callback. The application should save the contents of the HandlerDesc data structure and pass unhandled events to the previous event handler and context pointer. The macro HANDLERDESC_Call() may be used as a convenience for this call.
Side Effect
None
Comment
Applications may reset the object's event handler, context pointer and free pointer by passing in NULL for the 'pd' parameter.
The new event handler must pass unhandled events to the previous event handler so that all installed handlers have a chance to handle the event.
  • Follow