Important: The information in this document is obsolete and should not be used for new development.
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 classcText
and three of its element classes: the object classescWord
,cItem
, andcChar
. In this example, the container for each of these object classes is identified by a token that consists of a descriptor record of descriptor typetypeMyText
.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 toAEInstallObjectAccessor
in Listing 6-1 adds an entry to the application's object accessor dispatch table. This entry indicates that theAEResolve
function should call theMyFindTextObjectAccessor
function when resolving any Apple event object with thecText
object class and a container identified by a token of descriptor typetypeMyText
. The other calls toAEInstallObjectAccessor
in Listing 6-1 add entries for Apple event objects of object classescWord
,cItem
, andcChar
in a container identified by a token of descriptor typetypeMyText
. For example, because all the entries created by the code in Listing 6-1 specify the descriptor typetypeMyText
for the token that identifies the container, theAEResolve
function calls theMyFindWordObjectAccessor
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 timeAEResolve
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.
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.
- 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.
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 typetypeMyTextToken
, and one that finds a word in a container identified by a token oftypeMyGraphicTextToken.
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 typetypeNull
. Listing 6-4 demonstrates how to add entries to your application's object accessor dispatch table for the object classescWindow
andcDocument
. The container for each of these classes is identified by a token of descriptor typetypeNull
, 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 thetypeWildCard
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 astypeMyTextToken
, and another entry that specifies the object class ascWord
and the token descriptor type astypeWildCard
, the Apple Event Manager dispatches the object accessor function associated with the entry that specifiestypeMyTextToken
.If you specify
typeWildCard
as the first parameter andtypeMyToken
as the second parameter for theAEInstallObjectAccessor
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 thetypeMyToken
descriptor type.If you specify
cText
as the first parameter andtypeWildCard
as the second parameter for theAEInstallObjectAccessor
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 classcText
in containers identified by tokens of any descriptor type.If you specify
typeWildCard
for both the first and second parameters of theAEInstallObjectAccessor
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.