Developer

API Reference

IDrawDecorator

Brew Release
Brew MP 1.0.2
See Also
IDecorator Interface
Description
The widgets framework provides several built-in decorators such as the border and blend widgets, and the gradient decorator that perform very specific drawing operations on wrapped objects. The draw decorator provides applications with the ability to perform customized drawing operations to the objects wrapped by a decorator. For example, an application that wishes to display a border that contains itty bitty teeny tiny bitmap images of flesh eating zombies could create a draw decorator widget, wrap this widget around some other content, then supply a custom draw handler that would be called each time the draw decorator is asked to draw itself. The custom draw handler would then render the flesh eating zombies in all their grotesque and stomach churning glory.
It is important to note that a draw decorator widget is intended to enhance -- rather than replace -- the normal drawing activity associated with a decorator. The widget framework maintains what could be viewed as a chain of draw handlers for each object. Usually, this conceptual drawing chain will only include the draw handler for the widget wrapped by the decorator, like so:
       +-------------------------+
       |                         |
       |        Decorator        |     +---------------+
       |      Draw Handler     +-----> |    Widget     |
       |                         |     +---------------+
       +-------------------------+

A decorator such as a blend widget or border widget hooks into this chain by applying its own draw handler to render its specific visual effect. The border widget, for example, will hook its draw handler before the widget it wraps is drawn, like so:
             +-------------------------+
             |                         |
             |     Border Widget       |     +---------------+
         +------+   Draw Handler     +-----> |    Border     |    drawn first
         |   |                         |     +---------------+
         |   +-------------------------+
         |
         |
         |   +-------------------------+
         +-->|                         |
             |        Decorator        |     +---------------+
             |      Draw Handler     +-----> |    Widget     |    drawn second
             |                         |     +---------------+
             +-------------------------+

So, as illustrated the border is drawn first, followed by the widget it wraps.
Hooking a custom draw handler to a draw decorator has the same effect, with the new handler inserting itself into the calling chain, either before or after the default handler supplied by the decorator. The figure below illustrates how a custom draw handler is linked into the drawing chain.
   
             +-------------------------+
             |                         |
             |         Custom          |     +---------------+
         +------+   Draw Handler     +-----> |    Custom     |    drawn first
         |   |                         |     |   Drawing     |
         |   +-------------------------+     +---------------+
         |
         |
         |   +-------------------------+
         +-->|                         |
             |        Decorator        |     +---------------+
             |      Draw Handler     +-----> |    Widget     |    drawn second
             |                         |     +---------------+
             +-------------------------+

An application wishing to hook its own custom draw handler into the decorator drawing chain must first register its draw handler by calling IDrawDecorator_SetDraw(). The call to IDrawDecorator_SetDraw() returns a pointer to a data structure containing the decorator's current draw handler (i.e. the draw handler that would be called if a custom handler had not been attached to the decorator). The application should save this pointer and pass it to the decorator interface in a subsequent call to DrawHandlerDesc_Call() within the custom draw handler itself to insure that the drawing chain continues. The application may choose to perform its drawing either prior to or following the call to DrawHandlerDesc_Call(). For example, our previous example of the flesh eating zombie custom draw handler would, like a border widget, likely choose to draw all of those scary zombies as a frame around the decorator, then call DrawHandlerDesc_Call() to allow the widget it wraps to draw itself. A custom decorator draw handler that wishes to superimpose a logo over the top of another object (sort of like station branding on cable TV broadcasts), might choose to call DrawHandlerDesc_Call() first, then perform it's own custom rendering.
Supported Events: The draw decorator passes all received events to its child widget.
Usage
Example code -
   DrawDecoratorContext *pc = MYCONTEXT(me);
   IDrawDecorator *pidDraw = 0;
   int nErr;

   nErr = ISHELL_CreateInstance(GETSHELL(me), AEECLSID_DrawDecoratorWidget, (void**)&pidDraw);

   DRAWHANDLERDESC_Init(&pc->hd, CWidget_CustomDrawOver, pc, 0);
   IDRAWDECORATOR_SetDraw(pidDraw, &pc->hd);
   IDRAWDECORATOR_SetWidget(pidDraw, pc->piw);
   me->piw = (IWidget*)pidDraw;
   IWIDGET_AddRef(me->piw);
   CWidget_ContainerInsert(me);

   RELEASEIF(pidDraw);
  • Follow