MACINTOSH Q & A

MACINTOSH DEVELOPER TECHNICAL SUPPORT

Q Our application uses the movie poster as a still frame in a cell, similar to using a PICT. If a user sizes the cell width so that it's narrower than the poster, even though we clip the drawing to the cell size, QuickTime posters draw their full width, writing over whatever is in the way. Pictures clip through DrawPicture; why doesn't ShowMoviePoster stay within the clipping region? 

A ShowMoviePoster, as well as the movie and preview showing calls, uses the movie clipping characteristics rather than the destination port's clipping region. You must set the movie's clipping region to obtain the results you want. An easier way to do this is to get the picture for the poster by calling GetMoviePosterPict, and then simply use DrawPicture to display the poster. Because this is just a picture, the clipping region of the port is honored. This way you don't need different code for movies and pictures.

Q Our QuickTime application gets a Sound Manager error -201 after playing movies in succession, apparently because sound channels used in the previous movies have not been reclaimed. How does QuickTime decide to deallocate sound channels? It doesn't seem to happen in my "while (!IsMovieDone(theMovie) && !Button())" play loop. 

A Sound channels are released by active movies when they notice that some other movie needs them. This is currently done only at MoviesTask time. Before entering your loop to play a single movie, you can do one or both of the following:

• Preroll the movie you're about to play and check the error. If preroll returns -201, call MoviesTask(0,0) to give the other active movies a chance to give up their sound channels. A subsequent preroll of theMovie should return noErr.
• Call SetMovieActive(otherMovies, FALSE). Deactivate the movies that you aren't playing to force them to give up their resources.

Q When I select all frames in QuickTime and then do an MCCut or MCClear, the standard controller gets larger and redraws itself at the top of the movie. Is this a situation I should be prepared to handle or a bug? Does the controller behave strangely when the selectionTime of a movie is -1 or when the duration of the movie is 0? 

A The behavior you're observing is to be expected if the controller is attached to the movie. In this case, the controller goes to wherever the bottom left corner of the movie box takes it. If the movie loses all its "visible" parts, the movie controller will jump to the top of the window. The only way to get around this is to detach the controller when the movie box is empty; this is also something to keep in mind for the cases when the movie contains only sound, since pure sound movies have no dimensions. You can find sample code showing how to do this on the Developer CD Series  disc, in the SimpleInMovies example that accompanies the QuickTime article in develop  Issue 7.

Q Stepping through QuickTime movie video frames in the order they appear in the movie is simple using GetMovieNextInterestingTime, except for getting the first frame. If I set the time to 0 and rate to 1, I get the second frame, not the first. In addition, the video may start later than at 0. How do you suggest finding this first frame of video? 

A To get the first frame under the conditions you describe, you have to pass the flag nextTimeEdgeOK = $2000 to GetMovieNextInterestingTime. What this flag does is make the call return the current interesting time instead of the next, if the current time is an interesting time. You need to do this because there's no way to go negative and then ask for the next interesting time.Q I save PICTs to my document's data fork by writing the contents of the PicHandle. To save movies, do I convert the movie to a handle, and then save that as I would with PICTs? I just want the file references, not the data itself. 

A To save movies that are suitable for storage in a file, use PutMovieIntoHandle. The result of this call can be saved in the data fork of your files, and then you can call NewMovieFromHandle to reconstruct the movie for playback or editing.

You should also read the documentation regarding the Movie Toolbox FlattenMovie procedure, which creates a file that contains the 'moov' resource and the data all in the data fork. The advantage here is that the movie file you create using FlattenMovie can be read by any other QuickTime-capable application.

Q How can I identify the sender of an Apple event? 

A If your application is just sending a reply, it should not be creating an Apple event or calling AESend. Instead, the Apple event handler should stuff the response information into the reply event, as shown on page 6-50 of Inside Macintosh  Volume VI. The Apple Event Manager takes care of addressing and sending the event.

To find the target ID or process serial number of the sender of an Apple event, use AEGetAttributePtr to extract the address attribute, as follows:

retCode := AEGetAttributePtr(myAppleEvent, keyAddressAttr, 
						typeWildCard, senderType, @senderBuffer, 
						sizeof(senderBuffer), senderSize)

