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.
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 extended96on 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:
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 advancedcomputer 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 developIssue 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();
}
Theextern "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.*