Macintosh Q & A

Macintosh Developer Technical Support

Q I'm about to write my first QuickDraw GX printer driver (for a laser printer) and plan to base it on the sample code "Generic LaserWriter." Is there anything I need to know about that code?

A There are two bugs that you might need to know about, depending on which version of the sample you're using. Both are very easy to fix.

• In versions previous to those in the QuickDraw GX Developer's Kit (which is now part of the Mac OS Software Developer's Kit), a device ID of $88 is specified in the file ChooserSupport.a. For QuickDraw GX, the device ID should always be $A9. (This bug also slipped through in the "LaserWriter--custom dialogs" sample in the Developer's Kit.)

• For all the versions of the code in the Developer's Kit, we improved the file ChooserSupport.c by adding better error handling, making everything universal, and removing unnecessary code; however, we forgot to add ALRT -4095 and DITL -4095 to the driver. If the Chooser code fails, it tries to put up a "You're hosed" alert, which doesn't exist. You should still use this improved version if you can; you can just copy the missing resources from any of the other sample LaserWriter drivers in the Developer's Kit.

Q I've just ported my application to the Power Macintosh and I want it to optionally use the Speech Manager. But if I try to launch the application when the Speech Manager isn't installed, the Finder puts up a dialog that says "The application `GonzoApp' could not be opened because `SpeechLib' could not be found." How can I get my application to launch in this case?

A The Finder refuses to launch your application because the Code Fragment Manager (CFM) believes your application is "hard linked" to SpeechLib. The CFM assumes your application can't run at all without SpeechLib and that all references to SpeechLib must be resolved. Since it can't locate SpeechLib, it refuses to launch your application.

To get around this, the CFM supports a concept called "weak linking." In this case, it allows references to the library to be unresolved at run time, and it's up to the application (that is, your code) to check that it's safe to make calls to the library. If you don't check, your application will crash the first time it tries to call the library.

The best way to check that a weak-linked library is installed is to check that the address of a function in the library has been resolved. For example:

Boolean HasSpeechLib()
{
   /*
    * Check the address of some function in the library.
    * SpeechManagerVersion is convenient.
    * kUnresolvedSymbolAddress is defined in FragLoad.h. 
    */
   return (SpeechManagerVersion != kUnresolvedSymbolAddress);
}

Note that this is not a replacement for using Gestalt to determine whether services are available; you should still use Gestalt to determine whether the Speech Manager is installed. The above code is an additional check for native applications, to ensure that the necessary library functions are available.

How you weak-link your application to a particular library depends on your development environment. Using the PPCC tools, you would specify weak linking with the following option to MakePEF:

-l SpeechLib.xcoff=SpeechLib~

Note the tilde (~) character at the end: this specifies a weak-linked library. In Metrowerks CodeWarrior, when you add SpeechLib to the project, the little pop-up menu on the right side of the project window will have an "Import weak" option that you can use to enable weak linking. Other development environments may use different methods for designating a weak-linked library.

Q To make my application localizable, I want to use ExtendedToString and StringToExtended to convert floats to strings and strings to floats. These routines, though, use the SANE extended format, which is quite archaic. What's the best way to convert a float to an extended to pass to ExtendedToString? It should compile on both 680x0 and PowerPC machines with MPW, Metrowerks, and THINK C.

A On PowerPC machines, extended80 and extended96 do not exist, except as structures. There are a number of (PowerPC-only) conversion routines in fp.h, like x80told. Your formatting code can be written as follows:

#include <fp.h>
#include <TextUtils.h>

void LongDoubleToString (long double ld,
                         const NumFormatString *myCanonical,
                         const NumberParts *partsTable,
                         Str255 outString)
{
#if defined(powerc) || defined (__powerc)
   extended80   x;

   ldtox80(&ld, &x);
   ExtendedToString(&x, myCanonical, partsTable, outString);
#else
   #ifdef mc68881
      extended80   x;

      x96tox80(&ld, &x);
      ExtendedToString(&x, myCanonical, partsTable, outString)
   #else
      ExtendedToString(&ld, myCanonical, partsTable, outString);
   #endif
#endif
}

Note that long double is equivalent to extended80 or extended96 on 680x0, and 128-bit double-double on PowerPC. If you want to format a double, just pass it in and the compiler will take care of converting double to long double or double to extended.

SANE.h is being replaced by fp.h, for both 680x0 and PowerPC. This issue's CD contains the libraries and interfaces for this new numerics package, which implements the Floating-Point C Extensions (FPCE) proposed technical draft of the Numerical C Extensions Group's requirements (NCEG/X3J11.1).

For more information on how to convert a SANE program to PowerPC, see Inside Macintosh: PowerPC Numerics, Appendix A. In principle, you should replace all use of extended with double_t. The double_t type maps back to long double for 680x0, which is the same as extended; for PowerPC, it maps to 64-bit double, which is the fastest floating-point format. Only when you read or write 80- or 96-bit SANE numbers to files, or when you want to use any of the Toolbox routines that take an 80-bit extended parameter, do you need to use conversion routines.

Q I'd like to automatically configure printing in portrait or landscape mode without requiring the user to go through the Page Setup dialog. How do I go about doing this?

A The traditional Macintosh printing architecture provides no support for changing the page orientation programmatically. At the time the Printing Manager was designed (about ten years ago!), there was kind of an overreaction regarding the principle of the user being in control, so we've had to live without a dependable way of changing a print record without the user's help. The good news is the QuickDraw GX printing architecture does support changing print dialogs programmatically, and QuickDraw GX will eventually be replacing the old printing architecture.

If you're interested in finding a workaround in the traditional printing environment, the only one we can offer is to prepare a couple of print records with the desired settings ahead of time and include them in your application. Then you can select the appropriate one based on the high-order byte of the TPrStl.wDev field of a validated print record. If the current printer driver has a value you don't know about, ask the user to go through the Page Setup dialog once to set landscape mode. Your application can then save the print record after it's filled out by PrStlDialog (again, indexed by the high byte of the wDev field).

The best method for saving the print record is to save it as a resource in your document's resource fork. Make your resource type something different from those used by the Printing Manager, to prevent the Printing Manager from getting confused and grabbing the wrong resource.

Remember, you need to be careful: watch the high byte of the wDev field, and call PrValidate before passing a print record to PrOpenDoc. Also, take a look at Inside Macintosh: Imaging With QuickDraw; pages 9-17 and 9-18 provide some valuable information.

Q I want to create a mask for a picture, such that the mask is 0 wherever the picture's pixels are pure white, and 1 everywhere else. My first try was to simply use CopyBits to copy the rectangle enclosing the PICT onto a same-sized rect in a 1-bit-deep offscreen world. This didn't work, however, as the yellows get transformed to 0, which is not what I want. I tried various transfer modes with CopyBits (from 0 to 100) to no avail. The SeedCFill and the CalcCMask routines don't seem to be what I want either, because it appears that their masks have to be keyed off a certain point or side(s). I can take the brute force approach and go through the pixels of the PICT one by one, checking to see if they're white and setting the mask accordingly, but this seems insane. Is there a good method for doing this?

A The way to do this is to install a custom color search procedure, then call CopyBits to copy into the 1-bit GWorld and let the search proc determine the color to use. The search proc would simply look at the color asked for and return white if it's white or black if it's nonwhite. See "Color Manager" in Inside Macintosh: Advanced Color Imaging (on this issue's CD and forthcoming in print from Addison-Wesley).

Q I heard that you can use LaserWriter 8.1.1 with QuickDraw GX with some patch. Is this true? If so, how?

A You can install an option called QuickDraw GX Helper. To do this, launch the installer document for QuickDraw GX and choose Custom Install from the pop-up menu in the top left of the window. A list appears with a bunch of options, with checkboxes next to them. Click the small triangle next to the QuickDraw GX Utilities option; then check the QuickDraw GX Helper option below that.

After you install and reboot, Helper will be available to you. It works only with old-style "classic" printing applications (though there's nothing classic about the old Printing Manager :-); if you're using a QuickDraw GX-savvy application, Helper won't help. When you're in a "classic" printing application, there's a new option, Turn Desktop Printing On (or Off) in the Apple menu.

Be aware that this is more than a patch. Literally, it's an unpatch! It removes some of the QuickDraw GX patches and is really a bit of a hack, provided for convenience. Because of this, there isn't much of an interface. For instance, when desktop printing is turned off, the printer used is the one selected the last time that "classic" driver was used. To change to a different printer, you need to reboot without QuickDraw GX, choose a new printer in the Chooser, then reboot again with QuickDraw GX.

Here are some additional things to note:

• Helper will choose LaserWriter 7.x over LaserWriter 8 (because LaserWriter 7.x was called "LaserWriter," whereas LaserWriter 8.x is called "LaserWriter 8," and the former is ordinally before the latter). As you probably know, QuickDraw GX can't tolerate multiple printer drivers with the same creator codes, so it just picks the first one. Therefore, you should ensure that you have only one driver of each type in your Extensions folder.

• Of course, before turning off desktop printing you need to ensure that you have the appropriate desktop printer selected: if you want LaserWriter 8.1.1 selected when you turn off desktop printing, make sure a LaserWriter is the selected desktop printer; if you want ImageWriter to be selected when you turn off desktop printing, make sure an ImageWriter is the selected desktop printer; and so on.

• Helper works only with Apple drivers. If you need to print with another driver, rebooting without QuickDraw GX is the only option.

Q I'm trying to get a gxFont ID based on a given font name (for example, "Times"), and I've run across a confusing situation using GXFindFonts. Below is the call I'm using, and it gives an "inconsistent parameters" error. Can you tell me why this error occurs and what I'm doing wrong? Using gxFullFontName doesn't work in finding the font in this case. Using gxNoFontName gives errors with or without the font family ID; when should this indicator be used?

GXFindFonts(theFontFamilyID,       // font family
            gxNoFontName,          // font name
            gxMacintoshPlatform,   // font platform
            1,                     // default -> gxRomanScript,
            1,                     // default -> gxEnglishLanguage,
            strlen(name),          // name length
            (unsigned char*)name,  // the name
            1,                     // matching font
            1,                     // number of matches
            &fontID            // font reference);

A GXFindFonts is the Swiss Army knife of font-finding routines. You can use it to find one font or a set of fonts. You can have it base the search on nearly any combination of family name, style name, script type, or other font properties. Unfortunately, the combination of arguments it expects in order to work in its myriad ways can be a bit confusing -- it's easy to cut your finger on one of the blades and get an "inconsistent parameters" error.

The first argument passed (font family) is itself a gxFont structure. This argument, if not nil, allows you to restrict the search to those fonts that have the same family as the argument.

Each gxFont has several types of name string associated with it. As documented on page 7-7 of Inside Macintosh: QuickDraw GX Typography, there's a font family string, style string, unique name string, full font name string, and so on for each font. The second argument passed to GXFindFonts (the meaning argument) is one of the gxFontNames constants listed on page 7-79. This argument, if not gxNoFontName, specifies which of the font's names to compare with the seventh argument to determine a match. If the second argument is gxNoFontName, GXFindFonts ignores the seventh argument and assumes that you're basing your search on other criteria, such as platform, script, or language (arguments 3, 4, and 5, respectively).

The seventh argument (name), if not nil, is the name string that you want to search for, and the sixth argument (nameLength) is the length of that string.

GXFindFonts may find more than one font that matches the criteria. The eighth argument (index) is the index of the first of these fonts that you want GXFindFonts to return. The ninth argument (count) is the maximum number of fonts that you want GXFindFonts to return. So, for example, if you specify criteria that match ten different fonts, but you want GXFindFonts to return only the fifth, sixth, and seventh of these fonts, you'd pass 5 for the index and 3 for the count.

The tenth argument (fonts) is a pointer to a buffer in which GXFindFonts will return the matches it finds. This argument can be nil if you don't want the fonts returned -- for example, if you just want to find out the number of matches to your desired search (the number of matches is returned as the function result).

You got an error because you passed in a string to search for (in the sixth and seventh arguments) and yet specified gxNoFontName in the second argument. These arguments are inconsistent; fortunately you were using the debugging version of GX and received an error.

But, to return to my pocket knife analogy, sometimes it's simpler and safer to use a Buck knife instead of a Swiss Army knife (only one blade, and it locks!). If getting a font ID based on a font name is all you need to do, you should consider using the FindCNameFont function in font library.c. With this routine you can simply call

fontID = FindCNameFont(gxFullFontName, name);

instead of the nasty, multiple-parameter GXFindFonts. There are several other useful tools in font library.c which are also worth a look.

Q Perhaps you can clear up a long-running dispute we've had in our office. Long ago I read that the "Mac" in MacsBug doesn't stand for Macintosh, but is an acronym for something that starts with "Motorola." Please put my mind to rest.

A MacsBug stands for Motorola advanced computer systems debugger.

Q My application is going to support only the four "required" Apple events plus one custom event (the application will have an 'aete' resource). What's the desired behavior of the 'pdoc' event? The real question is, if the user selects a file type that this application created and chooses Print from the File menu, should a dialog box be presented to the user? Obviously, if the application receives the event from another application or a scripting system, we don't want to display the Print dialog (possibly on a remote machine). Should the behavior be different if the Finder sends the event? Should there be one or two ways of handling the event?

A Here's how your application should behave upon receiving a 'pdoc' event: If all you get is a 'pdoc', you should just print without user interaction. The user, or whoever, is just using you as a service to print a document. Start your printing without any dialogs, using whatever default print record you get from PrDefault. You do not have to quit; the Finder will send you a 'quit' Apple event as the next event you get.

If you're already running (that is, you were started with an 'oapp' or 'odoc' event) and you get a 'pdoc' event, you should treat that one in the same way as a user Print menu selection. You might be required to put up a dialog. Always remember to call AEInteractWithUser before putting up a print dialog (or any dialog) to be sure you have the right to interact, and be prepared to use default actions if you can't interact.

Q The Macintosh Quadra 630 Developer Note, page 68, says "You should be familiar with the ATA IDE specification, ANSI proposal X3T9.2/90-143, Revision 3.1." Where can I find this document?

A Apple's implementation of IDE is documented in the Developer Notes for the Macintosh Quadra 630 and the PowerBook 150. The ANSI IDE standard has been renumbered as X3.221 Revision 4A, April 93. You can order it (and other ANSI documents) from Global Engineering Documents; call 1-800-854-7179 in the U.S., or (303)792-2181 elsewhere. The cost is $25 plus shipping.

Q I'm trying to print a document with over 60 different fonts in it under QuickDraw GX, and I get an (unknown) error -27881. The document doesn't print. Is this a bug? This document will, however, print on non-QuickDraw GX systems to the LaserWriter 8.1.1 driver and presumably other drivers as well. We haven't been able to find an equivalent to the non-QuickDraw GX "unlimited downloadable fonts" setting under QuickDraw GX. Is there a worka round to this problem? I realize that it's somewhat of a ridiculous case, but people do actually do this.

A This is not a QuickDraw GX bug. It seems likely, given the error you're seeing, that this is a problem with one of the fonts you're using.

If you use the gerror dcmd included with the QuickDraw GX Developer's Kit (or plow through the file graphics errors.h), you'll see that the error is font_scaler_streaming_aborted. This tells you that the streaming was aborted for some reason; a common reason would be that the naming table in the font is bad. You should be able to determine the exact cause of this using the PSMirrorFile extension (which you can find in the Printing Extensions folder in the Developer's Kit). This extension will log to a file the dialog with a PostScript printer; it really helps during debugging.

What all this implies is that one of the fonts you're trying to use is bogus. You need to determine which one is causing your problem and remove it. You may be able to do this by successively dividing your document into halves until you find the section of the document that's causing the problem.

Q I'd like to know how to do chroma keying in QuickTime. I'm under the impression that this is possible, but haven't been able to figure out how by digging through Inside Macintosh.

A All you need to do is call SetVideoMediaGraphicsMode, setting graphicsMode to transparent and setting opColor to whatever color you want to be transparent.

Media            theMedia;
MediaHandler     theHandler;
RGBColor         theKeyColor;

...      // Set up key color and get the track.

theMedia = GetTrackMedia(theTrack);
theHandler = GetMediaHandler(theMedia);
MediaSetGraphicsMode(theHandler, transparent, &theKeyColor);

Note that since QuickTime currently uses QuickDraw to do the compositing, this approach can be rather slow.

Q I'd like to add a volume control style slider to my dialogs. I don't really want to have to implement my own CDEF since this must have already been done by many others. Is there anywhere I can pick one up?

A In the Sample Code folder on this issue's CD, as part of AppsToGo, there's a sample program called Kibitz that uses a slider CDEF. You can use that one as the basis for writing your own control. You'll have the source as well as the object code. The code should be adaptable to your needs; if you don't like the way the slider looks, you can easily change it using a resource editor (the resource type of slider parts is 'cicn').

Q I'm writing a real-time video application and would like to open file data forks for reading/writing at interrupt time (in a deferred task). What's the best call to do this?

A You can open files at interrupt time as long as you make the PBHOpen, PBHOpenDF, or PBHOpenRF call asynchronously. These calls are always safe at interrupt time; they'll get queued if the File Manager is busy with another call, letting the current request complete before processing your request. See the article "Asynchronous Routines on the Macintosh" in develop Issue 13 for complete information. The article explains when, why, and how you should use functions asynchronously on the Macintosh.

Q I was relying on sample code from Inside Macintosh to spool shapes when printing under QuickDraw GX, but it seems to be causing my application to crash. The code I'm using is in Inside Macintosh: QuickDraw GX Environment and Utilities, on page 1-22, Listing 1-6. Is that code correct?

A The code is correct in the context in which it's given, but shouldn't be used for printing. Calling GXDisposeShape from the spoolProc while printing is what causes your crash: the QuickDraw GX printing mechanism disposes of the shapes for you.

Q I'm trying to incorporate the minimal support for QuickDraw GX printing in my application, and I've run into a problem. For a start, I'm using Simple Sample GX, the sample code Dave Hersey wrote for his article "Adding QuickDraw GX Printing to QuickDraw Applications" in develop Issue 19. I made necessary modifications to this code for the printing method I'm using: our printing is basically 90% text output, which is paginated on the fly based on the size of the print page that's returned by the printing code. Crashes occurred, however, and I finally narrowed them down to DrawText or DrawString calls with only one character, or only one character followed by a space. Is this a bug?

A Yes, it's a bug in the glyph code. We expect to fix this in the 1.1 release of QuickDraw GX (which should be available by the time you read this) but here's an easy workaround for QuickDraw GX 1.0.1 and 1.0: convert any glyph shapes to path shapes. In your spoolProc, after you get the shape type (as in Simple Sample GX), do this:

if (theShapeType == gxGlyphType)
   GXSetShapeType(currentShape, (theShapeType = gxPathType));

This will convert any glyphs to paths, and will circumvent the problems in the glyph code. I've verified that this works using Simple Sample GX and also in your test case. Note also that you will lose any hinting information, so the text may appear slightly different.

Q What's the data that's passed when the Drag Manager sends a catalog directory, of type flavorTypeDirectory? The documentation says it's a DSSpec, but it's too small. Is it a packedDSSpec?

A The documentation is wrong. It's a packedDSSpec, as you thought.

Q Our application needed a source of uniform random numbers to generate statistical distributions, and we used the built-in Random function for this. A number of our users need to know the algorithm of Random because statisticians (as any mathematician) need to produce a numerical audit trail to document their work. I looked at the assembly code of the Random function and couldn't recognize the method, although it looks similar to a linear-congruent generator. Could you tell me the source of the Random function? If you can cite a book, that would be great!

A The Random function in QuickDraw is based on the formula

randSeed := (randSeed * 16807) MOD 2147483647

It returns a signed 16-bit number, and updates the unsigned 32-bit low-memory global randSeed. The reference used when implementing this random number generator was Linus Schrage, "A More Portable FORTRAN Random Number Generator," ACM Transactions on Mathematical Software Vol. 5, No. 2, June 1979, pages 132-138.

The RandomX function in SANE uses the iteration formula

r = (7^5 * r) mod (2^31 - 1)

as documented on page 67 of the Apple Numerics Manual, Second Edition.

Q I want the users of my application to be able to grow the window without changing the aspect ratio. Is there a way to call GrowWindow but somehow be able to monitor the mouse position and modify the size of the rectangle while it's being dragged?

A The best approach is to write your own custom replacement for GrowWindow that does what you want (see the snippet called GridWindowGrow on this issue's CD for an example of a replacement GrowWindow routine). Another option, easier but not really what you're after, is to allow "free" dragging and then enforce the aspect ratio in your subsequent call to SizeWindow.

Q We're having a problem with MPW C++. We build our application requiring a 68020 processor or better and an FPU. The problem is that the MPW C++ compiler seems to create a CODE segment called Static_Constructors. This segment contains FPU-specific code and causes our program to crash on launch (ID 16) for machines without an FPU. Looking through code, I notice that at launch __RTInit is called, which in turn calls __CPlusInit. __CPlusInit loads the Static_Constructors segment and executes it, before the main segment is ever called. Can we fix this? How?

A This is a known C++ problem and is mentioned in the Macintosh Technical Note "MPW C++ Q&As" (PT 555) under "C++ static constructors and checking for an FPU." A workaround is mentioned in the note but not in much detail; a little more information follows here.

You need to rename __CPlusInit to something else, and write your own replacement that calls the real one only if the FPU checks are passed. You can rename __CPlusInit (from RunTime.o) by using the Lib tool with the "-rn" option. Write your own version like this:

extern "C" void __CPlusInit(void)
{
   // Do the gestalt on FPU.
   Renamed_CPlusInit();
}

The extern "C" is relevant, since you don't want a C++ mangled name to link against.

Q Under WorldScript, the itlbValidStyles field of the 'itlb' resource governs what styles can be applied to text, depending on the language of the font. I understand the reasoning -- underlining makes no sense for vertical scripts, extended text makes no sense for cursive scripts, and so on. However, we need to underline Kanji text. How should we do it?

A Underlining as implemented in QuickDraw was based on assumptions appropriate for Roman text -- specifically, that the underline should be just below the baseline. Unfortunately, the Asian scripts don't have the same definitions for baseline, ascent, and descent, and this creates an irreconcilable problem. Excluding the Roman characters and some punctuation, all the characters in the Kanji font descend below the QuickDraw baseline, so when QuickDraw tries to draw the regular underline it gets broken (in the same way it does with Roman descenders like g, j, and p -- only more so). Because it looked so bad, underline was disabled for the two-byte script systems. QuickDraw GX is the real solution to this complicated problem.

Barring that, you should just draw your own underlines manually, using QuickDraw, somewhere near the descent line. Exactly where is a matter of style. Because of that, we recommend that you do plenty of user testing, and be sure to look at other applications that do the same thing (MacWrite, PageMaker, QuarkXPress, WordPerfect, TurboWriter, and so on).

Two notes: First, Roman text that uses a Kanji font needs to follow this same convention, so that the underlines are consistent. (There may still be a problem when different fonts on the same line are underlined -- the lines won't necessarily match up.) Also, if the text's style is set to underline, PostScript will still draw the underline in the traditional location, even though it's not displayed on the screen! If you're printing to a PostScript printer, be sure the text's style isn't underline or you'll end up with two underlines. Good luck!

Q Why does a quarter have ridges on the edge?

A Several hundred years ago, certain enterprising souls would shave the edges off of coins. They would then spend the coins as usual and sell the shavings as bulk valuable metal. In an effort to combat this, governments began decorating the sides of coins so that it would be apparent if the currency had been tampered with. Any shaved coin could be refused by a merchant. The U.S. mint followed suit and put edges on all silver and gold coinage (dollar denominations, half dollar, quarter, and dime) to deter shavers. Although currency became silver-copper clad in 1965, thereby making the metal much less valuable, the decision was made to retain the edging for tradition's sake.

These answers are supplied by the technical gurus in Apple's Developer Support Center. Special thanks to Brian Bechtel, Mark Harlan, David Hayward, Dave Hersey, Larry Lai, Martin Minow, Dave Radcliffe, Jeroen Schalk, and Nick Thompson for the material in this Q & A column.*

Have more questions? Need more answers? Take a look at the Macintosh Q & A Technical Notes on this issue's CD.*