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.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.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 thekeyDirectObject
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 thekeyAEEditionFileLoc
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 thekeyAEEditionFileLoc
parameter. If either of these is not specified, the handler uses default values. The handler uses the application-defined functionDoNewPublisher
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 theDoNewPublisher
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 theAEInteractWithUser
function to determine whether user interaction is allowed. If so, the handler sets thepromptForDialog
variable toTRUE
, indicating that theDoNewPublisher
function should display the publisher dialog box. If not,
the handler sets thepromptForDialog
variable toFALSE
, and theDoNewPublisher
function does not prompt the user for the location or name of the edition. For more information aboutAEInteractWithUser
, see "Interacting With the User," which begins on page 4-47.