Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Interapplication Communication /: Chapter 6 - Resolving and Creating Object Specifier Records / Installing Entries in the Object Accessor Dispatch Tables

Installing Object Accessor Functions That Find Apple Event Objects
Listing 6-1 demonstrates how to add entries to your application's object accessor dispatch table for the object class cText and three of its element classes: the object classes cWord, cItem, and cChar. In this example, the container for each of these object classes is identified by a token that consists of a descriptor record of descriptor type typeMyText.
Listing 6-1 Installing object accessor functions that find elements of different classes for container tokens of the same type
myErr := AEInstallObjectAccessor(cText, typeMyText, 
                                 @MyFindTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cWord, typeMyText, 
                                 @MyFindWordObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cItem, typeMyText, 
                                 @MyFindItemObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cChar, typeMyText, 
                                 @MyFindCharObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);    
The first call to AEInstallObjectAccessor in Listing 6-1 adds an entry to the application's object accessor dispatch table. This entry indicates that the AEResolve function should call the MyFindTextObjectAccessor function when resolving any Apple event object with the cText object class and a container identified by a token of descriptor type typeMyText. The other calls to AEInstallObjectAccessor in Listing 6-1 add entries for Apple event objects of object classes cWord, cItem, and cChar in a container identified by a token of descriptor type typeMyText. For example, because all the entries created by the code in Listing 6-1 specify the descriptor type typeMyText for the token that identifies the container, the AEResolve function calls the MyFindWordObjectAccessor function to locate a requested word regardless of whether the container for the word is a run of text, another word, a paragraph, or an item.
The fourth parameter for the AEInstallObjectAccessor function specifies a reference constant passed to your handler by the Apple Event Manager each time AEResolve calls your object accessor function. Your application can use this reference constant for any purpose. If your application doesn't use the reference constant, you can use 0 as the value, as shown in Listing 6-1.
The last parameter for the AEInstallObjectAccessor function is a Boolean value that determines whether the entry is added to the system object accessor dispatch table (TRUE) or to your application's object accessor dispatch table (FALSE).
If you add an object accessor function to the system object accessor dispatch table, the function that you specify must reside in the system heap. If there was already an entry in the system object accessor dispatch table for the same object class and container descriptor type, that entry is replaced unless you chain it to your system handler. You can do this the same way you chain a previously installed system Apple event handler to your own system handler. See the description of AEInstallEventHandler on page 4-59 for details.

WARNING
Before an application calls a system object accessor function, system software has set up the A5 register for the calling application. For this reason, if you provide a system object accessor function, it should never use A5 global variables or anything that depends on a particular context; otherwise, the application that calls the system object accessor function may crash.
The code shown in Listing 6-1 installs a separate object accessor function for each object class, even though the code specifies the same descriptor type for tokens that identify the containers for Apple event objects of each class. Most word-processing applications can specify the same object accessor function as well as the same token descriptor type for Apple event objects of these four classes, in which case the code shown in Listing 6-1 can be altered as shown in Listing 6-2.
Listing 6-2 Installing one object accessor function that finds elements of different classes for container tokens of one type
myErr := AEInstallObjectAccessor(cText, typeMyText, 
                                 @MyFindTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cWord, typeMyText, 
                                 @MyFindTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cItem, typeMyText, 
                                 @MyFindTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cChar, typeMyText, 
                                 @MyFindTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
In some situations you may want to write different object accessor functions to locate Apple event objects of the same object class in containers identified by tokens of different descriptor types. For example, the code in Listing 6-3 installs two different object accessor functions: one that finds a word in a container identified by a token of type typeMyTextToken, and one that finds a word in a container identified by a token of typeMyGraphicTextToken.
Listing 6-3 Installing object accessor functions that find elements of the same class for container tokens of different types
myErr := AEInstallObjectAccessor(cWord, typeMyTextToken, 
                                 @MyFindTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cWord, typeMyGraphicTextToken, 
                                 @MyFindGrphcTextObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
Every application must provide one or more object accessor functions that can find Apple event objects in the default container, which is always identified by a token of descriptor type typeNull. Listing 6-4 demonstrates how to add entries to your application's object accessor dispatch table for the object classes cWindow and cDocument. The container for each of these classes is identified by a token of descriptor type typeNull, which specifies an application's default container.
Listing 6-4 Installing object accessor functions that locate elements of different classes in the default container
myErr := AEInstallObjectAccessor(cWindow, typeNull, 
                                 @MyFindWindowObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallObjectAccessor(cDocument, typeNull, 
                                 @MyFindDocumentObjectAccessor,
                                 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
For any entry in your object accessor dispatch table, you can specify a wildcard value for the object class, for the descriptor type of the token used to identify the container, or for both. You specify a wildcard by supplying the typeWildCard constant when installing an entry into the object accessor dispatch table. A wildcard value matches all possible values.
If an object accessor dispatch table contains one entry for a specific object class and a specific token descriptor type, and another entry that is identical except that it specifies a wildcard value for either the object class or the token descriptor type, the Apple Event Manager dispatches the more specific entry. For example, if an object accessor dispatch table includes one entry that specifies the object class as cWord and the token descriptor type as typeMyTextToken, and another entry that specifies the object class as cWord and the token descriptor type as typeWildCard, the Apple Event Manager dispatches the object accessor function associated with the entry that specifies typeMyTextToken.
If you specify typeWildCard as the first parameter and typeMyToken as the second parameter for the AEInstallObjectAccessor function and no other entry in the dispatch table matches more exactly, the Apple Event Manager calls the object accessor function that you specify in the third parameter when resolving Apple event objects of any object class in containers identified by tokens of the typeMyToken descriptor type.
If you specify cText as the first parameter and typeWildCard as the second parameter for the AEInstallObjectAccessor function and no other entry in the dispatch table matches more exactly, the Apple Event Manager calls the object accessor function that you specify in the third parameter when resolving Apple event objects of the object class cText in containers identified by tokens of any descriptor type.
If you specify typeWildCard for both the first and second parameters of the AEInstallObjectAccessor function and no other entry in the dispatch table matches more exactly, the Apple Event Manager calls the object accessor function that you specify in the third parameter when resolving Apple event objects of any object class in containers identified by tokens of any descriptor type.
Once the Apple Event Manager finds a matching entry, whether exact or involving type typeWildCard, that is the only object accessor function it calls for that object class and token descriptor type. If that function fails, the Apple Event Manager won't look for another matching entry in the same table.