The senderBuffer can later be used with AECreateDesc to create an address to be passed to AESend. The buffer should be at least as large as data type TargetID. See Inside Macintosh  Volume VI, page 5-22, for a description of TargetID.

Q When I resize my real-time animation window in System 6, I call UpdateGWorld with the new size, and after that any drawing into the GWorld has no effect. This same code works perfectly in System 7. What could cause this? 

A You probably can't draw anything into your GWorld after using UpdateGWorld to resize it because of the clipping region of your GWorld. In system software versions before 7.0, UpdateGWorld always resizes the GWorld's clipping region proportional to the amount that the GWorld itself is resized. Unfortunately, NewGWorld initializes the clipping region of the GWorld to the entire QuickDraw coordinate plane, [T:-32767 L:-32767 B:32767 R:32767]. If UpdateGWorld resizes any of these coordinates so that they fall outside this range, the coordinates wrap around to the other end of the signed integer space, and that makes the clipping region empty. Empty clipping regions stop any drawing from happening.

The change in System 7 is that UpdateGWorld explicitly checks for the clipping region [T:- 32767 L:-32767 B:32767 R:32767]. If it finds this, it doesn't resize the clipping region. Otherwise, UpdateGWorld acts the same way that it did before System 7.

One of our mottos is, "Never give QuickDraw a chance to do the wrong thing." In keeping with that, we always explicitly set the clipping region of a GWorld whenever we change the size of the GWorld. So after calling NewGWorld, set its clipping region to be coincident with its portRect. After calling UpdateGWorld to resize the GWorld, set its clipping region to be coincident with its new portRect. That way, you'll always have a known environment and you won't have to worry about the change that was made in System 7--and you'll be less susceptible to bugs in this area in the future.Q UpdateGWorld doesn't seem to respond to the ditherPix flag unless color depth changes. The return flag after changing my color table is 0x10000, indicating that color mapping happened but not dithering. Is this a bug? 

A Yes, this is a bug. UpdateGWorld ignores dithering if no depth change is made. It probably won't be changed in the near future. The workaround is as follows:

1. Create a new pixMap with the new color table.
2. Call CopyBits to transfer your image to the newly created pixMap with dithering from the original GWorld's pixMap.
3. Update the GWorld with the new color table without using ditherPix.
4. Use CopyBits from the newly created pixMap without dithering back to the GWorld.

This will give you the same effect as UpdateGWorld with ditherPix.

Q Can I create, open, write, and close a file completely at interrupt time? I need to be compatible with both System 6 and System 7. 

A All these operations (and more) can be done completely at interrupt time. Any call that can be made asynchronously can be safely made at interrupt time, provided it's made asynchronously. Glancing through Inside Macintosh  Volume IV, we can see that this includes just about all of the File Manager, except for the calls to mount and unmount volumes, which must be made at a time when it is safe to move or purge memory.

One caveat: Making a call asynchronously here means really  making it asynchronously; making the call and then sitting in a little loop waiting for the ioResult field to change does not qualify. Either you must use completion routines to determine when a call has completed, or you must check the ioResult from time to time, never waiting for it at interrupt time (and in this case, a deferred task does qualify as being at interrupt time).

Q How can I tell whether a window is a Balloon Help window? 

A First, call the Help Manager procedure HMIsBalloon to determine whether a balloon is being displayed at all. Then call HMGetBalloonWindow to get the help window's window pointer, and compare that to the window pointer of the window you've got.

Note that if HMIsBalloon returns TRUE and HMGetBalloonWindow returns a window pointer of NIL, it means that the balloon "window" that's displayed really isn't a window at all; this will happen, for instance, if the balloon is being displayed on top of a pulled-down menu (we call this "to boldly go where no window has gone before").

Q How can I tell whether a font is monospaced or proportional? The FontRec record's fontType field doesn't correctly tell me whether the font is fixed width as Inside Macintosh Volume V says it should. All system fonts appear to have the same fontType regardless of whether they're fixed or proportional. Currently I test whether the width of the characters "m" and "i" are equal and if they are, I consider the font to be fixed width. Is there an easier (and faster!) way? 

