Technical Q&A GXPD28

Can't Print Hairlines

Q: How can I draw and print hairlines with QuickDraw GX? We use a PicComment in the normal print code, but this seems to make QuickDraw GX fail. (We get a -51 error, i.e., reference number invalid, when we call GXGetJobError after calling GXFinishJob, and we sometimes get this error without the PicComment code.)

We also tried calling GXSetShapePen in our spool procedure. When we set it to a fractional value, we get a wide line, but when we set it to a wide value, such as 8, it works properly. What do we need to do to print fractional widths?

I can print hairlines when I use:

SetPt((Point*)*lineWidth,2,1); PicComment(182,sizeof(Point),lineWidth);

but they are one pixel wide not two-pixel-wide, half-width lines (I am passing 1/2 in).

A: Here are two ways to get QuickDraw GX to draw hairlines when printing:

1. Call GXSetShapePen(myShape, 0); This sets your pen width to 0, which indicates that your pen should be set as thin as renderable on the output device. QuickDraw GX always draws hairlines at the resolution of the output device -- one pixel wide.
2. Call GXSetStylePen(myStyle, 0); This also sets your pen width to 0.

When using the GXSetShapePen and GXSetStylePen calls, don't specify the pen width as an integer. Calling GXSetStylePen(myStyle, 1) sets the pen width to 1/65536. Calling GXSetStylePen(myStyle, ff(1)) sets the pen width to 1.0.

QuickDraw GX uses a backing store file (it's an invisible file within the System folder) to send QuickDraw GX objects to disk when additional space is needed within the QuickDraw GX heap.

Almost all -51 errors from within QuickDraw GX or an application using QuickDraw GX are caused by double-disposing of a QuickDraw GX object (i.e., a shape, ink, style, or transform). The -51 error occurs because the double dispose causes QuickDraw GX to set the shape attributes, which tells QuickDraw GX that it has sent the QuickDraw GX object to disk. When it needs this object, it goes to the backing store and tries to get it, but it's not there. We have found a few cases where QuickDraw GX was double-disposing of objects, and these were fixed in QuickDraw GX version 1.1.

Before calling GXDrawShape (before calling GXFinishPage), call GXValidateShape on the shape(s) you are trying print. This ensures that a shape is valid before it is drawn or printed. This slows things down a little, but you will be able to determine if a shape is still available before you attempt to draw it (you might be disposing of a shape before you draw it). If you have an error handler installed, you usually receive the "shape_already_disposed" message, but you may not receive this message if something is wrong with the QuickDraw GX backing store.

It is also possible that the hairline drawing problems you are encountering are related to the translation options you are using. A translator takes your QuickDraw drawing commands and converts them to QuickDraw GX objects, based on options you provide. If you use the gxDefaultOptionsTranslation setting, a QuickDraw line turns into a 6-sided filled polygon. When your object is a polygon, changing the pen width has no effect.

To avoid this, call GXInstallQDTranslator() with either the gxSimpleGeometryTranslation or the gxReplaceLineWidthTranslation option. The gxSimpleGeometryTranslation option turns on both the simple-lines and simple-scaling translation options, and it translates QuickDraw lines into QuickDraw GX lines with flat endcaps. The QuickDraw GX line shape runs along the center of the original QuickDraw line, and it covers all the pixels of the QuickDraw line and more. The gxReplaceLineWidthTranslation option turns a QuickDraw line into a QuickDraw GX line with a width that is the average of the original pen's width and height. The gxReplaceLineWidthTranslation also affects the way the SetLineWidth PicComment is interpreted.

Once you set the translation option, your calls to GXSetShapePen() and/or GXSetStylePen() should behave as you expect them to, because they are acting on QuickDraw GX lines -- not polygons. When you have installed a translator, be sure to remove it with GXRemoveQDTranslator(). To learn more about the translation options, see:

Chapter 1 of Inside Macintosh: QuickDraw GX Environment and Utilities.

Inside Macintosh: QuickDraw GX Printing

Inside Macintosh: QuickDraw GX Graphics