Developer

API Reference

IDrawDecorator_SetDraw()

Brew Release
Brew MP 1.0.2
See Also
- IDrawDecorator Interface
- PFNHANDLER
- PFNFREEHANDLER
- DrawHandlerDesc
- DrawHandlerDesc_Call()
- IDrawDecorator_SetHandler()
Description
This function allows an application to hook its own custom draw handler into the drawing chain for a draw decorator. By default, a when asked to draw itself, a draw decorator will draw the object it wraps. Usually this object is another container managing one or more child objects, each of which will draw be drawn as the effective result of drawing the draw decorator. In this default state, the draw decorator really does not "draw" anything at all!! However, an application wishing to provide a customized appearance to an object may wrap that object in a draw decorator and provide its own customized drawing routine to decorate that object by calling IDrawDecorator_SetDraw() and providing a PFNDRAWHANDLER in a DrawHandlerDesc data structure to that draw decorator. The customized draw handler will then be called instead of the normal default drawing procedure allowing the application to perform whatever rendering magic is appropriate. For example, an application could choose to install its own custom draw procedure that renders all of its child widgets into an offscreen bitmap, then transformed that bitmap and finally blitted the image onto the display to create the effect of looking at the display from the inside out (neato!).
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 decorator 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 draw decorator is released so that the decorator may free the private memory allocated and passed to the event handler.
Parameters
  • p
    []:
    A pointer to an IDrawDecorator object.
  • pd
    []:
    Pointer to the data structure that contains the custom draw handler, private memory pointer, and the callback used to free the private memory.

Prototype
   void IDrawDecorator_SetDraw(IDrawDecorator *p, DrawHandlerDesc *pd);
Return
None
Side Effect
None
Comment
Passing NULL for the DrawHandlerDesc will reset the draw decorator's draw handler to use the draw decorator's default draw handler -- without private memory or the need to free privately allocated storage (but capable of only drawing the wrapped object without any decoration).
The draw handler installed by a draw decorator to perform custom drawing should itself remember to call DrawHandlerDesc_Call() so that the drawing chain will continue -- most notably, so that the object wrapped by the draw decorator will be drawn. 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 draw decorator's draw handler and event handler (by calling IDrawDecorator_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 draw decorator 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.
  • Follow