Macintosh Q & A

Macintosh Developer Technical Support

Q What operations cause QuickDraw GX to invalidate its shape caches? We want to maximize drawing performance in our application, and it would be nice to know ahead of time when caches will need to be rebuilt.

A As you might imagine, this topic is complex, but we'll try to explain the basics and give you some ideas about improving performance.

There are several caches associated with a shape, since each object associated with the shape has a separate cache. (By the way, the caches are in the QuickDraw GX heap and can be seen using GraphicsBug.) Every time you call GXDrawShape, QuickDraw GX determines which caches need to be updated, updates them, and then draws the shape. So the first thing to know is that if you want GXDrawShape to execute as fast as possible (for instance, if you're drawing several shapes and want the time between successive GXDrawShape calls to be minimal), you should call GXCacheShape ahead of time to update the shape's caches, minimizing the work GXDrawShape needs to do.

In general, any time you change information within a shape, you cause QuickDraw GX to invalidate at least one of the shape's caches. Layout shapes are exceptions to this rule, however. The cache associated with a layout shape will not be invalidated if all of the following conditions are met:

• You're adding characters to the end of the layout shape.
• There's a single run of text within the layout shape.
• The shape remains on the same device.

If you're drawing non-hairline geometric shapes and want to get them on the screen as fast as possible, you can set the gxCacheShape attribute of the shape. With this attribute set, QuickDraw GX will preprocess all the required parts of a shape into compressed bitmaps. This means the shape is completely ready to be drawn when you call GXDrawShape: the bits are just blasted to the screen.

Any time you change a view port's clip or mapping, QuickDraw GX will update all of the caches for the shapes and child view ports associated with that view port. There isn't any speed advantage to setting the clip or mapping of a shape rather than the clip or mapping of the shape's view port; the same work has to happen in either case. Note, though, that if the view port contains other shapes or has child view ports, their caches will be invalidated, too. You should change the view port's mapping to move a shape only when you want all shapes within the view port to move the same amount.

Q I'm looking into the possibility of writing a QuickDraw GX printer driver that will only print to a file, and I've run into a couple of stumbling blocks I hope you can help with. First, is there a way to create a desktop printer from the Chooser without having an actual printer attached or selecting a port? Can I get to the Chooser list so that I can display some kind of dummy or ghost printer? The second issue has to do with the user interface of the Print dialogs/panels. I would like to set the "Destination: File" radio button and disable the "Destination: Printer" one for QuickDraw GX application interfaces.

A There should be no problem creating a printer driver that only prints to a file. And yes, users will be able to create a desktop printer from such a driver. You can access the Chooser list: for an example of this, look at the source code file Chooser.c from any of the QuickDraw GX printer driver samples. You can do whatever you want within the Chooser to handle and display lists of available printers for the currently selected printer driver. You'll also need to modify the 'comm' resource to make sure that the Chooser does the right thing. You should be able to put a "nops" 'comm' resource reference into the 'look' resource.

You can disable any item in the Print dialog by overriding the GXJobPrintDialog message and, in your override, getting the destination tag for the appropriate item and locking it. This will make the item appear disabled in the dialog. PrintingMgr.h contains all the tags you can lock. You should be sure to set up the item to be gxVolatileOutputDriverCategory so that your settings go away if the user switches drivers in the pop-up menu; you can simply OR this with collectionLockMask when you set the item's attributes.

Q The documentation seems a bit thin on what resource type/ID is needed for ColorSync profiles in QuickDraw GX printer drivers. Is the appropriate type 'prof' or 'cmat'? Will QuickDraw GX automatically use one if I stick it in my driver, or do I also have to override the various profile messages?

A All you need to do is include a 'cmat' resource with ID gxColorMatchingDataID and specify it in your 'rdip' resource. However, you should also override GXFindFormatProfile so that inquiring applications can ask you what the format's profile will be. Additionally, you should override the GXImagePage message if you want to provide different profiles on a page-by-page basis.

Q I'm working on QuickDraw GX printer drivers. Can you give me some information on what must be done to support PrGeneral?

A PrGeneral support within your QuickDraw GX printer driver is automatic. The printing system will automatically maintain the appropriate information within the QuickDraw GX print record. The only exception to this automatic support is the SetRsl opcode: if you don't want QuickDraw GX to use the default gxReslType resource when the SetRsl opcode is used, you need to define a gxReslType resource of your own that reflects the capabilities of your printer.

Q Our application generates its own custom PostScript ^TM code when printing to PostScript printers. We'd like to support QuickDraw GX-style printing and still be able to continue generating our own custom PostScript code to send directly to the printer. What's the best way to handle this? I've tried generating empty shapes with custom PostScript code attached as a tag (using synonyms), but the LaserWriter QuickDraw GX driver emits its own "wrapper" code around our custom PostScript code, which could alter the printer's graphics state. Are there any other methods to achieve this without the possible side effects?

A You're actually very close to sending PostScript code correctly through the QuickDraw GX printing system without the side effects. As you already know, after a shape with 'post' tags has been sent to a PostScript printer, QuickDraw GX performs a PostScript restore. There's no way to prevent this from happening. However, only shape objects cause this behavior; QuickDraw GX will not perform a PostScript restore for any other object besides a shape.

The fastest and best method for sending PostScript code is to attach the code with tags (using synonyms) to only one empty shape. You can attach as many tags as are required. We recommend that the tags contain 12K of PostScript data each, for optimal performance. If you're sending PostScript code down to replace the clip or ink or some other object besides a shape, just attach a 'post' tag to the object your PostScript code describes; in this case a restore will not occur.

Q How should I download fonts to a PostScript printer under QuickDraw GX? I'm sending a direct stream of custom PostScript code, but I don't expect the driver to be able to deduce which fonts need to be included. I've read about the PostScript control tag that can be attached to a shape, and I know the structure for the tag contains font information, but the documentation about this tag is sketchy. Can you provide more details?

Related to this question, what's the best way to cause fonts to be downloaded under the current Printing Manager? We're using the "draw a single character off the page in the proper font" trick. I understand this practice is frowned on. Is there an approved way to do this short of intermixing QuickDraw and PostScript code in PicComments?

A Our thinking has changed regarding the use of the PostScript control tag for downloading a font. If you want to download a font within your PostScript stream, you should call GXFlattenFont and pass the font within your 'post' tag. The GX PostScript engine will unflatten the font and download it when it finds it attached to your 'post' tag.

The method you're using (drawing a character off the page) is completely supported under QuickDraw GX. It was the recommended method for a long time. However, the current recommendation is to use DrawText and pass in text that contains all the glyphs you want to use. The reason this approach is better for QuickDraw GX is that only the required information is downloaded, thereby saving memory on the printer.

Q Do I need to override the GXFreeBuffer message in my QuickDraw GX printer driver if I perform a total override of the GXDumpBuffer message? If I do need to override GXFreeBuffer, what do I do with the buffer? Should I dispose of it with DisposePtr?

A The documentation is a little confusing about the purpose of the GXFreeBuffer message. GXFreeBuffer is sent to ensure that the indicated buffer has been processed and is now available for more data; it doesn't actually dispose of a buffer. The only time you need to override GXFreeBuffer is if you're doing custom I/O (the customIO flag is set in your 'iobm' resource). The default implementation of GXFreeBuffer will work correctly for QuickDraw GX's default buffering mechanism.

GXFreeBuffer allows you to start asynchronous I/O in GXDumpBuffer; then other buffering routines can be sure that operations on a buffer are completed before they reuse the buffer (or dispose of it). If you're overriding GXFreeBuffer, you should just hang out in your override until I/O has completed for the buffer passed, and then return. If you're doing synchronous I/O, just return immediately, since all I/O must have completed.

Q When I control the start of a QuickTime movie from within my application, the movie controller doesn't get updated properly. I'm calling StartMovie to begin the movie as soon as it becomes visible, and I'm updating the movie controller like this:

 theResult := MCDoAction(tmpMovie.fController, mcActionPlay,
     @curRate);

However, this doesn't seem to work. What am I doing wrong?

A The MCDoAction call with mcActionPlay doesn't take a pointer to the data in the last parameter; it takes the data itself. But since the prototype specifies type (void *), to make the compiler happy it must be cast to a pointer. Many people have fallen into this trap.

The recommended method to start a movie when you're using the standard movie controller component is as follows:

// Play normal speed forward, taking into account the possibility
// of a movie with a nonstandard PreferredRate.
Fixed rate = GetMoviePreferredRate(MyMovie);
MCDoAction(MyMovieController, mcActionPlay, (void *)rate); 

If you do need to use StartMovie, the correct way to cause the movie controller to update is to call MCMovieChanged.

Q We're using the Communications Toolbox in our application and have noticed some strange behavior. Specifically, when a tool is being used, the tool's resource fork is placed not at the top of the resource chain, but behind the System and application resource forks. As a result, we're having trouble with tools that use STR# resources that conflict with those in our application. This results in bad configuration strings or configuration dialogs with the wrong text. I can easily work around this by changing the resource IDs in my application, but this doesn't solve the problem in the long run. Any advice?

A What you're seeing is a part of the "pathology" of the Communications Toolbox and its tools. Both do a less than perfect job of looking in the correct resource map for string resources. The result is what you're currently seeing: application strings end up being placed where tool strings are expected.

There are a couple of workarounds. The first you've cited, which is to make sure that none of your application's resource ID numbers conflict with the CTB tool's ID numbers. However, as you also noted, this can be a problem when you're using several CTB tools, and may not work if the user happens to select a tool that has a conflicting ID.

The better way to work around the problem is to save a reference to the current resource file and then set the resource file to the System file. After completing a call to CMChoose or CMGetConfig, you can reset the resource file to the one you started with. Here's how to do this:

short   oldResFile;
Point   dlogBoxPt;
Ptr     myConfigString;

/* First save the current resource file. */
oldResFile = CurResFile();
/* Now set the resource file to the System file. */
UseResFile(0);
/* Next call CMChoose to configure your connection tool. */
myErr = CMChoose(&myConnectionHdl, dlogBoxPt, nil);
/* Now call CMGetConfig to get the configuration string from the
    connection tool. */
myConfigString = CMGetConfig(myConnectionHdl);
/* And finally, restore the old resource file. */
UseResFile(oldResFile);

Q What is the Human Interface suggestion for removing a digital signature from a signed document? I see how to add and how to verify, but I can't find any suggestions for removing signatures.

A Here's the relevant paragraph from the AOCE Human Interface Guidelines document, which can be found on AppleLink (search the AOCE Talk folder):

Signatures may also be deleted by users. To accomplish this, the user should select the signature by clicking on its icon and choosing Clear from the application's Edit menu. Selecting the signature icon and pressing the delete key is a desirable alternative. Note that signatures must not be cut, copied, or pasted.

To actually remove a signature, just remove the 'dsig' resource from the file. Note that signed files may have the Finder "locked" bit set. If you remove the signature, you should also clear this bit.

Q I launch my application by dragging files onto its icon. It then opens the files, performs some quick operation, and quits. I can put '****' and 'fold' resources in FREFs to let users drag any file or folder onto the application icon. But when a user drags an AOCE catalog (or anything inside the catalog) onto the icon, the Finder won't let the user drop it onto my application. What do I need to do to my application to let users drop-launch it with AOCE catalogs (or their contents)? I know it's possible: the "Find in Catalog" application will drop-launch if a user dragged to it from a catalog.

A If you look, you'll see that "Find in Catalog" is a Catalogs Extension template. It's not an application program; it actually executes as part of the Finder. Unfortunately, you can't do what you want to with an application. You might want to look at the Catalog Service Access Modules chapter in Inside Macintosh: AOCE Service Access Modules for more information on the Catalogs Extension.

Q When users launch my utility application by double-clicking, I present a Standard File dialog that lets them choose a file to operate on. I'd like them to be able to browse AOCE catalogs as well as HFS files, but catalogs don't show up in the Standard File dialog. I could use another dialog for browsing AOCE catalogs, but why use two different interfaces for the same action (from the user's point of view, that is; the user just wants to specify an object, wherever it may be)? Is there a way to get catalogs to show up in the Standard File dialog? Is there any way to browse the file system and the AOCE catalog system in the same dialog? If the answer is no, is there an analog to Standard File for AOCE catalogs?

A You can't browse HFS files and AOCE catalogs in the same dialog, since they're two different file systems. To let the user browse the AOCE catalog system, you need to use the AOCE Standard Catalog Package Reference routines, which are documented in Inside Macintosh: AOCE Application Interfaces . There is a routine that's analogous to StandardGetFile. The AOCE Software Developer's Kit (available through APDA) includes sample code that shows how to browse AOCE catalogs.

Q I'm writing an application that will watch a user-specified folder and operate on files or folders that are dropped into it. I need to perform operations on every item in the folder and its subfolders. What will happen if I begin to walk through a new folder with PBGetCatInfo while the Finder is still copying files into the subfolder structure? Can I guarantee that I'll detect all the files?

A There's no way to find out directly when the Finder is done copying items into the folder, but there is a strategy we can recommend. First, though, you should know that the recommended way to determine whether items have been added to a folder is to watch its modification date. So how can you know when all the files have arrived? The recommended strategy is to poll the parent folder's modification date every few seconds after you first detect a change, and keep polling until you have a reasonably long interval during which there's no change in the date (30 seconds is probably about right). This means, of course, that there's a delay before you act on files dropped into the folder, but as the Print Monitor shows us, this delay is probably reasonable to the user.

One more possible gotcha you should know about: to tell whether it's safe to work with a particular file, it's not enough just to make sure the file isn't open; you need to check its length. If a file is closed (that is, not busy) but has no length in either its resource or data fork, you caught the Finder at an uncomfortable time, after it created the file but before it opened it. So to know if you can operate on a file the Finder might be copying, you must determine two things: it's not already open, and it has length in its resource or data fork.

Q Our application uses the Icon Utilities interface, and we want to verify that these features are present before we use them. We've been unable to do this successfully. The Macintosh Technical Note "Drawing Icons the System 7 Way" (QuickDraw 18) doesn't say how to do this, but Inside Macintosh: More Macintosh Toolbox recommends using Gestalt with the gestaltIconUtilities selector. When we try this, Gestalt returns an error of -5551 (undefined selector). What are we doing wrong?

A There isn't a Gestalt selector for the Icon Utilities; Inside Macintosh and the header files are wrong. Even if we were to correct that situation tomorrow (or in the next system software release), it wouldn't help, since the Icon Utilities are available on systems where the Gestalt selector isn't. The solution is to use the TrapAvailable function to see if the _IconDispatch A- trap is available. You can find the source code for TrapAvailable in Inside Macintosh Volume VI on page 3-8, or in Inside Macintosh: Overview on page 180.

Q I have a System 7 application that the user can drag files, disks, or folders to. How can I determine from the Apple event information which type of item (file, disk, or folder) has been dragged to the application icon?

A When the user drags a file, disk, or folder to an application icon, the Finder uses the Process Manager to open the application and then sends it an Open Document ('odoc') event containing a list of alias records for each object dropped. When your application receives the event, it needs to open each of the objects specified in the event by getting each alias record from the list and coercing the data for that record to an FSSpec. Once you have the FSSpec, you can check its parID to determine whether the directory ID is fsRtParID, indicating that you're looking at a volume. If the parID is anything other than fsRtParID, use PBGetCatInfo to determine if you have a file or a folder. Here's the code:

enum {kItsAVolume = 1, kItsAFolder, kItsAFile};
pascal OSErr GetSpecType(FSSpec *myFSS)
{
    CInfoPBRec  pb;
    OSErr           myErr;
    short           objType = 0;
    
    if ((myFSS->parID) == fsRtParID)
        objType = kItsAVolume;
    else {
        pb.hFileInfo.ioNamePtr = (StringPtr) *(myFSS).name;
        pb.hFileInfo.ioVRefNum = *(myFSS).vRefNum;
        pb.hFileInfo.ioDirID = *(myFSS).parID;
        pb.hFileInfo.ioFDirIndex = 0;
        myErr = PBGetCatInfoSync(&pb);
        if (myErr == noErr) {
            /* Check to see if bit 0x10 of ioFlAttrib is set; if it
                is, we've got a directory */
            if ((pb.hFileInfo.ioFlAttrib & 0x10) != 0)
                objType = kItsAFolder;
            else
                objType = kItsAFile;
        }
    }
    return (objType);
}

Q I'm trying to implement "the perfect component." The goals for this component are fast dispatching, delegatable, able to rely on delegates, ready for everything, and surprised by nothing. I've been using develop Issues 12 and 14 and Inside Macintosh: More Macintosh Toolbox to guide me, but I still have a question that wasn't addressed in those references.

I'm using the Fast Dispatch method to dispatch my component's calls. I've figured out how to repair the stack after getting an unsupported routine selector code, but I can't figure out how to delegate a call. I think I'm recovering the stack correctly, but all the documentation I've read doesn't even hint at this sort of functionality. I was thinking that I could use DelegateComponentCall after creating a ComponentParameters record, or I could calculate the size of the parameters and attempt to set up the stack for a ComponentCallNow call. However, neither of these is a good solution -- they both take too many instructions to implement and obviate the advantages of fast dispatching. Is there such a thing as a DelegateFastComponentCall that I haven't heard of?

A Try the following to delegate a component call:

move.l  d0, -(sp)       ; push d0 onto stack
PUSHDELEGATEGUY         ; macro to push component instance 
move.q  #-2,d0
dc.w        $a82a

What apparently happened is that the engineers realized how difficult it was to call DelegateComponentCall when the stack was screwed up. So they created a "special" delegate call. As you can see, the selector is -2. This is supposed to be documented somewhere in the Component Manager documentation, but was inadvertently left out.

Q Why aren't my components getting register calls? I've set the appropriate flag. I'm registering the component from my application.

A Your component won't get called to register at all since it's being registered by an application. If you removed your component and placed it in the Extensions folder so that it was registered at system startup, it would receive a register call. The reason for this is that registration of components happens only when the Component Manager is first loaded at system startup. After system startup, components can be registered by applications, but the register routine will not be called.

Q I heard that the new Apple digital camera will introduce a graphics format called QuickTake. Is this truly a new format or are these just QuickTime compressed PICTs? If it's a new format, where can I find documentation on it?

A QuickTake stores its pictures as compressed PICT files. There's a new CODEC that's necessary to decompress the images, but no new file type. The QuickTake 100 Digital Camera Developer Note contains extensive information about talking to the camera from both Macintosh and Windows machines. It also documents the picture formats. The QuickTake Camera Software Development Kit is available from APDA.

The QuickTake application that comes with the camera can save the pictures in a variety of formats, including PICT (with or without various compressions) and TIFF. There's also a control panel that allows the user to mount the camera as a read-only serial RAM disk (similar to MountImage), so your application can directly download the information from the camera's memory.

Q I'm writing my first action atom for the Installer. I tried writing a skeletal example, as follows:

resource 'inaa' (30000) {
    format2 {
        continueBusyCursors, actAfter, dontActOnRemove,
            actOnInstall,
        'infn', 149,
        0,
        1000,
        "Delete Folder"
}};
 
#include "ActionAtomHeader.h"
 
ActionAtomResult ActionAtomFormat2(ActionAtom2PBPtr aa)
{
    Debugger();
    return (kActionAtomResultContinue);
}

But the action never gets called! I don't have to explicitly refer to the 'inaa' anywhere, do I? I checked that the resources were copied into the file correctly and had the right IDs. What am I doing wrong?

A Your action atom is fine. The only mistake you've made is not tying your 'inaa' to a package ('inpk'). You have to add to your 'inaa' a reference to an active 'inpk'. Once you do that, it works great. (We had trouble with this one until we found a cool diagram on page 8 of the Installer documentation that shows how the script resources interrelate; that diagram is your friend, and seems to encapsulate quite a bit of critical information.)

Q We're planning a zone name change for the zone that contains some of our PowerShare servers. Will this require any action on the part of the administrators of the various servers beyond informing users of the change?

A It depends on whether you're changing the zone names of some or all of the servers. If you're changing the names of only some servers, it's entirely possible that you don't have to notify anybody, depending on how you've replicated your folders. For a while the new servers won't be contacted by any clients since all clients will try to address them at their old location, but eventually all servers will again start receiving requests from clients.

If you're changing the zone names of all the servers, the client software won't recognize that the zone names have changed, so you'll have to throw away your key chain and add it again after the zone names have changed. The PowerShare servers will eventually recover and rediscover all the other servers. We recommend that you bring up the Master Pathfinder first after changing its zone name and then bring up all the other servers. Once all the servers are up, it should take a few hours at most for everything to settle down again and for the system to be purring.

Q The function SMPEnumerateBlocks takes a buffer that returns information about the blocks in a letter. The documentation (Inside Macintosh: AOCE Application Interfaces, page 3-87) says that the buffer contains "a count byte indicating the number of blocks in the letter, followed by a block information structure for each block." I can't find anything that tells me what a "block information structure" is.

It looks to me as if it actually returns the count of blocks in a short, not a byte. Is this the total number of blocks, or the number of blocks returned by the call? If I have to call the function again to get information that didn't fit in the buffer, do I get another count followed by more block information structures, or do I just get an array with more block information structures without the count (short)?

The block information structure seems to be 16 bytes long, starting with an OCECreatorType structure. Is this always correct, and what is the other information?

A This is somewhat confusing. The "block information structure" referred to here is the MailBlockInfo structure defined in the OCEMail.h header file:

 struct MailBlockInfo {
    OCECreatorType  blockType;
    unsigned long   offset;
    unsigned long   blockLength;
};

And yes, the count byte returned in the buffer you provide is actually a short (the documentation is wrong). This value is placed right in front of the first MailBlockInfo structure each time you make the call. The count indicates the number of blocks that were put in your buffer for this particular call (not the total), which of course depends on the size of the buffer you pass; it fits in as many as it can. Check the "more" parameter to see if your buffer was too small to hold all the blocks, and check the nextIndex parameter for the sequence number of the next item to be returned.

Q I found what I think is a problem with the TEGetOffset routine: when it returns, a 28-byte handle has been locked for single-styled text. I believe it's a style handle that gets locked. This seems to be an intermittent bug, occurring only about half the time. Is there a workaround? Is it safe to just unlock the style handle after calling TEGetOffset?

A It's a bug all right, and it is the style handle that's getting locked. Here's a workaround:

static short MyTEGetOffset(Point pt, TEHandle th)
{
    TEStyleHandle   sh;
    short               theResult;
    char                saveState;

    if (th == 0L)
        return;
    sh = GetStyleHandle(th);
    saveState = HGetState(sh);
    theResult = TEGetOffset(pt,th);
    HSetState(sh, saveState);
    return theResult;
}

Q I have a question about the Japanese art of bonsai (colloquially known as stunting trees): What happens if you bonsai a fruit tree? Does the fruit come out dwarfed as well? Or does the tiny tree produce full-size fruit?

A This was a difficult one to find an answer to. It seems to depend on many factors, not the least of which is the kind of fruit tree you're talking about. One person we talked to said he once saw a bonsai lemon tree nine inches tall, with a single, full-size lemon hanging from a branch. (Actually, the lemon didn't hang; it would have broken the poor tree. Instead it rested on a small platform built especially for that purpose.) But there were also reports of a stunted crabapple tree that produced apples the size of peas. Go figure.

These answers are supplied by the technical gurus in Apple's Developer Support Center. Special thanks to Pete ("Luke") Alexander, Joel Cannon, Mark ("The Red") Harlan, Dave Hersey, Dave Johnson, Don Johnson, Scott Kuechle, Jim Luther, Kevin Mellander, Jim Mensch, Martin Minow, and John Wang for the material in this Q & A column. If you need more answers, take a look at the Macintosh Q & A Technical Notes on this issue's CD. *