MACINTOSH Q & A

MACINTOSH DEVELOPER TECHNICAL SUPPORT

Q In QuickDraw GX, if the QuickDraw clipping region of a window (set by SetClip(aRgn)) is not rectangular, the shapes drawn to the window's viewPort are sometimes clipped incorrectly. Is this a bug? 

A This is not a bug. QuickDraw GX doesn't honor any of the QuickDraw clipping regions except the one that's connected to a viewPort, created by calling the GXNewWindowViewPort routine.

Here's why: So that QuickDraw GX can draw into viewPorts associated with windows, it patches the Window Manager. When the user moves a window, or when your application calls BeginUpdate and EndUpdate, QuickDraw GX updates the viewPort caches and clip shape. The clip shape is set to the visRgn of the window. However, all other QuickDraw regions are ignored.

If you want to do some smart window clipping, you can. But you can't play directly with the viewPort attached to the window: that viewPort is maintained by the QuickDraw GX system and is therefore off limits to the application. (If you do try to manipulate it, you'll receive an error.) You need to attach a child viewPort to the window's viewPort; then you can convert the QuickDraw region you want to clip to into a GX shape (with the GX Translator) and set the child viewPort's clip shape to this new shape. Your QuickDraw GX shapes will then be clipped correctly.

Q Calling GXSetStyleRunControls on a layout shape with the "track" field set doesn't always have any visible effect, although the track value is always safely stored in the layout shape and can be retrieved with GXGetStyleRunControls. You can see this in GXWrite by adjusting the track kerning of some Tekton text: that works fine. If you switch to the Hoefler font, however, no track kerning is performed. Can you explain this? 

A When a track kerning value is specified, QuickDraw GX looks to the tables in the font to see how the kerning should be performed. A narrow text face with a large x-height, like Avant Garde, can probably take much tighter track kerning than something like Hoefler Italic can; only the font designer really knows how the kerning should behave. The font designer tells QuickDraw GX how to do track kerning by setting values in the 'trak' table of the font. This table contains one or more "reference points" -- values between -2 and 2 -- each of which tells how much to adjust space between the glyphs for any number of point sizes. If the specified track kerning value lies between reference points, QuickDraw GX interpolates accordingly.

Hoefler Italic contains only one reference point -- "normal" kerning (value 0). It does contain values for several different point sizes, but the font designer doesn't want the face more tightly or loosely kerned than in his original design. Since there's only one 'trak' point, QuickDraw GX winds up interpolating those entries with themselves and nothing really happens for the values you specify in the run controls. As you've noted, those values are still there, and they would be used if you switched those runs to a different text face, but they're having exactly the effect Jonathan Hoefler wanted -- none at all.

Q We're developing a QuickDraw GX printer driver for a 24-bit continuous-tone device. First, what should halftone fields be set to for a continuous-tone device (are they ignored?). Second, do we have to override GXDefaultPrinter and GXDefaultJob? The ImageWriter example shows building a default colorset inside GXDefaultPrinter. 

A The answer to your first question is that you can stop QuickDraw GX from using the halftone information by setting the gxDontSetHalftone flag in the plane flags field of each plane in the 'rdip' resource. That's it -- the halftone fields will be ignored.

The messages GXDefaultPrinter, GXDefaultDesktopPrinter, GXDefaultJob, GXDefaultPaperType, and GXDefaultFormat may be appropriate for your driver to override in order to modify default objects. You don't need to override these messages unless you have a reason to change the default object.

The ImageWriter driver with QuickDraw GX adds a list of view devices that are appropriate for the printer that's being used. Specifically, it adds a 144-dpi black-and-white view device and, if color is available, a 144-dpi color view device. If the driver didn't add these, the default printer view device (24-bit at 72 dpi) would be used. Overrides of a GXDefaultxxx message typically forward the message first to obtain the default object, and then modify that object as needed. So if you want more than one view device to be installed by your driver, you should override GXDefaultPrinter. That's what the ImageWriter driver is doing.

Q What is the correct way to recognize PowerTalk letters? Is it by checking for the file type 'lttr' or by looking at Finder flag bit 0x0200? Should I be saving letters as type 'lttr' or as my own file type, and should I be setting the bit? 

A The correct way of checking whether a particular document is a letter is to check the isLetter bit of the Finder info field. It's bit 9, mask 0x0200, and occupies the space formerly used by the "changed" bit.

Checking for file type 'lttr' doesn't work, since letters may have whatever file type the sending application desires. In fact, an application may support multiple letter types, and may have a different file type and icon for each type. This allows additional flexibility, since an application may have some idea what content the letter contains by checking its type, even before opening the letter.

