Macintosh Q & A

Q I'm having problems getting PICTs to display with the colors I want. I'm converting GIF files to PICTs by drawing the GIF into an offscreen GWorld. I'm using the Palette Manager to set up the colors, but there's no way to associate a palette with an offscreen PixMap. After I'm done drawing the GIF to a PixMap, I open the picture with the offscreen PixMap as the current port and use CopyBits to copy the PixMap onto itself, creating the picture. The problem is that if I use srcCopy, the colors are incorrect in the PICT when opened with TeachText (and other applications). But if I use ditherCopy the colors are saved correctly. I can use srcCopy if I do a CopyBits to/from a "color" window with the window's palette changed to my color palette. Is there a way to assign a palette to use for OpenPicture and still use CopyBits from an offscreen bitmap with srcCopy?

A You can associate a palette with a GWorld, but it won't solve your problem: since a GWorld never becomes "active," the associated device's colors are never changed to match the palette. The solution is to use a custom color table with the GWorld. And you can easily use Palette Manager routines to convert your palette to a color table.

Use the Palette2CTab routine to perform the conversion. Palette2CTab takes a PaletteHandle and a CTabHandle and copies all the colors from the palette into the color table, resizing the color table as necessary. If the palette handle is nil, no change takes place.

Now you have a color table that you can associate with your GWorld. You can pass it to NewGWorld when you create your GWorld initially; the fourth parameter is a handle to a color table. You need to explicitly set the depth in this call for best results. (If you pass nil for the depth, the color table parameter will be ignored and the depth of the GWorld will be set to match the deepest device that intersects the GWorld's boundary rectangle.) The other possibility is to associate the color table with an existing GWorld using UpdateGWorld.

Q I'm having a bit of a problem with DiffRgn. I start out with a "wide open" rectangular region (-32767, -32767, 32767, 32767) and then use DiffRgn to subtract a group of smaller rectangles from it. When I'm done, the bounding box of the region isn't what it should be. Any idea what's happening?

A What you need to do is create your clipping region so that it's not quite wide open (bottom and right coordinates of 32766 will work). If you do this, all your DiffRgn calculations will work fine.

While this isn't explicitly documented anywhere, it does seem to be a quirk in the way regions work. Due to the internal storage format of regions, the number 0x7FFF (32767) causes problems if it appears as a point inside a region. 0x7FFF is used as a flag in the internal region data structure to signify a "barrier." When this flag is used as a data point in a nonrectangular region, region parsing becomes completely screwed up.

QuickDraw tries to catch the creation of regions that will be poorly formed and turn them into properly formed (but slightly incorrect) regions, but it isn't 100% successful.

Q I'm erasing my windows with a color other than white, by setting the window's background color and calling EraseRect. But in cases where the Window Manager gets there first (window ordering changes or a window's size gets larger) I still get flicker, because the Window Manager erases with the wContent color from the window's color table (white by default) and not the port's background color. Is there a friendly, clean way to avoid that flicker? (I notice that in System 7.5, background colors are implemented with EraseRect, just as I'm doing it. Are you simply assuming the flash will be minimal?)

A One of the Window Manager's functions is to ensure that the content region of a window is opaque when it needs to be: that's why the Window Manager "pre-erases" the window when the content region grows, before your application gets a chance to. As you point out, if your application is then erasing large areas of the window to a different color, you'll get a noticeable flicker in those parts of the content region that needed to be opaque. This is an unfortunate side effect of a necessary maneuver by the Window Manager. Any system dialogs that set a background color and use EraseRect will suffer from the same flicker (although you won't spot it so often, since for the most part they're modal, nonresizable, and relatively small).

There are two solutions: If you create your windows from 'WIND' resources, you can create 'wctb' resources with the same ID and an appropriate wContent color and they'll automatically be used when the window is created. Alternatively, you can use the SetWinColor routine to apply a color table to a window after it has been created.

Q How can we write native PowerPC versions of our QuickDraw GX printer drivers? Native QuickDraw GX applications are easy, but I can't find any documentation for writing native drivers. One problem I can see is the jump table at the top of the 'pdvr' code resource, where each of the jump table entries is supposed to contain a 680x0 instruction to jump to the appropriate override procedure within the resource. How should we proceed?

A First of all, in our experiments with native QuickDraw GX drivers we've found little or no performance increase, so we don't really recommend writing native printer drivers. The bottlenecks in typical QuickDraw GX printer drivers are in the file and network I/O, which aren't affected much by the driver's code (see the Print Hints column in this issue of develop for more information). Unless you have some repetitive and time-consuming operation in which you can expect a huge win, your code will most likely just get bigger, and possibly even slower in some cases because of the context switches.

That said, I'll tell you how to make any or all of your overrides into "fat" overrides. Each of the fat overrides needs to consist of three parts:

• a "safe routine descriptor" (see below)

• the 680x0 code

• the PowerPC code

The safe routine descriptor allows a simple JMP instruction (such as those found in the 'pdvr' jump table) to run either 680x0 code or PowerPC code, depending on what type of Macintosh it's running on. The beginning of the safe routine descriptor contains 680x0 code that's executed the first time through and that determines whether the Mixed Mode Manager is present. If so, the routine descriptor from the PowerPC chunk of code is copied to the top of the resource. If not, a 680x0 branch instruction that jumps to the 680x0 code is inserted at the top of the routine descriptor. This code munging happens only the first time through -- after that, the code resource is set up to run the 680x0 code or the PowerPC code immediately upon jumping to it. This is described in more detail in Inside Macintosh: PowerPC System Software and in MixedMode.r.

Here's how a fat override would be called from QuickDraw GX: First, execution jumps to the desired entry in the printer driver's jump table. The 680x0 JMP instruction in the table is executed and jumps to the safe routine descriptor in the override. The safe routine descriptor then executes either the 680x0 code or the PowerPC code, depending on the machine.

The real trick is building the makefile. First the makefile has to compile each of the override functions into a 680x0 code resource using C and Link, and into a PowerPC code resource using PPCC, PPCLink, makePEF, makesys, and Rez. Next, it needs to use Rez to combine the results of the compiles into fat resources with safe descriptors. Finally, it needs to use Rez to combine the jump table with all of the fat resources. This last step is a doozy. You'll need to write an MPW tool that concatenates all the fat resources while keeping track of the offsets of each one. These offsets will need to be stuffed into the jump table at the top of the final 'pdvr' resource.

Q I'm trying to display from my QuickDraw GX printer driver a movable modal dialog box that contains a list. What would be the best way to do it?

A Since you're displaying the dialog from a printer driver, you can let QuickDraw GX do most of the work. Use GXAlertTheUser to put up a 'plrt' resource that specifies the printingStatus type. That makes a movable modal dialog. Then override GXInitializeStatusAlert to build your list information for the dialog, and GXHandleAlertEvent so that you can update your dialog, handle clicks, dispose of the dialog, and so forth. You'll probably also want to override GXHandleAlertFilter to help out with that.

Q I noticed that the "Larger Print Area" checkbox has been taken out of QuickDraw GX's LaserWriter Page Setup Options. I assume this means one of three things: (a) it's now on all the time, (b) it's now off all the time, or (c) it's lurking someplace else. Which is it?

A The option has been removed, as you noted, but the functionality is still available, in the guise of papertypes. To decide where on the page to print, QuickDraw GX printing uses the papertype that a page is formatted for. Some of these papertypes come standard (built into QuickDraw GX or into specific drivers), but users can also create their own papertypes using the papertype editor that accompanies QuickDraw GX.

For example, a user could create a papertype called "Company Letterhead" that's based on US Letter but has an imageable area that excludes the part of the page at the top where the address and logo might be, as well as the line or two of text at the bottom of the page. When dropped into the Extensions folder, these custom papertypes become available from QuickDraw GX applications, and users can format their documents with them. In the case of this letterhead example, the result would be that you wouldn't have to fiddle around with your text to avoid printing over the type and graphics on the paper.

The "Larger Print Area" feature isn't compatible with the concept of papertypes because in order for QuickDraw GX to honor the imageable area of a papertype, it can't change the dimensions that the papertype is set up for. Again, using the letterhead example, if we were to expand the imageable area it would probably result in text printing over the company logo or address information.

We realized that some customers would still expect this functionality to be around, so we've included some papertypes in the LaserWriter GX driver that mimic the old behavior. When you format for the LaserWriter GX driver (or for a desktop printer for that driver), you'll notice that two new papertypes become available in the QuickDraw GX page setup dialogs: "A4 Letter (7.8 x 11.4)" and "US Letter (8.5 x 11)." These are "larger print area" versions of their counterparts. In applications that aren't QuickDraw GX aware, these papertypes can be found in the Page Setup dialog's Paper Type menu.

Q I was wondering whether QuickDraw GX, like LaserWriter 8, uses PostScript printer description (PPD) files. How do PPD files and the new printing architecture integrate? What happens in QuickDraw printing compatibility mode?

A The short answer to this question is no, QuickDraw GX does not use PPD files. The longer answer is, well, longer.

The main use for PPD files was to extend the functionality of the LaserWriter 8 driver. As you know, the contents of many of LaserWriter 8's dialogs depend on the contents of the PPD file. The user can associate a PPD file with a printer via the Chooser from LaserWriter 8 onwards, by using the Setup button in the Chooser dialog.

As you're also aware, the mechanism for choosing printers has changed with QuickDraw GX. This means that PPD files aren't needed, except for one case: using QuickDraw GX Helper to print with LaserWriter 8 with QuickDraw GX installed. In this situation, printing will occur in the same way as before -- in other words, the print process will be the same as for plain old LaserWriter 8, including the use of PPD files. In QuickDraw printing compatibility mode (that is, printing with a pre-QuickDraw GX application on a system running QuickDraw GX), the emulation will use the QuickDraw GX driver, so PPD files won't be used unless the driver specifically supports them.

By the way, there's no reason a printer driver manufacturer can't incorporate PPD files into a QuickDraw GX printer driver, if it's deemed appropriate.

Q When my application creates a new media (of text type in this case) for a new track in a movie created with NewMovieFromScrap, the dataRef and dataRefType should be set to nil, according to the QuickTime documentation. The problem is that later I want to edit that media (adding a text sample to it, for example), but BeginMediaEdits returns -2007 (no data handler found). I assume I can get around that by first saving the movie to a file, but this seems slimy since the movie won't end up on disk in the end. Any suggestions for a better approach?

A You're correct -- BeginMediaEdits complains if the movie has been created with NewMovieFromScrap. Unfortunately, BeginMediaEdits doesn't think memory-based movies are on a media that will support editing. The workaround is, as you thought, to store the movie in a temporary file until you're finished editing it.

Fortunately, this is easy to do. When you call NewTrackMedia, pass an alias to a new file in the dataRef parameter instead of nil. Passing nil (the usual approach) indicates that the movie's default data reference should be used, but because your movie came from the scrap and not a file, it has no data reference -- hence the error you're getting. By the way, using the data handler in QuickTime 2.0, you can create a movie entirely in memory.

Q I need to alter the pixel information of a QuickTime movie frame after it has been decompressed but before it's displayed on the screen. Is there any way that a user-defined procedure can be called by QuickTime at this point? If not, how can I accomplish this?

A As long as you use QuickTime 1.6 or later, you can do this easily. The mechanism is described in the Macintosh Technical Note "QuickTime 1.6.1 Features" (QT 4) under the heading "SetTrackGWorld."

SetTrackGWorld lets you force a track to draw into a particular GWorld. This GWorld may be different from that of the entire movie. After the track has drawn, it calls a "transfer procedure" that you've written to copy the track to the actual movie GWorld. You can also install a transfer procedure and set the GWorld to nil. This results in your transfer procedure being called only as a notification that the track has drawn -- no transfer takes place.

You should do your image manipulation in your transfer procedure. Bear in mind, of course, that calling resource-intensive or time-consuming routines in your transfer procedure will have an adverse effect on the playback performance of your movie.

Q I'm looking for the documentation for five routines in the Communications Toolbox that aren't in my 1.0 documentation. The routines are "PBxxx-style" asynchronous routines: CMNewIOPB, CMDisposeIOPB, CMPBRead, CMPBWrite, and CMPBIOKill. Where are these calls documented?

A These calls are documented in the Communications Toolbox 1.1 Engineering Notes. The calls were added to allow "overlapping I/O," that is, issuing a _CMWrite call and then issuing another before the first completes. The Communications Toolbox version 1.0 specifically prohibits this behavior.

Q I have an application that needs to be able to detect invisible folders. The "invisible" bit for files is in the fdFlags in the FInfo structure, but that obviously won't work for directories. What's the recommended way to do this?

A PBGetCatInfo will get you the information you need. The ioDrUsrWds field of the DirInfo structure that you get by calling PBGetCatInfo is a DInfo structure:

struct DInfo {
   Rect                frRect;       /* folder rect */
   unsigned short      frFlags;      /* flags */
   Point               frLocation;   /* folder location */
   short               frView;       /* folder view */
};

The frFlags field has the same layout as the fdFlags field in an FInfo structure. Many of the bits don't apply to directories, but fOnDesk and fInvisible do. The fInvisible bit is set for almost all invisible folders. The only exceptions to this are certain special folders that the Finder can create, such as the "Temporary Items" folder, which you shouldn't have to worry about.

Q When a user of my application saves a file, I want to automatically save a few files, each of which has a different extension to the name the user chose. For instance, if the user saves the file as "MyFile" I want to create "MyFile.a," "MyFile.b," and "MyFile.c." If the user gives a filename that already exists, but the filename with the extension doesn't exist, is there a way to avoid the appearance of the Replace/Cancel dialog? Conversely, can I make the Replace/Cancel dialog appear for the filenames with the extensions? I assume CustomPutFile is the way to go here, but I'm not sure how to proceed.

A CustomPutFile is the answer, all right. One way to get rid of the Replace/Cancel dialog is to write a simple dialog hook function that includes the following code:

/* If it's the "Replace Existing?" dialog... */
if (refCon == sfReplaceDialogRefCon)
   /* ...and the dialog is just about to appear... */
   if (item == sfHookFirstCall)
      /* ...then "hit" the Replace button automatically. */
      return 1;

The problem you pose is a little different, however, so we recommend a different approach. In addition to avoiding the standard Replace/Cancel warning, your dialog hook function will also need to make sure each filename-plus-suffix combination is a valid filename (that is, not too long), put up Replace/Cancel dialogs in case any filename-plus-suffix combination already exists, and override other warnings, such as the "That name is already used by a folder" dialog.

First, define a data structure that can be passed to CustomPutFile so that your dialog hook function can access the list of suffixes you're working with and return the results (that is, the FSSpec and FInfo) of each filename-plus-suffix combination. Then, your dialog hook function should do the following when the user clicks the Save button:

• Make sure that each filename-plus-suffix combination is a valid filename.

• Put FSSpecs for each filename-plus-suffix combination into the data structure so that you can get at them later.

• Put up Replace/Cancel dialogs for any filename-plus-suffix combination that already exists.

• If the user cancels any of these, remap the Save item to nothing by returning sfHookNullEvent.

• If the user accepts all of these, remap the Save item to Cancel by returning sfItemCancelButton and, before returning, mark the sfReply as good, so that your application can tell that the user really clicked the Save button. By changing the Save item to the Cancel item, you bypass all the standard warnings, which means that your dialog hook function is responsible for warning the user if there's anything wrong with the filename. These warnings should maintain the spirit of the normal Standard File warnings as much as possible.

Inside Macintosh: Files, pages 3-26 through 3-40, provides additional information on this subject.

Q I need to obtain the location of my application from within my application. How can I do this?

A The Process Manager routine GetProcessInformation returns an FSSpec to the current process if you use the process serial number kCurrentProcess, as shown in the following code:

OSErr GetCurrentProcessSpec(FSSpec *spec)
{
   ProcessSerialNumber   currentPSN;
   ProcessInfoRec       info;

   /* Get current process FSSpec with GetProcessInformation. */
   currentPSN.highLongOfPSN = 0;
   currentPSN.lowLongOfPSN = kCurrentProcess;
   info.processInfoLength = sizeof(ProcessInfoRec);
   info.processName = NULL;  /* we don't need process name here */
   info.processAppSpec = spec;
   return (GetProcessInformation(&currentPSN, &info));
}

If GetCurrentProcessSpec returns with a noErr result, spec.vRefNum is the volume reference number of the volume your application file is on, spec.parID is the directory ID of your application file's parent directory, and spec.name is the name of your application file.

If your application is a 680x0 application and might run under System 6 (where the Process Manager and the Apple Event Manager aren't available), you can use GetAppParms to get the reference number of your application and then pass that number to PBGetFCBInfo to get the location of your application. PowerPC applications must use GetProcessInformation because GetAppParms isn't available to them.

The following code shows how to use GetAppParms and PBGetFCBInfo to get the location of your application. You must define OBSOLETE in your source code before you include SegLoad.h; otherwise GetAppParms (and the other obsolete Segment Loader routines CountAppFiles, GetAppFiles, and ClrAppFiles) will not be defined.

/* Obsolete System 6 way of getting the application location. */

#define OBSOLETE
#include <SegLoad.h>
#include <Files.h>

OSErr GetCurrentAppLocation(short *vRefNum, long *parID,
    Str63 apName)
{
   OSErr      result;
   FCBPBRec   fcbPB;
   Handle      apParam;
   
   /* Get application reference number from Segment Loader. */
   GetAppParms(apName, &fcbPB.ioRefNum, &apParam);
   
   /* Get application location from File Manager. */
   fcbPB.ioNamePtr = apName;  /* return application name here */
   fcbPB.ioVRefNum = 0;
   fcbPB.ioFCBIndx = 0;
   result = PBGetFCBInfoSync(&fcbPB);
   if (result == noErr) {
      *vRefNum = fcbPB.ioFCBVRefNum;
      *parID = fcbPB.ioFCBParID;
   }
   return (result);
}

Q I have a handle to a resource and I want to find the location of the file it came from. Can I do this?

A Yes, you can use HomeResFile to get the file reference number associated with the resource and then pass that number to PBGetFCBInfo to get the location of the resource file, as follows:

OSErr GetFileLocationFromResource (Handle theResource,
         short *vRefNum, long *parID, Str63 name)
{
   OSErr         result;
   FCBPBRec      fcbPB;
   
   /* Get resource file reference number from Resource Manager. */
   fcbPB.ioRefNum = HomeResFile(theResource);
   result = ResError();
   if (result == noErr) {
      if (fcbPB.ioRefNum != 1) {         /* Is resource in ROM? */
         if (fcbPB.ioRefNum == 0) {   /* Is it in the System file? */
            /* Get System file's real refNum. */
            fcbPB.ioRefNum = LMGetSysMap();
         }
         /* Get resource file location from File Manager. */
         fcbPB.ioNamePtr = name;      /* return filename here */
         fcbPB.ioVRefNum = 0;
         fcbPB.ioFCBIndx = 0;
         result = PBGetFCBInfoSync(&fcbPB);
         if (result == noErr) {
            *vRefNum = fcbPB.ioFCBVRefNum;
            *parID = fcbPB.ioFCBParID;
         }
      }
      else {
         /* Resource was in ROM, not a file. Return paramErr. */
         result = paramErr;
      }
   }
   return (result);
}

Q I need to write an extension that will launch an application at a specified time. I've looked at various ways to do this, but they all seem dangerous or difficult, mostly because I can't call either LaunchApplication or AESend (to send an 'oapp' event) at interrupt time. What's the best/safest/simplest way to do this?

A Write a BOA (background-only application, also called a faceless background application) that just sits in the background and periodically checks the time. When the correct time arrives, the BOA can launch the application and quit (or remain running if this is a periodic task). Make your BOA have a file type of 'appe' (application extension) and it will be installed in the Extensions folder and launched at startup.

Q I need to insert a two-dimensional array, such as "long double myArray[512][3]," into an Apple event. Is there any way to use AEPutArray? I know that I can probably loop over each item and add it to a list of typeFloat, but that's extremely cumbersome and slow. Also, I could send it as typeData, but that wouldn't let users view the data in a script editor. Any ideas? I'm looking for the most elegant and speedy solution. I'll also need the inverse: a way to extract that data from an incoming Apple event.

A There's no standard way of implementing two-dimensional arrays in Apple events. Apple event arrays are limited to one-dimensional arrays of integer, char, handle, or descriptor types. While it may be possible to represent your data in one of these formats, this is not going to be a very efficient solution.

There are several other possible solutions to the problem, but only you can decide which one will work best. Perhaps the most straightforward is to create an AEList, which in itself contains a set of AELists, to represent your data. While this will allow your data to be displayed by the Script Editor, it could be very inefficient for large arrays. It's also consistent with the way that the Table Suite specifies a table (which is basically what your two-dimensional array is): type cTable consists of a list of typeRow descriptors, which in turn consist of a list of typeCell descriptor records.

Another more efficient approach (which is also more trouble) is to use your own private data format and install a system coercion handler to coerce this data into a form that can be displayed in the Script Editor (typeChar, for example). When the data is returned from your GetData handler, the coercion handler will be called to translate the data, so it would be displayed as text in the results window.

Do you really need to provide a two-dimensional array in a form that can be read in the Script Editor? Often the user will just want to request certain elements of the array, rather than requesting the entire array. The best solution of all might be to avoid sending large arrays completely, at least in a format that can be displayed in the Script Editor. There's very little the user can do to view and manipulate large amounts of data from the Script Editor anyway. You could allow users to request pieces of data from the array, using a row and column approach to allow them to specify the data, but when they need to manipulate large amounts of data you might consider writing the requested data to a file and then returning an alias to the file.

Q I'm implementing a dialog in which seven items need to be present all the time while the presence of the other items depends on various situations. I use Hide/ShowDItem to do the trick. Is there any other way to do it? The dialog's DITL is really a mess!

A The approach of showing and hiding individual items is fine if you have only a couple of items in the dialog item list, but as you've found, it becomes a real mess when the dialog starts to become more complex. You can dynamically add items to and remove items from a dialog box by using the AppendDITL and ShortenDITL routines. When you call AppendDITL, you specify a dialog box and a new item list resource to append to the dialog's existing item list resource. You also specify where the Dialog Manager should display the new items, using one of these constants to designate where AppendDITL should display the appended items:

CONST   overlayDITL         = 0;      {overlay existing items}
        appendDITLRight     = 1;      {append at right}
        appendDITLBottom    = 2;      {append at bottom}

You should create one dialog with the seven items that remain constant, and a series of associated DITL resources that contain the items you need to add to each variant of the dialog. Then use AppendDITL to add these as required.

Q If I call the following stripped-down routine twice, my application crashes the second time. Why?

static void CrashMeBaby (void)
{
   Rect         aRect;
   DialogPtr    aDialog;

   SetRect(&aRect, 50, 50, 200, 200);
   aDialog = NewDialog(NIL, &aRect, "\p", true, altDBoxProc,
            (WindowPtr) -1L, false, 0, GetResource('DITL', 400));
   DisposeDialog(aDialog);
}

A The problem is that DisposeDialog disposes of the item list (which you're obtaining with GetResource) by calling DisposeHandle, not ReleaseResource. This leaves an invalid reference lingering in the resource map, which is bad news. The next time the resource is needed, it would normally be read in again from disk. However, in this case the handle is no longer valid, and you crash. The workaround for this is simply to call DetachResource on your item list handle after you retrieve it.

One way of finding this kind of bug is to use the DisposeResource extension, which can be found on this issue's CD. This traps instances of DisposeHandle being called to dispose of a resource. If you install DisposeResource and try it with your code, you'll see that this is what's happening in your case.

Q How do fleas jump so high? Surely the power required for these prodigious leaps (easily 100 times their length!) can't be supplied by muscle. How do they do it?

A Fleas have an organ (not a muscle) that's elastically deformable and can store energy like a rubber band. It's "charged up" over time, with a sort of ratcheting muscular action. So the flea "winds up" and then lets go all at once. An interesting side effect is that just after a flea jumps, it's unable to jump again; it needs time to recharge. (The time needed, however, is a mere tenth of a second.)

These answers are supplied by the technical gurus in Apple's Developer Support Center. Special thanks to Brian Bechtel, Joel Cannon, David Hayward, Dave Hersey, Peter Hoddie, Dave Johnson, Jon Lansdell, Jim Luther, Kevin Mellander, Jim Mensch, 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.