Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support

Apple IIgs
#83:    Resource Manager Stuff

Revised by:     Dave "Eh?" Lyons                                 January 1991
Written by:     Dave Lyons                                           May 1990

This Technical Note answers your miscellaneous Resource Manager questions.
Changes since September 1990:  Added notes about when you need to set the
current resource application and about re-opening your resource fork.
_____________________________________________________________________________

What SetCurResourceFile Does

SetCurResourceFile is documented in Chapter 45 of the Apple IIgs Toolbox
Reference, Volume 3 (see especially "Resource File Search Sequence" near the
beginning of the chapter).

This explanation might make you think SetCurResourceFile rearranges the search
path, but it does not; instead, it just makes searches start at a different
place in the path.  SetCurResourceFile is useful for controlling what resource
files are searched, not for changing the search order.

How the Toolbox Uses Resources as Templates

The toolbox uses several types of resources as templates for creating other
objects.  Examples include rControlList, rControlTemplate, and rWindParam1.
The toolbox automatically releases these resources from memory as soon as it is
through with them, so there is no need to create your template resources with
special purge levels in an effort to free more memory.  It is not a problem.

Using Resources From Window Update Routines

In System Software 5.0.4 and earlier there is no special code to set the
current resource application when the system calls a application window update
routine (See Apple IIgs Technical Note #71 for notes on NDAs and the current
resource application).

To avoid a situation where a window update routine cannot get needed resources,
obey the following rules:

1.   Application window update routines must either (a) assume that
     the resource application has the same value it had when the
     window was created, or (b) save, set, and restore the current
     resource application, using GetCurResourceApp and
     SetCurResourceApp.

2.   NDAs that start the Resource Manager must not call application
     window update routines, and they must not cause application
     window update routines to be called (for example, if an NDA
     calls TaskMaster to handle a modal dialog or movable modal
     dialog, the tmUpdate bit in wmTaskMask must be off).

CurResourceApp in InfoDefProcs and Custom Windows

The current resource application has no guaranteed value when an information
bar definition procedure or custom window definition procedure gets control.
These must always save, set, and restore the current resource application using
GetCurResourceApp and SetCurResourceApp.

StartUpTools Opens Resource Forks Read-Only

When StartUpTools opens your application's resource fork, it opens it with
read-only access.  If your application needs to make changes to the resources
on disk, you need to close the fork and reopen it with read and write access.
To close it, use GetCurResourceFile and CloseResourceFile; to reopen it, use
LGetPathname2 and OpenResourceFile.

Note:  You must update the resFileID field in the StartStop record if you close
       and reopen your resource fork.  CloseResourceFile disposes the handles
       of any resources in memory from the file you're closing, so you must
       call DetachResource on any resources you need to keep.  (If you pass an
       rToolSTartup resource to StartUpTools, the system detaches it for you
       automatically.)

Calling StartUpTools From a Shell Application (File Type $B5, EXE)

StartUpTools tries to open the current application's resource fork.  It
determines the pathname of the "current application" by examining prefix 9: and
making a GET_NAME GS/OS call, but do not assume it will always construct the
pathname this way.  If you call StartUpTools from a shell application and
expect it to open your EXE file's resource fork, you will be disappointed.

If GS/OS has launched your application, life is good-usually, though, a shell
has loaded your shell application directly, so GET_NAME returns the name of the
shell instead of the name of your application file.

To open your shell file's resource fork, call ResourceStartUp, get the pathname
by calling LGetPathname2 on your user ID, and pass the pathname to
OpenResourceFile.

What's NIL in a Resource Map?

The resource maps for open resource files are kept in memory, and the structure
is defined in chapter 45 of Apple IIgs Toolbox Reference, Volume 3.

The resHandle field of a resource reference record (ResRefRec) is defined as
"Handle of resource in memory.  A NIL value indicates that the resource has not
been loaded into memory."  In this case, NIL means that the middle two bytes of
the four-byte field are zero.  In other words, a NIL entry in the resource map
may have a non-zero value in the low-order byte.

LoadResource and SetResLoad(FALSE)

When you call LoadResource on a locked or fixed resource and SetResLoad is set
to FALSE, you may get Memory Manager error $0204 (lockErr), because the
Resource Manager tries to allocate a locked or fixed zero-length handle, which
the Memory Manager does not permit.

Adjusting the Search Depth

If you wish to add some resource files to the beginning of a resource search
path and adjust the depth so that the end point of the search is unchanged,
it's tempting to use SetResourceFileDepth(0) to get the current depth, add one,
and set this new depth with SetResourceFileDepth.

The problem is that the search depth is often -1 ($FFFF), meaning "search until
the end of the chain."  If you add your adjustment to -1, you do not usually
get the intended effect.  A solution is just to check for $FFFF and not adjust
the depth in that case.

Further Reference
_____________________________________________________________________________
  o  Apple IIgs Toolbox Reference, Volume 3
  o  Apple IIgs Technical Note #71, DA Tips and Techniques