Note that when your application saves a letter to disk, nothing special needs to be done with either the Finder flags or the file type to ensure that the Finder notices that the file created is a letter. SMPBeginSave and SMPEndSave will automatically set the isLetter bit for you, and the Finder will realize from this bit that your file is indeed a letter.

One final piece of information: Since letters may have a file type other than 'lttr', an additional hook was added to the Finder drag and drop mechanism to allow applications to have any letter drop-opened on them, regardless of the letter's file type. If you add a BNDL/FREF pair with the type 'ltr*' to your application, the Finder will highlight your icon whenever any letter is dragged over it. This mechanism works in the same way that '****' does for the universal drag and drop wildcard.

Q Can we use a different A5 world with QuickTime? Our plug-in architecture uses A5 for global access, but we allow the A5 world to move. QuickTime doesn't seem to appreciate this and doesn't think that EnterMovies has been called after the A5 world moves. We currently work around this by locking down our A5 world but would rather not. Is locking down the A5 world even good enough?  

A You can use a different A5 world with QuickTime. QuickTime allocates a new set of state variables for each A5 world that's active when EnterMovies is called. However, since QuickTime uses A5 to identify each QuickTime client, if you move your plug-in's A5 world QuickTime will no longer recognize that you've called EnterMovies for that client. So you can use a different A5 world, but you'll have to lock it down.

Q We're trying to display a QuickTime movie in a frame that can be panned, cropped, and overlaid by other objects. The movie controller doesn't seem to understand that the badge may lie entirely outside the frame. Is there some way to tell the movie controller where to place the badge?  

A Unfortunately, QuickTime isn't flexible about this. The code that positions the badge calculates it from the bounding box of the movie region, and insets it six pixels from the left and bottom. There's no sane way to work around this, other than not to use the standard badge, but instead use your own badge and perform your own badge tracking.

Q I've noticed some interesting behavior using the standard compression dialog and was wondering if someone could explain it to me. I'm trying to provide session-wide defaults for compressing sequences of images. If I don't prime the dialog by doing an SCRequestSequenceSettings, then when I do an SCCompressSequenceBegin the dialog is displayed. Is there any way to prevent this, and to use some set of defaults (without using an image to derive the defaults)? 

A The compression dialog components allow you to get settings with the SCGetInfo call, and to set them with SCSetInfo. The first time, you should display the dialog with SCRequestSequenceSettings, and then use SCGetInfo to retrieve the settings. After that, you can apply the same parameters before starting a compression sequence by using SCSetInfo. If you provide settings before calling SCCompressSequenceBegin, the dialog won't be displayed; otherwise it will be. See Inside Macintosh: QuickTime Components,  page 3-8 and pages 3-15 through 3-25, for details about the format of the settings.

Also, as you may know, you can generate default parameters that also avoid the dialog by using the SCDefaultPixMapSettings, SCDefaultPictHandleSettings, and SCDefaultPictFileSettings routines. But these do require an image. This way you can avoid displaying the dialog for the first sequence, and still generate valid settings. See Inside Macintosh: QuickTime Components,  pages 3-26 through 3-28, for more information about these routines.

Q When a user pastes a movie into a movie-controller movie, the added movie is inserted in the top left corner of the movie. Is there a way for the user to choose where the movie is pasted, and if not, how can I give the movie controller or Movie Toolbox an offset to use rather than have the editing operations use the top left corner? 

A When you paste a movie into a movie-controller movie, the movie controller is simply calling PasteMovieSelection to insert the source movie. All the characteristics of the movie are inserted, and therefore the movie is inserted in the top left corner of the movie. There's no easy way to specify an offset directly to the movie controller. If you want to change the offset of the pasted movie, you'll have to modify the movie yourself after the paste using Movie Toolbox commands. Once you're done changing the movie, be sure to call MCMovieChanged so that the movie controller updates correctly.

The actual modification is simple: call GetTrackMatrix, add your offset to the matrix, and call SetTrackMatrix. The difficulty is in determining which tracks to modify, since the paste may either create a new track or use an existing one. We recommend doing this by gathering all track indexes before the paste, and then comparing with the track indexes after the paste. Since most movies these days have just a few tracks, this shouldn't require much overhead. (But be warned: some movies do  have a lot of tracks!) To get the track information, you can call GetMovieTrackCount and GetMovieIndTrack.

One last idea: If you don't mind changing the source movie, an alternative is to simply offset the source movie before the paste.

Q Has Apple defined a codec type for a codec that does CCITT Group IV FAX compression/decompression? If not, how does one go about registering a brand new codec type with Apple? 