A The Font Manager documentation is not explicit enough about the fact that bit 13 (0x2000) of the fontType field is useless. The Font Manager doesn't check the setting of this bit, nor does QuickDraw (or any printer driver). As you observed, monospaced fonts like Monaco or Courier don't have the bit set; the bit is meaningless. In addition, the fontType field is available only for 'FONT' and 'NFNT' resources; it does not exist in 'sfnt' resources, and you would have to check separately for the resource type of the font. Your idea of comparing the widths of "m" and "i" (or any other characters that are extremely unlikely to have the same widths in a proportionally spaced font) is indeed the only reasonable way of figuring out whether a font is monospaced.Q The TrueType system extension (INIT) apparently renders glyphs differently with System 6 than with System 7. For example, our "abc" string in 160-point Helvetica ® is almost half as many pixels under System 7, so the styled text no longer lines up with the bitmapped graphics underneath. Any way to avoid this?

System 6

System 7

A Your System 6 configuration probably has the specific Helvetica Bold TrueType outlines available, while this Helvetica Bold TrueType version is missing in your System 7. When the Font Manager gets a request for Helvetica, txSize 160, txFace bold, it looks in the font association table of the Helvetica FOND (font family record; see page 37 of Inside Macintosh  Volume IV). First, it looks for the right size (yes, there's a TrueType outline font: size requirement fulfilled), then it looks for the style (oops, no Bold variant of the font available; must ask QuickDraw to apply its algorithmic "smearing" to produce a bold version of it).

Unfortunately, the QuickDraw emboldening always works the same way, regardless of the size of the character: it just smears the character horizontally by one pixel--which is rather ineffective for big point sizes and, of course, quite different from the typographically truly bold outline of the Helvetica Bold font.

By the way, if you choose the stylistic variants outline or shadow, the result is equally disappointing, because there are no specific TrueType versions available for Helvetica Outline or Helvetica Shadow.

In conclusion, the only way to avoid this problem is to make sure your users have the required font versions in their system. You may want to include this as a recommendation in the manual, or even to come up with an alert in your application if there's no Helvetica Bold in the system. Unfortunately, there's no easy, built-in way to check for this; IsOutline returns TRUE even when there's no Helvetica Bold, because the Helvetica TrueType font is used to render the character in the first place; the QuickDraw smearing is applied in a second step, and is not considered for the result of IsOutline. You would have to take the Helvetica FOND and walk its font association table "by hand."

Q My application calls SetOutlinePreferred so that TrueType fonts are used if both bitmapped and TrueType fonts are in the system. It was reported to me, however, that some international TrueType fonts look really bad at small point sizes on the screen. Should I avoid calling this function? 

A SetOutlinePreferred is best used as a user-selectable option. Along the same lines, you might want to include the SetPreserveGlyph call ( Inside Macintosh  Volume VI, page 12-21)--again, as a user-selectable option.

Currently, the default for outlinePreferred is FALSE for compatibility reasons (existing documents don't get reflowed if the bitmapped fonts are still around) and for aesthetic and performance reasons (users are free to maintain bitmapped fonts in the smaller point sizes if the TrueType version isn't satisfying for small sizes or is too slow). On the other hand, as soon as a bitmapped font is unavailable  for a requested point size, and a TrueType font is present, the TrueType font is used even with outlinePreferred = FALSE. Setting outlinePreferred = TRUE makes a difference only for point sizes where a bitmapped font strike is present along with an 'sfnt' in the same family. TrueType fonts might be preferable even for small point sizes if linearly scaled character widths are more important than screen rendering: if the main purpose of a program is preprint processing for a high-resolution output device, outlinePreferred = TRUE may give better line layout results on the printer, at the price of "not so great" type rendering on a 72 dpi screen. (An example of the conflict between linearly scaled TrueType and nonlinearly scaled bitmapped fonts is Helvetica: StringWidth('Lilli') returns 19 for the 12-point bitmapped font, and 15 for the 13-point size from TrueType!)

All this boils down to the recommendation stated initially: the user should be given the flexibility to decide whether to use the existing bitmaps (using TrueType only for bigger point sizes and high-resolution printers), or to go with TrueType even if the result on the screen is not optimal. (By the way, it's likely that TrueType development will substantially reduce this conflict in the future.)

Q When you bring up the Finder windows under System 7 on a color system and click a control panel item icon, it paints itself that fancy gray. How can I get that effect? 

A To get the fancy System 7 icon dimming to work in your program, read Macintosh Technical Note #306, "Drawing Icons the System 7 Way," and use the icon-drawing routines contained in it. The routines show how to use the Icon Toolkit, which is what the Finder uses. If you want the same effect under System 6, you'll have to emulate the dimming of the icons via QuickDraw; the IconDimming sample code in the Snippets folder on the Developer CD Series  disc shows how to do this.

Q When the OK button is disabled in the System 7 Standard File dialog box, it's drawn in gray. I was looking for sample code on how to do this in a way that's appropriate for multiple screens at various color depths. For example, how should you draw the outline if you have an OK button in a movable modal dialog box with half the OK button on an 8-bit color screen and the other half on a 1-bit monochrome screen? 

A There are two ways to draw the gray (dimmed) outline across several screens in different depths: one uses MakeRGBPat (Inside Macintosh  Volume V, page 73), the other uses DeviceLoop (Inside Macintosh  Volume VI, page 21-23). Look for GrayishOutline.p in the Snippets folder on the Developer CD Series  disc for a code sample that demonstrates both ways.

Q If the Epcot Center building "Spaceship Earth" were a golf ball and you were proportionally tall enough to hit it, where would it land? 

A Zimbabwe.

Q How do you determine whether the Picture Utilities Package function GetPictInfo is available? Gestalt doesn't seem to have the right stuff! 

A To determine whether the GetPictInfo routine is available, check the system version number with the Gestalt function. GetPictInfo is available in system software version 7.0 and later. Use the Gestalt selector gestaltSystemVersion to determine the version of the system currently running. Usually it's best not to rely on the system version to determine whether features are available, but in this case, it's the only way to determine whether the Picture Utilities Package is available.

For example, the following C function will determine whether the GetPictInfo call is available:

#include <GestaltEQU.h>
Boolean IsGetPictInfoAvail()
{
	OSErr err;
	long feature; err = Gestalt(gestaltSystemVersion,&feature);
	/* Check for System 7 and later */
	return (feature >= 0x00000700);
}

In Inside Macintosh  Volume VI, see page 3-42 for information on using Gestalt to check the system version number, and see page 18-3 for information on the Picture Utilities Package.

Q How can I directly access the alpha channel (the unused 8 bits in a 32-bit direct pixel using QuickDraw) under System 7? Under System 6 it was easy, but under System 7's CopyBits the alpha channel works with srcXor but not with srcCopy. 

A With the System 7 QuickDraw rewrite, all "accidental" support for the unused byte was removed, because QuickDraw isn't supposed to operate on the unused byte of each pixel. QuickDraw has never officially supported use of the extra byte for such purposes as an alpha channel. As stated in Inside Macintosh  Volume VI, page 17-5, "8 bits in the pixel are not part of any component. These bits are unused: Color QuickDraw sets them to 0 in any image it creates. If presented with a 32-bit image--for example, in the CopyBits procedure--it passes whatever bits are there."

Therefore, you cannot rely on any QuickDraw procedure to preserve the contents of the unused byte, which in your case is the alpha channel. In fact, even CopyBits may alter the byte, if stretching or dithering is involved in the CopyBits, by setting it to 0. Your alternatives are not to use the unused byte for alpha channel storage since the integrity of the data cannot be guaranteed, or not to use QuickDraw drawing routines that can alter the unused byte.

Q When used from MPW C++, pragma unused, pragma force_active, and pragma once don't appear to work. In fact, pragma unused actually causes a C compile-time error. Why does this occur in spite of assurances in release notes that all pragmas are passed on to the C compiler? 

A The problem with pragmas and C++ is that the CFront compiler generates C code, and during this phase it also shuffles around the source code lines, so the pragma doesn't end up in the same place as originally intended. Also, CFront moves any pragmas inside the function body outside, because it can't do much with the pragmas, and the best bet is to move them just outside the body for the C compiler. This means that any pragmas stated inside the function body are unusable in real life.

Here's a summary of how pragmas work with C++:

• pragma segment, pragma parameter, and pragma processor should work OK.
• pragma force_active may or may not work, depending on the code case.
• pragma warnings and pragma pop/push should work in most cases, depending on the code movement.
• pragma trace should also work, especially if it's defined just before a function or member function.
• pragma unused and pragma once won't work, alas.

For more information about pragmas and C++, please consult the MPW 3.2 C++ documentation.

Q Inside Macintosh Volume II, page 33, states that _GetHandleSize returns D0.L >= 0 if the trap is successful or D0.W < 0 if the trap is unsuccessful. What happens if the handle size is 0xFFFF, for instance? A TST.W will indicate an error when in fact there is none. How should I check for this condition? 

A Inside Macintosh  is correct (although confusing) regarding the determination of an error condition. The way to do it is first test the long to see if it's valid (D0 >= 0). If the long is valid, you can continue with confidence that no error occurred. If, however, the long in D0 is negative, the low word contains the error (and currently the high word contains $FFFF, the sign extension). The reason the manual highlights the fact that only the low word contains the error is to allow you to save the error in standard fashion since all other errors are word sized, and also to caution you against using the processor status on exit from GetHandleSize since it will be based on the low word only. In other words, if the long is negative, simply ignore the high word. Here's some assembly code that will work:

	move.L	theHandle(a6),A0
	_GetHandleSize
	tst.L	D0
	bpl.s	@valueOK
	move.W	D0,theError(A5)
	moveQ	#0,D0
@valueOK

Q What are recommended values for retry interval and retry count when using the AppleTalk NBP call PLookupName on a complicated internet? 

A You might want to start with the NBP retry interval and retry count values Apple uses for its Chooser PRER and RDEV device resource files. The Chooser grabs these values from the PRER's or RDEV's GNRL resource -4096:

The count value should be based on how likely it is for the device to miss NBP lookup requests. For example, the AppleTalk ImageWriter has a dedicated processor on the LocalTalk option card just to handle AppleTalk, so its count value is low; most Macintosh models and LaserWriter printers depend on their 680x0 processor to handle AppleTalk along with everything else in the system (the Macintosh IIfx and Macintosh Quadra models are exceptions to this), so their count value is higher.

The interval value should be based on the speed of the network and how many devices of this type you expect there to be on the network. On a network with very slow connections (for example, one using a modem bridge), or in cases where there are so many devices of a particular type that lots of collisions occur during lookups, the interval value should be increased.

Apple puts these values in a resource because not all networks and devices are alike. You should do the same (put your interval and count in a resource so that it can be configured).

Q I'd like to use the same names that the system uses to identify itself on the AppleTalk network in my program. Where can I find those names? 

A The names used by the system for network services are stored in two 'STR ' resources in the System file. Your program can retrieve those names with the Resource Manager's GetString function. Only one of the names is available in systems before System 7: the name set by the Chooser desk accessory. That name is stored in 'STR ' resource ID -16096. With System 7, the Sharing Setup control panel lets the user assign two names for network services: the Owner name and the Computer name.

The Owner name is the name stored in 'STR ' resource ID -16096; it identifies the user of the Macintosh. The Owner name is used by System 7 for two primary purposes: to identify the owner of the system when accessing the system remotely through System 7 file sharing or through the user identity dialog used by the PPC Toolbox (and Apple Event Manager), and to serve as the default user name when logging on to other file servers with the Chooser.

The Computer name (also known as the Flagship name) is the name stored in 'STR ' resource ID -16413; it identifies the Macintosh. The Computer name is the name used by system network services to identify themselves on the AppleTalk network. For example, if your system's Computer name is "PizzaBox," the PPC Toolbox registers the name "PizzaBox:PPCToolBox@*" when you start program linking, and file sharing registers the name "PizzaBox:AFPServer@*" when you start file sharing.

Q What's the recommended technique for telling whether the user has turned off AppleTalk? 

A The best way to determine whether AppleTalk has been turned off is to use the AppleTalk Transition Queue to alert you to .MPP closures. (This is one of the reasons why the AppleTalk Transition Queue was implemented.) The AppleTalk Transition Queue is available only in AppleTalk version 53 or later, and is documented in the AppleTalk chapter of Inside Macintosh  Volume VI, starting on page 32-17. There's also a code snippet, Transition Queue, in the Snippets folder on the Developer CD Series  disc.

Q Sometimes when my system extension (INIT) starts executing, the current zone is the system zone rather than the application zone. Should I call SetZone(ApplicZone) before allocating memory in the system extension? 

A The system does not set the zone to the application zone before loading each system extension, so if a previous extension left the zone set to the system zone, it's possible that an extension could unintentionally be loaded into the system heap and have the current zone be the system zone.

To ensure that nonpermanent memory requested by a system extension is allocated in the application heap, do a SetZone(ApplicZone) before calling NewHandle or NewPtr. Any system extension that calls SetZone should restore the current zone to what it was upon entry.

Any permanent memory allocation by a system extension should be made in the system heap with NewPtrSys or NewHandleSys. Use a 'sysz' resource if the system heap allocations will exceed 16K.

Q Are there any new rules regarding SCSI driving with virtual memory? My System 6 driver doesn't work with System 7. 

A It's important to remember that VM usually uses a SCSI device for its backing store. As such, if VM needs to use your driver it can't tolerate a driver's page swap in the middle of a page swap. This means if your driver's code is not in the system heap, it needs to be held when called, and your buffers also need to be held if your driver is entered by a Control or Status call. Buffers are automatically held by the system if your driver is entered by a Read or Write call. The following documents provide a good overview of what you need to do to revise a SCSI driver for VM compatibility. * Inside Macintosh  Volume VI, which contains new information specific to virtual memory as it relates to drivers and especially SCSI

• Macintosh Technical Note #285, "Coping with VM and Memory Mappings"
• "VM Paper" from the System 7 CD in the VM Goodies folder

Q I discovered an interesting bug in the Macintosh LaserWriter driver. If the word "timeout" is in the name of a document, the LaserWriter driver will give a timeout error -8132. Are there similar magic words? 

A PostScript error messages are sent from the LaserWriter to the driver as text streams. The driver must check these strings to see if they contain an error message. If a document is named something that contains the same string as a PostScript error message, the driver may think there's an error when the printer sends the "status: printing document XXXXX" message. Other strings cause similar problems; one of them is "printer out of paper." If you want to see the rest of the strings, take a look at the LaserWriter printer driver resource type 'PREC' ID = 109.

Q What do the terms "maney" and "fakey" mean? 

A These are slang words commonly used in California. "Fakey" means you're riding your snowboard backwards. "Maney," often applied to snowboarding, is derived from "maniac"; it means intense, high-energy, absorbing maximum consciousness. It also has allusions to the mane of a lion, as in the pride of the lion. Nietzsche might have equated "maney" with "will to power."

Kudos to our readers who care enough to ask us terrific and well thought-out questions. The answers are supplied by our teams of technical gurus; our thanks to all. Special thanks to Pete ("Luke") Alexander, Tim Dierks, Steve Falkenburg, Bill Guschwan, C. K. Haun, Dave Hersey, Dennis Hescox, Rich Kubota, Edgar Lee, Jim Luther, Joseph Maurer, Kevin Mellander, Jim Mensch, Guillermo Ortiz, Craig Prouse, Dave Radcliffe, Greg Robbins, Kent Sandvik, Gordon Sheridan, Bryan ("Stearno") Stearns, Brigham Stevens, Sriram Subramaniam, Forrest Tanaka, John Wang, and Scott ("Zz") Zimmerman for the material in this Q & A column. Thanks also to developer Bruce Ballard for his graphics sample. *

Looking for the Apple II Q & A section? It's gone. See the Editorial for details.*

Have more questions? Need more answers? Take a look at the Dev Tech Answers library on AppleLink (updated weekly) or at the Q & A stack on the Developer CD Series  disc.*