Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records / Creating Object Specifier Records

Creating a Simple Object Specifier Record

This section shows how to use the CreateObjSpecifier function to create the object specifier record shown in Table 6-7. The CreateObjSpecifier function creates the necessary keyword-specified descriptor records for the class ID, container, key form, and key data and returns the resulting object specifier record as a descriptor record of type typeObjectSpecifier.

Listing 6-12 shows how the CreateObjSpecifier function creates an object specifier record from parameters that an application specifies.

Listing 6-12 Creating an object specifier record using CreateObjSpecifier

VAR
   desiredClass:        DescType; 
   myObjectContainer:   AEDesc; 
   myKeyForm:           DescType; 
   myKeyDataDesc:       AEDesc; 
   disposeInputs:       Boolean; 
   myObjSpecRec:        AEDesc;
   myErr:               OSErr;

desiredClass := cRow;
myObjectContainer := MyGetContainer;
myKeyForm := formAbsolutePosition;
myKeyDataDesc := MyGetKeyData;
disposeInputs := TRUE;
{create an object specifier record}
myErr := CreateObjSpecifier(desiredClass, myObjectContainer, 
                              myKeyForm, myKeyDataDesc, 
                              disposeInputs, myObjSpecRec);

The code shown in Listing 6-12 demonstrates how an application might use the CreateObjSpecifier function to create four keyword-specified descriptor records as part of a descriptor record of type typeObjectSpecifier. The CreateObjSpecifier function returns a result code of noErr if the object specifier record was successfully created. The object specifier record returned in the myObjSpecRec parameter describes an Apple event object of the class specified by the desiredClass parameter, located in the container specified by the myObjectContainer parameter, with the key form specified by the myKeyForm parameter and key data specified by the myKeyDataDesc parameter.

You can specify TRUE in the disposeInputs parameter if you want the CreateObjSpecifier function to dispose of the descriptor records you created for the myObjectContainer and myKeyDataDesc parameters. If you specify FALSE, then your application is responsible for disposing of these leftover descriptor records.

Listing 6-13 shows an application-defined function that uses CreateObjSpecifier to create an object specifier record for the first row in the table named "Summary of Sales" in the document "Sales Report," then uses the object specifier record returned in the myObjSpecRec parameter as the direct parameter for a Get Data event.

Listing 6-13 Using CreateObjSpecifier in an application-defined function

FUNCTION MyRequestRowFromTarget (targetAddress: AEAddressDesc; 
                                 VAR reply: AppleEvent): OSErr;
VAR
   desiredClass:           DescType;
   myKeyForm:              DescType;
   myObjectContainer:      AEDesc;
   myObjSpecRec:           AEDesc;
   myKeyDataDesc:          AEDesc;
   keyData:                LongInt;
   theAppleEvent:          AppleEvent;
   myErr:                  OSErr;
   ignoreErr:              OSErr;

BEGIN
   {initialize (set to null descriptor records) the two descriptor records } 
   { that must eventually be disposed of}
   MyInit2DescRecs(myObjSpecRec, theAppleEvent);

   desiredClass := cRow;                     {specify the class}
                                             {specify container for the row}
   myErr := MyCreateTableContainer(myObjectContainer, 
                                    'Summary of Sales', 'Sales Report');
   IF myErr = noErr THEN 
   BEGIN
      myKeyForm := formAbsolutePosition;     {specify the key form}
      keyData := 1;                          {specify the key data for row}
      myErr := AECreateDesc(typeLongInteger, @keyData, Sizeof(keyData), 
                              myKeyDataDesc);
      IF myErr = noErr THEN
         {create the object specifier record}
         myErr := CreateObjSpecifier(desiredClass, myObjectContainer, 
                                       myKeyForm, myKeyDataDesc, 
                                       TRUE, myObjSpecRec);
      IF myErr = noErr THEN
         {myObjSpecRec now describes an Apple event object, and will become } 
         { direct parameter of a Get Data event; first create Get Data event}
         myErr := AECreateAppleEvent(kAECoreSuite, kAEGetData, targetAddress, 
                                       kAutoGenerateReturnID, 
                                       kAnyTransactionID, theAppleEvent);



      IF myErr = noErr THEN
         {add myObjSpecRec as the direct parameter of the Get Data event}
         myErr := AEPutParamDesc(theAppleEvent, keyDirectObject,
                                 myObjSpecRec);
      IF myErr = noErr THEN
         myErr := AESend(theAppleEvent, reply, kAEWaitReply + 
                         kAENeverInteract, kAENormalPriority, 120, 
                         @MyIdleFunction, NIL);
   END;
   ignoreErr := AEDisposeDesc(myObjSpecRec);
   ignoreErr := AEDisposeDesc(theAppleEvent);
   MyRequestRowFromTarget := myErr;