A We're not aware of any standard codec type for CCITT Group IV FAX. Apple doesn't have any mechanism in place for registering codec types. We suggest that developers use the creator code for their applications, since creator codes are unique, as long as they register them with us. We hope to have a better solution than this sometime in the future.

Q When I called Gestalt with the gestaltKeyboardType selector and my new Apple Adjustable Keyboard using System 7.1, I expected Gestalt to return a response that wasn't in GestaltEqu.h, but instead it returned an error of -5550, meaning "Couldn't obtain response." Is there something more I need to do? Should I expect Gestalt to return an error when I get new hardware? 

A Gestalt is in error in not being able to identify the adjustable keyboard. But the real problem (which the adjustable keyboard exacerbates) is that the gestaltKeyboardType selector doesn't really do what you want it to do. What you want Gestalt to do is enumerate the features of a system; however, gestaltKeyboardType tells you the type of keyboard most recently touched, which is of limited utility. In the past, it's been very rare to have more than one keyboard on a system, so the gestaltKeyboardType selector could give you a unique answer. But the adjustable keyboard is two separate keyboards -- one for the keyboard and one for the numeric keypad -- so gestaltKeyboardType can't give you a unique answer. Because of these problems, we consider this selector to be obsolete.

What you need is a way to list all the keyboard devices on a system. You can use the ADB Manager's GetADBInfo call to get the information for all the ADB keyboards connected. You'll see two keyboards connected if the whole adjustable setup is installed. The first will be at address $02 (all keyboards have an original address of $02); the second will be at an address between $08 and $0F, due to ADB remapping. Your first task would be to determine which ADB devices are keyboards. You can do this by using CountADBs to tell you how many devices there are, and then having a loop that calls GetIndADB for each device. For each device, you would test the original address field; if it's $02, you have a keyboard of some type. You can then use the handler ID of the device to identify the keyboard. The names and device handler IDs of the three main adjustable keyboards and the adjustable keypad are as follows:

U.S. standard adjustable keyboard   $10
ISO standard adjustable keyboard    $11
Japan adjustable keyboard           $12
Adjustable keyboard's keypad        $0E

Note that the keypad will usually be the one remapped and there's no way to guarantee that it will be remapped to a specific address. That's why you have to use CountADBs and GetIndADB to get the information.

Q Someone told me recently that the glue on postage stamps is made from horse hooves and other mammalian unmentionables. Is this true? I'm a strict vegetarian. 

A The glue used on postage stamps is not made from hooves or any other animal products. Although we're not sure exactly what it is  made of, we've been assured by the United States Post Office that the glue they use is vegan and  kosher. (International readers should check with their local postal services.)

Q Is there any reliable way of extracting the scaling information from a page setup record? We want to display a summary of the page setup in terms of paper size and scaling (for example, 8.5" by 11", 50%) instead of virtual page size (such as 17" by 22"). Can we assume that the editText item with a numerical value is the scaling field? 

A There is no reliable way to extract the scaling information. You certainly can't assume an editText item in a dialog is the scaling field -- it could be anything. Don't assume anything about the items or their order, because printer driver developers are free to do whatever they feel like, and most of them have. The ImageWriter allows only 50% reduction, for example, so it's a checkbox, not a numerical field. In some drivers such options may even be in the job dialog for "user convenience."

We've tried for a long time to come up with a reliable way to do this, and there just isn't one. Drivers can and do store scaling values, if they support them, anywhere they like in the print record. You can't compare the page rectangle to that returned by PrintDefault because the user may have picked a paper size other than the default. (You wouldn't want the user to choose legal paper and see 8.5" by 11", scaled 100% horizontally, 122% vertically!) This mechanism was designed to be transparent so that applications wouldn't have to do anything, but it was designed too  transparently: applications can't tell what the scaling is even if they want to. Note that the new printing architecture of QuickDraw GX actually lets you find out things like this.

Q I'm trying to draw text to a rectangle and am using TextBox, which works fine. What I want to do is determine the vertical coordinates of the bottom of the text in the text box. I want to draw a line right under the bottom of the text, and the text is arbitrary in length. One time it may be a single word, other times an entire sentence that wraps in the rectangle. Do you know any way to calculate what I need? 

A Unfortunately, you can't do it. TextBox doesn't leave the port in any state that can be counted on. However, all is not lost: TextBox is a relatively simple operation and can be easily duplicated with a few lines of code. If you duplicate TextBox, you can access the TextEdit record before it's destroyed. With access to the TextEdit record you can easily measure the text drawn. Try the code below. Also see "The TextBox You've Always Wanted" in develop  Issue 9 for a very flexible, fast replacement to TextBox.

