Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Handling Apple Events

Handling Apple Events Sent by the Edition Manager

If your application provides publish and subscribe capabilities, it should handle the Apple events sent by the Edition Manager in addition to the required Apple events. Your application should also handle the Create Publisher event, which is described in the "Handling the Create Publisher Event" section on page 4-22.

The Edition Manager sends your application Apple events to communicate information about the publishers and subscribers in your application's documents. Specifically, the Edition Manager uses Apple events to notify your application

• when the information in an edition is updated
• when your application needs to write the data from a publisher to an edition
• when your application should locate a particular publisher and scroll through the document to that location

The Section Read, Section Write, and Section Scroll Events

The following descriptions identify the three Apple events sent by the Edition Manager--Section Read, Section Write, and Section Scroll--and the actions they tell applications to perform.

Section Read--read information into the specified section
Event class		SectionEventMsgClass
Event ID		SectionReadMsgID
Required parameter
	Keyword:	keyDirectObject
	Descriptor type:	typeSectionH
	Data:	A handle to the section record of the subscriber whose edition contains updated information
Requested action		Update the subscriber with the new information from the edition.

Section Write--write the specified section to an edition
Event class		SectionEventMsgClass
Event ID		SectionWriteMsgID
Required parameter
	Keyword:	keyDirectObject
	Descriptor type:	typeSectionH
	Data:	A handle to the section record of the publisher
Requested action		Write the publisher's data to its edition.

Section Scroll--scroll through the document to the specified section
Event class		SectionEventMsgClass
Event ID		SectionScrollMsgID
Required parameter
	Keyword:	keyDirectObject
	Descriptor type:	typeSectionH
	Data:	A handle to the section record of the publisher to scroll to
Requested action		Scroll through the document to the publisher identified by the specified section record.

See the chapter "Edition Manager" in this book for details on how your application should respond to these events.

Handling the Create Publisher Event

If your application supports publish and subscribe capabilities, it should also handle the Create Publisher event.

Create Publisher--create a publisher
Event class		kAEMiscStdSuite
Event ID		kAECreatePublisher
Required parameter		None
Optional parameter
	Keyword:	keyDirectObject
	Descriptor type:	typeObjectSpecifier
	Data:	An object specifier record that specifies the Apple event object or objects to publish. If this parameter is omitted, publish the current selection.
Optional parameter
	Keyword:	keyAEEditionFileLoc
	Descriptor type:	typeAlias
	Data:	An alias record that contains the location of the edition container to create. If this parameter is omitted, use the default edition container.
Requested action		Create a publisher for the specified data using the specified location for the edition container. If the data isn't specified, publish the current selection. If the location of the edition isn't specified, use the default location.

When your application receives the Create Publisher event, it should create a publisher and write the publisher's data to an edition. The data of the publisher, and the location and name of the edition, are defined by the Apple event. If the Create Publisher event includes a keyDirectObject parameter, then your application should publish the data contained in the parameter. If the keyDirectObject parameter is missing, then your application should publish the current selection. If the document doesn't have a current selection, your handler for the event should return a nonzero result code.

If the Create Publisher event includes a keyAEEditionFileLoc parameter, your application should use the location and name contained in the parameter as the default location and name of the edition. If the keyAEEditionFileLoc parameter is missing, your application should use the default location and name your application normally uses to specify the edition container.

Listing 4-9 shows a handler for the Create Publisher event. This handler checks for the keyDirectObject parameter and the keyAEEditionFileLoc parameter. If either of these is not specified, the handler uses default values. The handler uses the application-defined function DoNewPublisher to create the publisher and its edition, create a section record, and update other data structures associated with the document. See the chapter "Edition Manager" in this book for an example of the DoNewPublisher function.

Listing 4-9 A handler for the Create Publisher event

FUNCTION MyHandleCreatePublisherEvent (theAppleEvent,
                                       reply: AppleEvent; 
                                       handlerRefcon: LongInt)
                                       : OSErr;
VAR   
   myErr:                  OSErr;
   returnedType:           DescType;
   thePublisherDataDesc:   AEDesc;
   actualSize:             LongInt;
   promptForDialog:        Boolean;
   thisDocument:           MyDocumentInfoPtr;
   preview:                Handle; 
   previewFormat:          FormatType; 
   defaultLocation:        EditionContainerSpec;
BEGIN
   MyGetDocumentPtr(thisDocument);
   myErr := AEGetParamDesc(theAppleEvent, keyDirectObject, 
                           typeObjectSpecifier, 
                           thePublisherDataDesc);
   CASE myErr OF
      errAEDescNotFound: 
      BEGIN
         {use the current selection as the publisher and set up }
         { info for later when DoNewPublisher displays preview}
         preview := MyGetPreviewForSelection(thisDocument);
         previewFormat := 'TEXT';
      END;
      noErr: 
         {use the data in keyDirectObject parameter as the }
         { publisher (which is returned in the }
         { thePublisherDataDesc variable), and set up info for }
         { later when DoNewPublisher displays preview}
         MySetInfoForPreview(thePublisherDataDesc, thisDocument, 
                             preview, previewFormat);
      OTHERWISE
      BEGIN
         MyHandleCreatePublisherEvent := myErr;
         Exit(MyHandleCreatePublisherEvent);
      END; 
   END;
   myErr := AEDisposeDesc(thePublisherDataDesc);

   myErr := AEGetParamPtr(theAppleEvent, keyAEEditionFileLoc, 
                         typeFSS, returnedType, 
                         @defaultLocation.theFile,
                         SizeOf(FSSpec), actualSize);
   CASE myErr OF
      errAEDescNotFound: 
         {use the default location as the edition container}
            myErr := MyGetDefaultEditionSpec(thisDocument, 
                                             defaultLocation);
      noErr: 
      BEGIN             {the keyAEEditionFileLoc parameter }
                        { contains a default location}
         defaultLocation.thePart := kPartsNotUsed;
         defaultLocation.theFileScript := smSystemScript;
      END;
      OTHERWISE
      BEGIN
         MyHandleCreatePublisherEvent := myErr;
         Exit(MyHandleCreatePublisherEvent);
      END; 
   END;
   myErr := MyGotRequiredParams(theAppleEvent);
   IF myErr <> noErr THEN
   BEGIN
      MyHandleCreatePublisherEvent := myErr;
      Exit(MyHandleCreatePublisherEvent);
   END;
   myErr := AEInteractWithUser(kAEDefaultTimeout, gMyNotifyRecPtr, 
                                 @MyIdleFunction);
   IF myErr = noErr THEN promptForDialog := TRUE
                    ELSE promptForDialog := FALSE;
   myErr := DoNewPublisher(thisDocument, promptForDialog, 
                           preview, previewFormat, 
                           defaultLocation);
   {add keyErrorNumber and keyErrorString parameters if desired}
END;

Note that the MyHandleCreatePublisherEvent handler in Listing 4-9 uses the AEInteractWithUser function to determine whether user interaction is allowed. If so, the handler sets the promptForDialog variable to TRUE, indicating that the DoNewPublisher function should display the publisher dialog box. If not,
the handler sets the promptForDialog variable to FALSE, and the DoNewPublisher function does not prompt the user for the location or name of the edition. For more information about AEInteractWithUser, see "Interacting With the User," which begins on page 4-47.