Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 1 - QuickDraw GX and the Macintosh Environment / QuickDraw GX and the Macintosh Environment Reference

QuickDraw-to-QuickDraw GX Translator Functions / Installing and Removing the Translator

GXInstallQDTranslator

You can use the GXInstallQDTranslator function to initiate translation of the QuickDraw drawing commands to QuickDraw GX shapes. Subsequent QuickDraw drawing commands are translated into equivalent QuickDraw GX shapes.

void GXInstallQDTranslator(GrafPtr port, 
                           gxTranslationOptions options, 
                           const Rect *srcRect, 
                           const Rect *dstRect, 
                           Point styleStretch,
                           gxShapeSpoolFunction userFunction, 
                           void *reference);

port

A pointer to the QuickDraw graphics port into which to install the translator.

options

The translation options to use for the translation.

srcRect

A pointer to a rectangle defining the QuickDraw source dimensions for drawing, in QuickDraw coordinates.

dstRect

A pointer to a rectangle defining the QuickDraw destination dimensions for drawing, in QuickDraw coordinates.

styleStretch

The amount of scaling that certain picture-comment items, such as dashes, will be given in the x and y directions.

userFunction

A pointer to an application-defined callback function to which the translator passes each translated shape.

reference

A pointer to a reference constant that can be used for any purpose. QuickDraw GX passes the reference constant to the application-defined callback function each time it calls the function.

DESCRIPTION

You can use the GXInstallQDTranslator function to install the QuickDraw-to-QuickDraw GX translator into a QuickDraw graphics port. QuickDraw commands that draw into that port are translated to equivalent QuickDraw GX shapes.

All QuickDraw drawing commands executed after you call this function and before you call GXRemoveQDTranslator are converted into QuickDraw GX shapes and passed to an application-defined function. There is not necessarily a one-to-one match between a QuickDraw function call and the generation of a QuickDraw GX shape; the translation algorithm can combine several QuickDraw items into one QuickDraw GX shape.

The srcRect and dstRect parameters represent the source and destination space of the image, expressed in QuickDraw coordinates. The relation between the source and destination rectangles specifies the amount of scaling to be applied during translation. If scaling is not required, you can pass identical rectangles for both parameters.

The styleStretch parameter represents the amount of scaling that QuickDraw bitmap patterns are given by the translator in the x and y directions in order to scale them up to the destination space. The x scale factor is stored in styleStretch.h and the y scale factor is stored in styleStretch.v. These values are usually the destination resolution divided by the screen resolution (72 dpi), rounded to the nearest integer.

The userFunction parameter is a pointer to an application-defined callback function of type gxShapeSpoolFunction:

typedef OSErr (*gxShapeSpoolProcPtr)(gxShape toSpool, 
                                       void *refCon);
typedef gxShapeSpoolProcPtr gxShapeSpoolFunction;

The translator calls the function every time that it generates a translated QuickDraw GX shape. You must provide the function; its prototype is described in the section "Handling Translated QuickDraw Data" beginning on page 1-41.

The reference parameter of the GXInstallQDTranslator function can be used by your application in any manner you desire, within the constraints of a long data field. The translator passes the parameter to the application-defined callback function. For example, you can use reference to specify where the translated picture is to be displayed, by passing a view port reference in the reference parameter.

SPECIAL CONSIDERATIONS

If you call the GXInstallQDTranslator function to install the translator, you must subsequently call the GXRemoveQDTranslator function to remove it when you are finished.

The port parameter to this function must be an old-style graphics-port pointer (GrafPtr); however, the translator depends on the existence of a color graphics port. Therefore, you should always create a color graphics port (using NewCWindow, NewGWorld or OpenCPort), and coerce the CGrafPtr to a GrafPtr when you call this function.

Before installing the translator, you must first call the GXInitPrinting function.

Installation of the translator cannot cause an out_of_memory error, but the process of translation can result in an out-of-memory condition. Your application should be prepared to handle that condition.

ERRORS, WARNINGS, AND NOTICES

Notices (debugging version)

translator_already_installed_on_this_grafport

SEE ALSO

For an example of the use of this function, see Listing 1-5 on page 1-21.

Translation options from the gxTranslationOptions enumeration are described in Table 1-2 on page 1-12.

The application-defined shape-spooling function called by the translator is described on page 1-41.

To translate an entire QuickDraw picture, use the GXConvertPICTToShape function, described in the previous section.

For a general description of the QuickDraw-to-QuickDraw GX translator, see the section "Using the QuickDraw-to-QuickDraw GX Translator" beginning on page 1-10.

The GXInitPrinting function is described in the chapter "Core Printing Features" in Inside Macintosh: QuickDraw GX Printing.

For descriptions of color graphics ports and the functions you use to create them, see Inside Macintosh: Imaging With QuickDraw.