void MyTextBox(Ptr text, long length, Rect *box, short just)
{
    // Replacement for TextBox that will draw a line under the last 
    // line of text.
    TEHandle te;
    Rect UnderRect;
    
    te = TEStyleNew(box, box);
    TESetJust(just, te);
    TESetText(text, length, te);
    TEUpdate(box, te);
    
    UnderRect = (*box);
    UnderRect.top = TEGetHeight(32767, 0, te) + UnderRect.top;
    UnderRect.bottom = UnderRect.top + 1;
    TEDispose(te);
    FrameRect(&UnderRect);
}

Q Is there any way for an application to mount an AppleShare volume in System 6? In System 7, the PBVolumeMount function allows you to do this if you have the right information. Is this call or a similar one supported in System 6?  

A The PBVolumeMount, PBGetVolMountInfoSize, and PBGetVolMountInfo calls are all supported in System 6 if  the AppleShare 3.0 or later Chooser extension has been installed. These versions of the Chooser extension have been tested back to System 6.0.4, and work fine.

Q Our product needs to access the DCD signal from the modem port to function correctly when talking to an external modem. Most documentation doesn't say anything about the DCD signal being available. However, we have a hardware diagram that shows that pin 7 on the mini-8 connector is connected to give a DCD signal on later Macintosh models. In most documentation pin 7 is shown as not connected. Is pin 7 connected to anything, so that I can wire it to the DCD signal from the modem? If so, how can I access the status of pin 7 to see when DCD is asserted or negated? If I can do this, what models of Macintosh will it work on, and will it stay like that in future releases? 

A There is ongoing confusion regarding the Macintosh serial ports and how to wire them for serial operation. Macintosh serial ports are RS-422. By shorting the positive receive pin to ground, you create an RS-423 port, which is an RS-232 emulation. The table below shows a pin-wiring schematic from the Macintosh DIN-8 to DB-25 RS-232 serial cable, which supports hardware handshake and DCD transmission (arrows show the direction of signal transmission):

Notice that we connect the DCD signal to the GPi input pin. As you know, the GPi trace isn't implemented on all Macintosh CPUs. Additionally, there is no serial driver call implemented to obtain the current state of the GPi pin. Rather than have a complete list of which CPUs it's connected on, you can fairly easily make your application dynamically find this out on a particular CPU at run time. So you can tell the user whether DCD from a modem can be detected on a particular installation, with no need for a priori knowledge. See the Macintosh Technical Note "Serial GPi (General-Purpose Input)" (Devices 16) for a description of using GPi and Gestalt.

Q I use the OpenPicture, draw, ClosePicture sequence to create a picture handle. Since the handle can be quite large, and since I dispose of it fairly quickly, it would make sense to allocate it in temporary memory. But I haven't found any reasonable way to do that. Any suggestions? Both these situations arise because my application runs in a fairly small (800K) partition. I do this so that other applications have adequate space to work with it, since one of my main functions is to interact with other applications using Apple events. However, I occasionally need more memory for a few seconds at a time. 

A There are two ways to cause OpenPicture to use temporary memory. A simple way to do it is to allocate a block of temporary memory, then create a new heap zone in that block and make it the current zone just before you call OpenPicture. This will cause subsequent memory allocations to happen in your temporary block, and will work fine. See Inside Macintosh: Memory  for more information about creating heap zones.

Another way is to replace the putPicProc, as is commonly done when spooling a picture to disk, and instead spool it to temporary memory. If you're not familiar with picture spooling, see Inside Macintosh  Volume V, page 89, which has code for spooling a picture to disk as it's created. This is the same technique as documented there, only it spools the picture to temporary memory instead.

You create a handle in temporary memory the size of a picture and fill in its size and picFrame fields so that it looks like a normal picture handle. In your putPicProc you copy the data in, continually resizing the handle if necessary to fit the data. After you call ClosePicture, remove your putPicProc; then you can use the temporary handle just like a normal picture.

The advantage of this method over the first one is that you can make the picture as large as temporary memory will let you, and you end up using just enough memory. The first technique, while technically easier to implement, limits you to the size of the heap you initially create, and you also may use a lot more temporary memory than you need. If you're able to come up with a good guess of how large your pictures are going to be, use the first technique; if not, use the second one.

Q I think I may have found a bug in the System 7 TrueType rasterizer code: under some clipping conditions it may crash/freeze the system inside the DrawText call. I'm really not doing anything out of the ordinary; the key to making it die apparently lies in the placement of an obstructing window that just barely overlaps the text being drawn. Investigating the problem in MacsBug reveals that somewhere deep in the TrueType rasterizer some code is trashing the A3 register and not restoring it properly. 

