May 93 - Testing Custom Resources for Errors
Testing Custom Resources for Errors
Steve Lavagnino & Laurie Seaton
The use of custom resources provides unique ways of handling information on the
Macintosh. It also poses some interesting problems. One such problem is how to
automate testing of custom resources for spelling errors, validity, and adherence to
user interface guidelines.
Our product, SoftPolish, was originally developed to automate the testing of standard
user interface resources. We included hundreds of tests on almost all the standard
resources. However, we knew the importance of anticipating demands from our user
community; especially from our target market, detail-oriented software
professionals. They would discover both new resources to test and new tests to make on
existing resources. To keep these users happy, we needed to enable SoftPolish to check
any custom resource. Simultaneously we wanted to provide an easy way to update our
product to test new resource types and to enhance existing tests. The following
describes how we achieved those goals.
Customizing SoftPolish™ to Handle Custom Resource
Types
SoftPolish Code Modules
SoftPolish can be customized through the use of external code modules, which
supplement or replace built-in resource tests. As SoftPolish scans a target file, target
resources are loaded into memory and examined. SoftPolish checks its own resource
fork to see if an external code module exists for the target resource type.
If a match occurs, a parameter block is constructed and passed to the external code
module. The parameter block includes the address in memory of the target resource,
the resource tests which were specified in the user's Scan dialog (See Figure 1.
SoftPolish Scan Dialog), and fields that allow an external code module to request
services from SoftPolish such as spell-checking or error-reporting.
What to Test
The general programming style for code modules is to have them first check the
parameter block to see which tests are currently requested. Not all tests may be
chosen, or selected tests may not be relevant to the resource the module is checking. In
Listing 1, the routine STR checks to see if the user has chosen UserInterface, Spelling,
or listStrings options. After determining that one of these options has been chosen, STR
extracts the string from the resource. (For a custom resource it may well be a more
complicated routine that extracts strings or other information from within the
resource.)
Communicating with SoftPolish
After the string is extracted in Listing 1, a series of assignments sets fields in the
parameter block. The first assignment sets the pleasedo field to msgDoString. The
pleasedo field is defined by using a set of predefined constants or parameters located in
the header files of the example source code. These predefined constants all start with
'msg' and each constant correlates to an action in SoftPolish. Before a callback is made,
the code module must set the pleasedo field to an 'msg' constant which specifies the
desired action. Pleasedo is an important field in the parameter block because it tells
SoftPolish what to do when a callback is made. Actions that SoftPolish can make via
callbacks are: testing to determine if a referenced resource is of the proper size,
testing to see if a string can be displayed within a specified rectangle, spell-checking
strings, replacing strings, writing the changed strings to the resource, displaying the
progress of checks to SoftPolish, and reporting error messages to the SoftPolish log
file. In Listing 1, the predefined constant msgDoString tells SoftPolish it is receiving a
string to test.
Depending on what the desired action is, additional data about the resource is usually
required before the callback can be made. For instance, msgDoString in Listing 1
requires several other assignments: a pointer to the text you want checked is put in the
field textPtr, the length of the text is put into textLen, and then options (such as
checks for capitalization and quote checking) are set with booleans in fields
arg.aDoString.bePicky and arg.aDoString.initialCaps. The last assignment to
arg.aDoString.spellit utilizes one of the user options already in the parameter block to
establish whether a callback string should be checked.
Now that all the parameter block fields are set, the code module makes a callback to the
SoftPolish application by calling the procedure DoCallBack. DoCallBack takes the
callbackaddress field in the parameter block as its argument. Even if a module is doing
its own testing of resources, it uses callbacks to report errors to the standard
SoftPolish log file.
Naming the Code Module
Once the routine for handling the resource is written, you need to give the code
resource a name and type. Each code module must have a resource of type 'SPCM'
(SoftPolish Code Module) or 'SPSM' (Softpolish Supplemental Module). The resource
name of the code module indicates what type of resource the code module accepts. For
example, an 'SPCM' resource named 'STR ' is, to SoftPolish, a code module that handles
'STR ' resources. If you add an 'SPCM' module for a type SoftPolish already tests, your
code module will replace the internal SoftPolish handling of that resource type.
Alternatively if you add an 'SPSM' code module, your code module supplements the
checking done by SoftPolish or an 'SPCM' module for that resource type.
Where to get more information
For more details on other callback routines, check the FrameWorks source code disk
or download our technical note on code modules from Applelink or America Online. The
note contains examples of code modules in C, Pascal, and FORTRAN. It also provides
header files with definitions of ModuleParms, 'msg' constants, and other records that
need to be included in your code module.
Listing 1
Ptr sptr;
Str255 str;
/* Determine what to test */
if (MP->Req->doUserInterface || MP->Req->doSpelling
|| MP->Req->listStrings) {
/* Extract the string out of the resource. */
sptr = *(MP->thdl);
memcpy(str,sptr,256);
/* Set up the callback for SoftPolish to check the string */
MP->pleasedo = msgDoString;
MP->textPtr = &str+1;
MP->textLen = str[0];
MP->resItem = -4;
MP->arg.aDoString.bePicky = true;
MP->arg.aDoString.initialCaps = false;
MP->arg.aDoString.spellit = MP->Req->doStrings;
DoCallback(MP->callbackaddress);
/* Make changes to the string if necessary */
if (MP->correctString[0]>0) {
SetHandleSize(MP->thdl,MP->correctString[0]+1);
sptr = *(MP->thdl);
memcpy(sptr,MP->correctString,MP->correctString[0]+1);
MP->pleasedo = msgWriteChangedResource;
DoCallback(MP->callbackaddress);
}
}
/* If requested, check the size of the resource */
if (MP->Req->doValidity && MP->Req->doSizeCheck) {
sptr = *(MP->thdl);
memcpy(str,sptr,256);
MP->pleasedo = msgCheckResourceSize;
MP->arg.aCheckResourceSize.correctSize = str[0]+1;
DoCallback(MP->callbackaddress);
}
}