Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Modifying Resources

ChangedResource

If you've changed a resource's data or changed an entry in a resource map, you can use the ChangedResource procedure to set a flag in the resource's resource map entry in memory to show that you've made changes.

PROCEDURE ChangedResource (theResource: Handle);

theResource

A handle to a resource.

DESCRIPTION

Given a handle to a resource, the ChangedResource procedure sets the resChanged attribute for that resource in the resource map in memory. If the resChanged attribute for a resource has been set and your application calls UpdateResFile or quits, the Resource Manager writes the resource data for that resource (and for all other resources whose resChanged attribute is set) and the entire resource map to the resource fork of the corresponding file on disk. If the resChanged attribute for a resource has been set and your application calls WriteResource, the Resource Manager writes only the resource data for that resource to disk.

If you change information in the resource map with a call to SetResInfo or SetResAttrs and then call ChangedResource and UpdateResFile, the Resource Manager still writes both the resource map and the resource data to disk. If you want any of your changes to the resource map or resource data to be temporary, you must restore the original information before the Resource Manager updates the resource fork on disk.

After writing a resource to disk, the Resource Manager clears the resource's resChanged attribute in the appropriate entry of the resource map in memory.

If the given handle isn't a handle to a resource, if the modified resource data can't be written to the resource fork, or if the resProtected attribute is set for the modified resource, ChangedResource does nothing. To find out whether any of these errors occurred, call ResError.

When your application calls ChangedResource, the Resource Manager attempts to reserve enough disk space to contain the changed resource. If the modified resource data can't be written to the resource fork (for example, if there's not enough room on disk), the resChanged attribute is not set to 1. If this is the case and you call UpdateResFile or WriteResource, the Resource Manager won't know that the resource data has been changed. Thus, the routine won't write the modified resource data to the resource fork and won't return an error. For this reason, always make sure that the ResError function returns the result code noErr after a call to ChangedResource.

IMPORTANT

If you need to make changes to a purgeable resource using routines that may cause the Memory Manager to purge the resource, you should make the resource temporarily not purgeable. To do so, use the Memory Manager procedures HGetState, HNoPurge, and HSetState to make sure the resource data remains in memory while you change it and until the resource data is written to disk. (You can't use the SetResAttrs procedure for this purpose, because the changes don't take effect immediately.) First call HGetState and HNoPurge, then change the resource as necessary. To make a change to a resource permanent, use ChangedResource and UpdateResFile or WriteResource; then call HSetState when you're finished. Or, instead of calling WriteResource to write the resource data immediately, you can call SetResPurge with the install parameter set to TRUE before making changes to purgeable resource data.

If your application doesn't make its resources purgeable, or if the changes you are making to a purgeable resource don't involve routines that may cause the resource to be purged, you don't need to take these precautions.

SPECIAL CONSIDERATIONS

The ChangedResource procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.

When called, ChangedResource reserves disk space for the changed resource. The procedure reserves space every time you call it, but the resource is not actually written until you call WriteResource or UpdateResFile. Thus, if you call ChangedResource several times before the resource is actually written, the procedure reserves much more space than is needed. If the resource is large, you may unexpectedly run out of disk space. When the resource is actually written, the file's end-of-file (EOF) is set correctly, and the next call to ChangedResource will work as expected.

If your application frequently changes the contents of resources (especially large resources), you should call WriteResource or UpdateResFile immediately after calling ChangedResource.

RESULT CODES

noErr	0	No error
resNotFound	-192	Resource not found
resAttrErr	-198	Attribute inconsistent with operation

SEE ALSO

To check for errors, call the ResError function as described on page 1-47.

For examples of the use of the ChangedResource procedure, see Listing 1-2 on page 1-16 and Listing 1-11 on page 1-32.

For descriptions of the UpdateResFile and WriteResource procedures, see page 1-87 and page 1-88, respectively. For descriptions of the SetResInfo, SetResAttrs, and SetResPurge procedures, see page 1-77, page 1-80, and page 1-89, respectively.

For information about using the Memory Manager procedures HGetState, HNoPurge, and HSetState, see Inside Macintosh: Memory.