END;

The MyRequestRowFromTarget function shown in Listing 6-13 specifies the class ID as cRow, indicating that the desired Apple event object is a row in a table. It uses the application-defined function MyCreateTableContainer to create an object specifier record for the table that contains the row, passing "Summary of Sales" and "Sales Report" as the second and third parameters to identify the name of the table and the name of the document that contains the table. (The next section, "Specifying the Container Hierarchy," explains how to construct the MyCreateTableContainer function.) It then specifies the key form as the constant formAbsolutePosition, which indicates that the key data specifies the position of the row within its container; sets the keyData variable to 1, indicating the first row, and uses AECreateDesc to create a descriptor record for the key data; and uses CreateObjSpecifier to create the object specifier record that describes the desired word.

The desired row is now fully described by the myObjSpecRec variable, which contains a descriptor record of type typeObjectSpecifier that contains the three nested object specifier records shown in Table 6-7 on page 6-67. After using AECreateAppleEvent to create a Get Data event, the MyRequestRowFromTarget function uses the AEPutParamDesc function to add the myObjSpecRec variable to the Get Data event as a direct parameter, then uses AESend to send the Get Data event.

Note that the MyRequestRowFromTarget function begins by using the application-defined function MyInit2DescRecs to set myObjSpecRec and theAppleEvent to null descriptor records. These two functions must be disposed of whether the function is successful or not. By setting them to null descriptor records, the function can dispose of them at the end regardless of where an error may have occurred.

Specifying the Container Hierarchy

Because the container for an object specifier record usually consists of a chain of other object specifier records that specify the container hierarchy, your application must create all the object specifier records in the chain, starting with the record for the outermost container. Listing 6-14 and Listing 6-15 demonstrate how to use the CreateObjSpecifier function to create the first two object specifier records in such a chain: the records for a document and a table.

Listing 6-14 Specifying a document container

FUNCTION MyCreateDocContainer (VAR myDocContainer: AEDesc;
                               docName: Str255): OSErr;
VAR
   myDocDescRec:  AEDesc;
   nullDescRec:   AEDesc;
   myErr:         OSErr;
BEGIN
   {create a descriptor record for the name of the document}
   myErr := AECreateDesc(typeChar, @docName[1], 
                           Length(docName), myDocDescRec);
   IF myErr = noErr THEN
      {create a null descriptor record}
      myErr := AECreateDesc(typeNull, NIL, 0, nullDescRec);
   IF myErr = noErr THEN
      {create an object specifier record to specify the }
      { document object}
      myErr := CreateObjSpecifier(cDocument, nullDescRec, 
                                  formName, myDocDescRec, TRUE, 
                                  myDocContainer);
   MyCreateDocContainer := myErr;
END;

The function MyCreateDocContainer in Listing 6-14 creates an object specifier record that identifies a document by name. It starts by using the AECreateDesc function to create two descriptor records: one of type typeChar for the name of the document, and one of type typeNull for the null descriptor record that specifies the default container (because the document is not contained in any other Apple event object). These two descriptor records can then be used as parameters for the CreateObjSpecifier function, which returns an object specifier record (that is, a descriptor record of type typeObjectSpecifier) in the myDocContainer variable. The object specifier record specifies an Apple event object of the object class cDocument in the container specified by the nullDescRec variable with a key form of formName and the key data specified by the myDocDescRec variable. This object specifier can be used by itself to specify a document, or it can be used to specify the container for another Apple event object.

