Zz speaks
OK, so you're cruising your source like a madman trying to get all those little System
7.0 changes in before that target ship date (whatever it is this week), and you notice
that the items you've added to the Page Setup/Print dialogs don't have any Balloon
HelpTM--you know, those items like Reverse Pages, Print Hidden Text, or even Use
Fractional Font Widths. (Coming up with meaningful names for these items, in four
words or less, was a little tricky.) But now there's help, literally, in System 7.0.
Great! Then you remember that there wasn't a simple Printing Manager call to add
those items to the dialogs. You had to resort to the technique described in Technical
Note #95, How to Add Items to the Print Dialogs. As you remember, it used a set of
procedures that modified the Printing Manager's (that is, the selected print driver's)
dialog item list (DITL) resource.
Remembering the actual code in Tech Note #95, you consider that the Standard File
package shipped with 7.0 has a new call that allows you to append things to its dialog,
including Help Manager resources. Feeling relieved, you think, "Ah, there must be a
similar call in the new Pri . . ." But no, the new printing architecture has been
delayed. A quick scan shows that there isn't even a Printing Manager chapter inInside
Macintosh Volume VI! Help!!! It's not as bad as you might expect. If you consult Tech
Note #95, you'll see the rather husky AppendDITL procedure. This procedure is called
to append the items that you want to add to the dialog item list being used by the
particular dialog (Page Setup or Print).
The sample code from Tech Note #95 calls some Printing Manager routines that let
you get in after the DITL resource has been loaded, but before the dialog has been
displayed. You add your items to the resource in memorywithout calling either
ChangedResource or WriteResource. The driver then uses this DITL and displays your
items. Once the dialog is dismissed, the resource is purged, and the driver doesn't even
know you were there. Life is good.
As you've probably guessed by now, you're going to have to append to the Help Manager
dialog item help ('hdlg') resource in the same way that you appended to the DITL
resource. You simply scan the list to the end, and then append the appropriate items.
The 'hdlg' resource is purged in the same way as the DITL resource, so once again you
make no permanent changes.
On the next page is the definition of the Append2hdlg procedure. We start by getting
both 'hdlg' resources into memory. It's safe to assume the source 'hdlg' resource hasn't
been loaded yet, but we use the SetResLoad trick on the destination in case it has
already been loaded. (The SetResLoad trick is a method for determining whether a
resource has already been loaded. This trick is important, since in cases where the
resource has already been loaded by the system, you don't want to unload it or
permanently change any of its resource attributes.) The trick works like this: You
SetResLoad to false so that the Resource Manager doesn't load the resource data;
instead, it just creates an empty resource handle that can be passed to routines like
GetResInfo. You then call GetResource on the resource you're looking for. If the handle
returned is empty (that is, points to nil), you know the resource isn't already in
memory. If the handle returned is not empty, something else (like the system) has
already loaded it before you called GetResource. In this example, since we use
HGetState and HSetState to preserve the resource attributes, and we want the resource
to be left in memory when we're done, we don't really need to know if it was already
loaded. The SetResLoad code is included for anyone who is planning on modifying this
code to do more.
Next we initialize our locals. We want to point srcPtr to the place in the source
resource that we want to start copying from. To do this, we need to point past the
"missing item." The size of the item is stored in the resource just after the resource
header. We first use srcPtr to get the size (in bytes) of the missing item. Using that
size, we can calculate the starting location for the copy. We don't actually initialize
srcPtr yet, since resizing the destination handle could move memory. Next we
initialize dstPtr and dstLength. In the process, we resize dstHdl to make room for the
items we're going to append. Once SetHandleSize has been called, we also initialize
srcPtr. Now that srcPtr and dstPtr are set up, we use BlockMove to copy the new items
into the destination resource. After unlocking the resource handles, we update the
numItems field of the destination resource so that the Help Manager will know how
many items we added. Finally, we release the source resource. We don't want to release
the destination, since our changes would then be lost.
void Append2hdlg(srcResID, dstResID)
short srcResID, dstResID;
{
Handle srcHdl, dstHdl;
Ptr srcPtr, dstPtr;
short srcLength, dstLength;
short missingItmSz;
SignedByte dstHState;
srcHdl = GetResource('hdlg', srcResID);
if (srcHdl != nil) {
SetResLoad(false); /* System resource, make sure it's not */
dstHdl = GetResource('hdlg', dstResID); /* already loaded. */
SetResLoad(true);
if (*dstHdl == 0)
dstHdl = GetResource('hdlg', dstResID);
dstHState = HGetState(dstHdl);
if (dstHdl != nil) {
srcPtr = (Ptr)*srcHdl + sizeof(hdlgHeader);
missingItmSz = *((IntPtr)srcPtr);
srcLength = GetHandleSize(srcHdl) - (sizeof(hdlgHeader)
- missingItmSz);
dstLength = GetHandleSize(dstHdl);
SetHandleSize(dstHdl, dstLength + srcLength);
if (MemError() != noErr) {
DebugStr("\pMemError");
/* Use this error handler, go to jail. */
ExitToShell(); /* It's the law! */
}
dstPtr = (Ptr)*dstHdl + dstLength;
srcPtr = (Ptr)*srcHdl + sizeof(hdlgHeader) +
missingItmSz;
HLock(srcHdl);
HLock(dstHdl);
BlockMove(srcPtr, dstPtr, srcLength);
HUnlock(srcHdl);
HSetState(dstHdl, dstHState);
((hdlgHeaderPtr)*dstHdl)->hdlgNumItems +=
((hdlgHeaderPtr)*srcHdl)->hdlgNumItems;
}
}
ReleaseResource(srcHdl);
}
So that's about it. Append2hdlg is a lot smaller than AppendDITL because we don't
actually need to parse the contents of the 'hdlg' resource. Although it's another piece of
code to be added to your application, this should be quite painless, unlike other
Printing Manager exercises. Don't forget to read the Help Manager chapter of Inside
Macintosh Volume VI for guidelines on the contents of your Help Manager balloons. See
ya next time . . .
SCOTT "ZZ" ZIMMERMAN loves Disneyland--we think it's because he's really a
cartoon character at heart. When asked, he admitted to wanting to be Captain Hook
when he grew up. His favorite ride is Peter Pan because it's romantic, cool, dark, and
the main character is a kid who never grew up. Except for the romantic, cool, and dark
parts, it reminds him a lot of life at Apple. When he's at Apple he makes sure he drinks
at least 15 gallons of Mountain Dew a day--he says it powers the mechanism for his
retractable Barbie Doll hair. In closing, we'll leave you with his favorite question,
"How can I miss you if you won't leave?"*
For more information on the format and use of the "missing item" in an 'hdlg'
resource, and much more about Balloon Help, see the Help Manager chapter in Inside
Macintosh Volume VI. *