The custom draw handler is stored in a DrawHandlerDesc data structure as a PFNDRAWHANDLER, along with a pointer to a block of memory allocate and owned by the application. This pointer will be passed into the draw handler each time the draw handler is asked to draw itself, providing access to private application storage. The DrawHandlerDesc data structure also contains a PFNFREEHANDLER that will be called when the widget is released so that the widget may free the private memory allocated and passed to the event handler.
- pif:[in] A pointer to an IDrawHandler interface.
- pDesc:[in] Pointer to the data structure that contains the custom draw handler, private memory pointer, and the callback used to free the private memory.
void IDrawHandler_SetDraw(IDrawHandler *p, DrawHandlerDesc *pd);
Unless the draw handler is to be responsible for drawing all of the widget, the custom draw handler installed should itself remember to call DRAWHANDLERDESC_Call() so that the drawing chain will continue. The draw handler may call DRAWHANDLERDESC_Call() at any point -- either before it performs its own drawing, after, or someplace in the middle.
An application that hooks into both a widget's draw handler and event handler (by calling IHandler_SetHandler()), should exercise care in managing the private data released by the PFNFREEHANDLER stored in the DrawHandlerDesc data structure. Draw handlers and event handlers both manage data structures that contain pointers to private storage, as well as a pointer to a function that will be used to release this storage -- which could be different... or could be the same! Each of these PFNFREEHANDLER routines will be called when the widget is released. Therefore, an application that uses the same block of private storage for both its custom event and draw handling procedures should be careful to check the validity of the storage to be freed before actually attempting to release the memory.