A This is a bug in QuickDraw's text-drawing routine, introduced when support for TrueType was added: QuickDraw (under certain circumstances, like foreground not black or background not white) allocates an off-screen buffer for the text on the stack. If there isn't enough stack space, the string is cut in pieces, and the code reentered for each piece separately. (If that still doesn't help, no text is drawn at all.) The bug is that A3 is assumed to hold the port throughout the text-drawing code, but when we added support for TrueType, we reused A3, forgetting the previous convention for the case where the string had to be subdivided. This probably won't be fixed before the rewritten QuickDraw is released in PowerPC processor-based machines.

The workaround is to preflight available stack space before issuing text-drawing calls for long strings and large point sizes, and draw the string in pieces yourself if necessary. You may also want to allocate more stack space at startup via

SetApplLimit(GetApplLimit() - something );

with something  empirically determined. For a big application with a large minimal partition size, 16K or 32K more or less in the heap shouldn't matter; but it's a big win for QuickDraw's reliability, and generally a good recommendation.

Q I would like to be able to determine the clock speed of any CPU. I know that I could write a routine and calculate the time it took to execute the code, but can you tell me a more direct way? 

A You can use the GetCPUSpeed routine to check the current clock speed of the PowerBooks (after checking gestaltPowerMgrAttr to make sure that the Power Manager is present). This routine is documented in the Power Manager chapter of Inside Macintosh  Volume VI (page 31- 20).

Unfortunately, there's no way to check the clock speed of other Macintosh models. The only thing you might be able to use as a crude way of comparing relative speeds is the low-memory global, TimeDBRA ($0D00). TimeDBRA gives you the number of iterations of DBRA per millisecond, which can help in a relative speed comparison.

Q A wonderful thing about MacsBug is that you can save logs, and our testers use it to log crashes of our programs under development. Unfortunately, some of our more lazy testers just send a log without a description of how they made the crash occur. I was wondering if there's a way a user can enter a comment in MacsBug that will get saved in a log but won't be interpreted by MacsBug. This way, users could put the whole bug report in one nice consolidated log, without going and editing it later in a text editor. 

A You can enter text into your MacsBug log by using the printf dcmd in MacsBug. It's similar to the C printf function. If your testers want to add anything to the log file, they can simply type

 printf "interesting comment that I wanted to make"

For more on the printf dcmd, see the MacsBug 6.2 reference manual.

Q I have problems linking my QuickDraw GX printing extension when I include MPW's StdClib.o, evidently because I call sprintf. I was told this is because of global variables in the StdClib.o library. Does MPW have a parallel library for use with standalone code -- something like THINK C's ANSI-A4 library? 

A The problem is that two of the routines in StdCLib.o use global data. You can get around this problem by redeclaring the problem routines in your code. First #include <StdIO.h> in one of your source files or included header files. Add the following to your source:

size_t fwrite(const void *, size_t, size_t, FILE *) { return 0; }
int _flsbuf(unsigned char, FILE *) { return 0; }

These lines redefine fwrite and _flsbuf, the offending routines, so that they don't use global data (or do anything, for that matter, except return 0). Make sure that the object file containing the above routines appears in your Link instruction before  StdCLib.o, since only the first declaration will be used. Of course, this means that you can't use the fwrite and _flsbuf routines, but it's unlikely you'll want to in a printing extension anyway. Also, sprintf never calls them. The linker will generate "duplicate symbol definition" warnings for the two routines, of course, unless you specify -msg nodup in your Link instruction. In addition, don't forget to link with RunTime.o.

The sprintf routine is great for debugging, since you can easily get formatted debugger output, as follows:

OSErr err;
Str255pStr;

// Do stuff that might cause an error
. . .

if (err) {
    pStr[0] = sprintf(&pStr[1], "Error %d", err);
    DebugStr(pStr);
}

Also, check out the dprintf command in QuickDraw GX's GXExceptions.h file; it's similar to this.

Q What is the correct term for the little depression above the center of my upper lip? In high school we called it a "curvicle," but I'm pretty sure we made that up.  

A The correct term is "philtrum." Biologists debate heatedly about its real purpose, but there's no doubt that it makes a good place to rest the tip of your index finger during periods of deep thought.

These answers are supplied by the technical gurus in Apple's Developer Support Center. Special thanks to Pete ("Luke") Alexander, Matt Deatherage, Godfrey DiGiorgi, Steve Falkenburg, Mark ("The Red") Harlan, Dave Hersey, Elli Howe, Joseph Maurer, Kevin Mellander, Jim Mensch, and Brigham Stevens 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 and in the Dev Tech Answers library on AppleLink.*