Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records / Writing Object Callback Functions

Writing an Object-Comparison Function

To handle object specifier records that specify tests, your application should provide an object-comparison function (unless it specifies kAEIDoWhose as described on page 6-56). Your object-comparison function should be able to compare one Apple event object to another Apple event object or to another descriptor record.

You specify your object-comparison function with the AESetObjectCallbacks function. Whenever it is resolving object specifier records and needs to compare the value of an Apple event object with another object or with data, the Apple Event Manager calls your object-comparison function.

Here's the declaration for a sample object-comparison function:

FUNCTION MyCompareObjects (comparisonOperator: DescType; 
                           object: AEDesc;
                           objectOrDescToCompare: AEDesc; 
                           VAR result: Boolean): OSErr;

The Apple Event Manager passes the following information to your object-comparison function: a comparison operator that specifies how the two objects should be compared, a token for the first Apple event object, and either a token that describes the Apple event object to compare or a descriptor record.

It is up to your application to interpret the comparison operators it receives. The meaning of comparison operators differs according to the Apple event objects being compared, and not all comparison operators apply to all object classes. After successfully comparing the Apple event objects, your object-comparison function should return the noErr result code and, in the result parameter, a Boolean value specifying TRUE if the result of the comparison is true and FALSE otherwise. If for any reason your comparison function is unable to compare the specified Apple event objects, it should return the result code errAEEventNotHandled; then the Apple Event Manager will try an alternative method of comparing the Apple event objects, such as calling the equivalent system object-comparison function, if one exists.

Your object-comparison function should be able to compare an Apple event object belonging to any object class with another Apple event object. Your function should also be able to compare two Apple event objects with different object classes, if appropriate. For example, an object-comparison function for a word-processing application might be asked to compare the First Name column of a specified row in a table with the first word on a specified page--that is, to compare an Apple event object of object class cColumn with an Apple event object of object class cWord. You must decide what kinds of comparisons make sense for your application.

The Apple Event Registry: Standard Suites defines standard comparison operators. Here is a list of the constants that correspond to these comparison operators:

CONST 
   kAEGreaterThan       = '>   ';
   kAEGreaterThanEquals = '>=  ';
   kAEEquals            = '=   ';
   kAELessThan          = '<   ';
   kAELessThanEquals    = '<=  ';
   kAEBeginsWith        = 'bgwt';
   kAEEndsWith          = 'ends'; 
   kAEContains          = 'cont'; 

The comparison operators always relate the first operand to the second. For example, the constant kAEGreaterThan means that the object-comparison function should determine whether or not the value of the first operand is greater than the value of the second operand. For more information, see page 6-103.

Listing 6-11 shows an application-defined function, MyCompareObjects, that compares two Apple event objects of any object class supported by the application.

Listing 6-11 Object-comparison function that compares two Apple event objects

FUNCTION MyCompareObjects (comparisonOperator: DescType; 
                           theObject: AEDesc;
                           objectOrDescToCompare: AEDesc; 
                           VAR result: Boolean): OSErr;
BEGIN
   result := FALSE;
   {compare two objects for equivalence}
   IF comparisonOperator = kAEEquals THEN
      MyCompareObjects := MyCompEquals(theObject, 
                                       objectOrDescToCompare, 
                                       result)
   ELSE
      {compare two objects for greater than}
      IF comparisonOperator = kAEGreaterThan THEN
         MyCompareObjects := MyCompGreaterThan(theObject, 
                                          objectOrDescToCompare,
                                          result)
   ELSE
      {compare two objects for less than}
      IF comparisonOperator = kAELessThan THEN
         MyCompareObjects := MyCompLessThan(theObject, 
                                          objectOrDescToCompare,
                                          result)
   ELSE
   {this app does not support any other comparison operators}
      MyCompareObjects := errAEEventNotHandled;
END;

The MyCompareObjects function calls a separate application-defined routine for each comparison operator. In each case, the application-defined routine that actually performs the comparison can compare an Apple event object with either another Apple event object or with a descriptor record's data. If for any reason the comparison cannot be performed, the MyCompareObjects function returns the result code errAEEventNotHandled.