Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 1 - QuickDraw GX and the Macintosh Environment / Using the QuickDraw-to-QuickDraw GX Translator

Installing and Removing the Translator

If you want to capture QuickDraw commands as they are executed, convert them, and either draw them immediately or save them, you need to install the QuickDraw-to-QuickDraw GX translator in the graphics port to which the QuickDraw drawing commands will be sent.

You install the translator with the GXInstallQDTranslator function. Once installed, the translator intercepts all QuickDraw drawing commands to that port, converts them to QuickDraw GX shapes, and sends them to a callback function (that you supply) for drawing or saving. When you are finished capturing QuickDraw commands, you remove the translator with the GXRemoveQDTranslator function.

Note

There is not necessarily a one-to-one match between a QuickDraw function call and the generation of a QuickDraw GX shape.

Listing 1-5 is a sample that uses the functions GXInstallQDTranslator and GXRemoveQDTranslator to convert the bounded QuickDraw commands. The application-defined callback function, aShapeProc, sets the view port and draws each translated shape. The aShapeProc function is shown in Listing 1-6 on page 1-22.

Listing 1-5 Installing and removing the translator

/* first, install the translator */
GXInstallQDTranslator(window, gxDefaultOptionsTranslation, 
                        &theRect, &theRect, theStyleStretch,
                        aShapeProc, (void *) &theWindViewPort);

/* now, make QuickDraw calls */
PenSize(20, 10);

MoveTo(100, 100);
LineTo(200, 100);

MoveTo(100, 150);
LineTo(200, 250);

/* when finished drawing, remove the translator */
GXRemoveQDTranslator(window, nil);

When using the GXInstallQDTranslator function, you must supply an application-defined function that gives you control over what is to be done with the QuickDraw GX shapes resulting from the translation. For example, you may want to draw each shape as it is translated, or you may want to spool multiple shapes and draw after you have completed the picture.

Listing 1-6 is the sample shape-spooling function used by the code in Listing 1-5. This function sets the view port, which is passed to it in the reference parameter, and then draws the shape passed to it in the parameter theShape.

Listing 1-6 Sample application-defined shape-spooling function

OSErr aShapeProc( gxShape theShape, 
                                 void *reference)
{
   GXSetShapeViewPorts(theShape, 1, (gxViewPort *) &reference);
   GXDrawShape(theShape);
   GXDisposeShape(theShape);
   return(GXGetGraphicsError(nil));
}

The prototype for the shape-spooling function, and how to use it, are described in the section "Handling Translated QuickDraw Data" beginning on page 1-41.