Listing 6-15 shows an application-defined function, MyCreateTableContainer, that creates an object specifier record describing a table contained in a document.

Listing 6-15 Specifying a table container

FUNCTION MyCreateTableContainer (VAR myTableContainer: AEDesc;
                                 tableName: Str255;
                                 docName: Str255): OSErr;
VAR
   myDocDescRec:        AEDesc;
   myTableDescRec:      AEDesc;
   myErr:               OSErr;
BEGIN
   {create a container for the document}
   myErr := MyCreateDocContainer(myDocDescRec, docName);
   IF myErr = noErr THEN
   BEGIN
      {create the table container, }
      { first specify the descriptor record for the key data}
      myErr := AECreateDesc(typeChar, @tableName[1], 
                              Length(tableName), myTableDescRec);
      IF myErr = noErr THEN
         myErr := CreateObjSpecifier(cTable, myDocDescRec,
                                    formName, myTableDescRec, 
                                    TRUE, myTableContainer);
   END;
   MyCreateTableContainer := myErr;
END;

The function MyCreateTableContainer in Listing 6-15 starts by using the function MyCreateDocContainer from Listing 6-14 to create an object specifier record that identifies the table's container--the document in which the table is located. Then it uses the AECreateDesc function to create a descriptor record for the key data--a name that, when combined with the key form formName, will identify the table in the document. The object specifier record for the document and the descriptor record specifying the table's name are passed to the function CreateObjSpecifier. It returns an object specifier record in the myTableContainer parameter that specifies an Apple event object of the object class cTable in the container specified by the MyDocDescRec variable with a key form of formName and the key data specified by the myTableDescRec variable. This object specifier record can be used by itself to specify a table, or it can be used to specify the container for another Apple event object.

Listing 6-13 uses the MyCreateTableContainer function shown in Listing 6-15 to specify the container hierarchy illustrated in Table 6-7 on page 6-67. The nested object specifier records shown in Table 6-7 use the key forms formName and formRelativePosition. You can create key data for the key forms formPropertyID, formUniqueID, and formRelativePosition using similar techniques.

Specifying a Property

The key form formPropertyID allows your application to specify key data identifying a property of the object specified as a container. For example, an object specifier record that identifies the font property of a word specifies cProperty as the class ID, an object specifier record for the word as the property's container, formPropertyID as the key form, and the constant pFont as the key data.

Note that an object specifier record that identifies a property does not include a value for the property, such as Palatino. The value of a property is returned or set as a parameter of an Apple event. For example, an application that sends a Get Data event to get the pFont property of a word receives a value such as Palatino in the keyAEResult parameter of the reply event, and an application that sends a Set Data event to change the pFont property of a word specifies a font in the keyAEData parameter of the Set Data event.

To specify the key data for a key form of formPropertyID, your application must create a descriptor record of typeType whose data consists of a constant specifying a property. You can use AECreateDesc to create a descriptor record that specifies the constant for a property, then use CreateObjSpecifier to add the descriptor record to an object specifier record as a keyword-specified descriptor record with the keyword keyAEKeyData.

For more information about object specifier records that specify a property, see "Key Data for a Property ID" on page 6-14.

Specifying a Relative Position

The key form formRelativePosition allows your application to specify key data identifying an element or a set of elements that are immediately before or after the specified container. For example, if the container is a table, you could use a key form of formRelativePosition to specify the paragraph before or after the table.

To specify the key data for a key form of formRelativePosition, your application must create a descriptor record of typeEnumerated whose data consists of a constant specifying either the element after (kAENext) or the element before (kAEPrevious) the specified container.

You can use AECreateDesc to create a descriptor record that specifies one of these constants, then use CreateObjectSpecifier to add it to an object specifier record as a keyword-specified descriptor record with the keyword keyAEKeyData.

For more information about object specifier records that specify a relative position, see "Key Data for Relative Position" on page 6-16.