Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Drawing Pictures

DrawPicture

To draw a picture on any type of output device, use the DrawPicture procedure.

PROCEDURE DrawPicture (myPicture:\xDDPicHandle; dstRect:\xDDRect);

myPicture

A handle to the picture to be drawn.

dstRect

A destination rectangle, specified in coordinates local to the current graphics port, in which to draw the picture. The DrawPicture procedure shrinks or expands the picture as necessary to align the borders of its bounding rectangle with the rectangle you specify in this parameter. To display a picture at a resolution other than that at which it was created, your application should compute an appropriate destination rectangle by scaling its width and height by the following factor:

scale factor = destination resolution / source resolution

For example, if a picture was created at 300 dpi and you want to display it at 75 dpi, then your application should compute the destination rectangle width and height as 1/4 of those of the picture's bounding rectangle. Your application can use the GetPictInfo function (described on page 7-46) to gather information about a picture. The PictInfo record (described on page 7-31) returned by GetPictInfo returns the picture's resolution in its hRes and vRes fields. The sourceRect field contains the bounding rectangle for displaying the image at its optimal resolution.

DESCRIPTION

Within the rectangle that you specify in the dstRect parameter, the DrawPicture procedure draws the picture that you specify in the myPicture parameter.

The DrawPicture procedure passes any picture comments to the StdComment procedure pointed to by the commentProc field of the CQDProcs or QDProcs record, which in turn is pointed to by the grafProcs field of a CGrafPort or GrafPort record. The default StdComment procedure provided by QuickDraw does no comment processing whatsoever. If you want to process picture comments when drawing a picture, you can use the SetStdCProcs procedure to assist you in changing the CQDProcs record, and you can use the SetStdProcs procedure to assist you in changing the QDProcs record.

SPECIAL CONSIDERATIONS

Always use the ClipRect procedure to specify a clipping region appropriate for your picture before defining it with the OpenCPicture (or OpenPicture) function. If you do not use ClipRect to specify a clipping region, OpenCPicture uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you want to scale the picture, the clipping region can become invalid when DrawPicture scales the clipping region--in which case, your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when DrawPicture draws it. Setting a clipping region equal to the port rectangle of the current graphics port, as shown in Listing 7-1 on page 7-10, always sets a valid clipping region.

When it scales, DrawPicture changes the size of the font instead of scaling the bits. However, the widths used by bitmap fonts are not always linear. For example, the 12-point width isn't exactly 1/2 of the 24-point width. This can cause lines of text to become slightly longer or shorter as the picture is scaled. The difference is often insignificant, but if you are trying to draw a line of text that fits exactly into a box (a spreadsheet cell, for example), the difference can become noticeable to the user--most typically, at print time. The easiest way to avoid such problems is to specify a destination rectangle that is the same size as the bounding rectangle for the picture. Otherwise, your application may need to directly process the opcodes in the picture instead of using DrawPicture.

You may also have disappointing results if the fonts contained in an image are not available on the user's system. Before displaying a picture, your application may want to use the Picture Utilities to determine what fonts are contained in the picture, and then use Font Manager routines to determine whether the fonts are available on the user's system. If they are not, you can use Dialog Manager routines to display an alert box warning the user of display problems.

If there is insufficient memory to draw a picture in Color QuickDraw, the QDError function (described in the chapter "Color QuickDraw" in this book) returns the result code noMemForPictPlaybackErr.

The DrawPicture procedure may move or purge memory.

SEE ALSO

Listing 7-1 on page 7-10 illustrates how to use DrawPicture after creating a picture while your application is running; Listing 7-2 on page 7-13 illustrates how to use DrawPicture after reading in a picture stored in a 'PICT' file; Listing 7-6 on page 7-16 illustrates how to use DrawPicture after reading in a picture stored in the scrap; and Listing 7-8 on page 7-19 illustrates how to use DrawPicture after reading in a picture stored in a 'PICT' resource.

See the chapter "Font Manager" in Inside Macintosh: Text for information about Font Manager routines; see the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information about Dialog Manager routines.