All DatabasesInside Mac - Basic Toolbox
GetResource
GetResource Read a resource into memory; get its handle
#include <Resources.h> Resource Manager
Handle GetResource(rType, rID );
ResType rType ; resource type (e.g., 'FONT', 'MENU', etc.)
short rID ; ID of desired resource
returns handle leading to the resource data
GetResource allocates storage for and reads the specified resource into
memory (if necessary). If the resource is found in any open resource file, this
function will return a handle leading to the resource data.
rType is a 4-byte resource type, such as 'MENU', 'DLOG', etc. It specifies
which type of resource you want to access. It can be any 32-bit long
integer, but is generally four displayable ASCII characters.
rID is the resource identifier, as defined in the resource file. For
application programs, the convention is to use positive values higher
than 127.
Returns: a Handle which leads to the resource data. A return value of NIL
indicates an error - either the resource can not be found or it will
not fit into memory See ResError.
Notes: A resource can contain any information imaginable, but is most often
quasi-permanent data which is seldom changed. Conventions should be
followed when creating your own resource types and IDs. See Resource
Types for related information and a list of defined resource types.
You may not need this function since the Toolbox contains a set of
ResType-specific resource calls which simplify access to commonly-used
resources:
GetNewControl GetResource('CNTL', ... )
GetCursor GetResource('CURS', ... )
GetNewDialog GetResource('DLOG', ... )
GetIcon GetResource('ICON', ... )
IUGetIntl GetResource('INTL', ... )
GetMenuBar GetResource('MBAR', ... )
GetMenu GetResource('MENU', ... )
GetPattern GetResource('PAT ', ... )
GetIndPattern GetResource('PAT#', ... )
GetPicture GetResource('PICT', ... )
GetString GetResource('STR ', ... )
GetIndString GetResource('STR#', ... )
GetNewWindow GetResource('WIND', ... )
Whenever available, you should use the type specific calls. Routines such
as GetNewWindow, GetNewDialog, and GetNewControl load the
resource into the heap and then copy the data from the resource into an
appropriate structure (a WindowRecord, DialogRecord, and ControlRecord,
respectively). A Handle or Ptr to this structure is returned, not a handle to
the resource in your heap. Likewise, you cannot pass the ControlHandle
that you get from a call to GetNewControl to a Resource Manager
routine such as DetachResource.
When read via GetResource, the correct way to dispose of the resource is
to use ReleaseResource (exception: use DisposHandle to discard
resource data after using DetachResource).
Finding Resources
In searching for a resource, GetResource looks through resource files
starting with the current one and working backward through all the
resource files that were opened before it. By default, the system resource
file is searched last (since it was opened first).
Your application resource gets opened automatically when the application
starts up, so by default, it is searched first. If you subsequently call
OpenResFile, that file becomes current and it is searched first. You can
call UseResFile to select any open resource file as the current file
(causing that file to be searched first).
The 128K ROMs provide a set of "one-deep" resource functions (e.g.,
Get1Resource) which search only one resource file.
ROM-based Resources
The 128K ROMs (and later versions) contain a set of ROM-resident system
resources. All the manager-specific resource calls include these resources
in the search by "inserting" them in front of the system resources (e.g.,
GetCursor(watchCursor) returns a handle leading to the cursor
definition in ROM). However, GetResource and other
Resource Manager calls will not find these ROM resources unless you
set low-memory global flags before the call:
RomMapInsert 0xB9E 0 = ignore ROM resources
0xFF=include ROM resources in search
TmpResLoad 0xB9F 0 = work as if SetResLoad(TRUE)
0xFF=temporarily disable "load
These are unusual "one-shot" flags as they are both cleared to 0 after each
Resource Manager call. If used, they should be set directly before each
Resource Manager call that searches resources (GetResource,
Get1Resource, etc.). Note that since the current resource file is
searched first, you can override any system or ROM-based resource simply
by including a resource with the same type and ID in your application
resource.
The following example reads an application-specific resource, locks it into
memory, de references the handle, accesses some data, unlocks it and releases
its memory.
Example
# include <Resources.h>
# define MY_RESID 128
Handle rHandle;
char *cp, firstByte;
rHandle = GetResource( 'danR', MY_RESID );
if ( rHandle == nil ) { /*... error, abort gracefully ... */ }
HLock( rHandle ); /* always lock de referenced handle */
cp = * rHandle; /* cp now points to the data */
firstByte = *cp; /* use (*cp) or (** rHandle) to refer to first byte of data */
/*... now OK to access data from the 'danR' resource data ... */
HUnlock( rHandle ); [TOKEN:12074] let it float again */
ReleaseResource( rHandle ); /* free up memory when ALL done */
Referenced by (189):