Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 2 - Edition Manager / Using the Edition Manager

Receiving Apple Events From the Edition Manager

Applications that use the Edition Manager must support Apple events. This requires that your application support the required Open Documents event and Apple events sent by the Edition Manager. See the chapter "Introduction to Apple Events" in this book for general information on Apple events.

Apple events sent by the Edition Manager arrive as high-level events. The EventRecord data type defines the event record.

TYPE EventRecord =
   RECORD
      what:       Integer;    {kHighLevelEvent}
      message:    LongInt;    {'sect'}
      when:       LongInt;
      where:      Point;      {'read', 'writ', 'cncl', 'scrl'}
      modifiers:  Integer;
   END;

The Edition Manager can send these Apple events with the event class and event ID as shown here:

• Section Read events ('sect' 'read')
• Section Write events ('sect' 'writ')
• Section Cancel events ('sect' 'cncl')
• Section Scroll events ('sect' 'scrl')

Each time your application creates a publisher or a subscriber, the Edition Manager registers its section. When an edition is updated, the Edition Manager scans its list to locate registered subscribers. For each registered subscriber that is set up to receive updated editions automatically, your application receives a Section Read event.

If the Edition Manager discovers that an edition file is missing while registering a publisher, it creates a new edition file and sends the publisher a Section Write event.

When you receive a Section Cancel event, you need to cancel the specified section. Note that the current Edition Manager does not send you Section Cancel events, but you do need to provide a handler for future expansion.

If the user selects a subscriber within a document and then selects Open Publisher in the subscriber options dialog box, the publishing application receives the Open Documents event and opens the document containing the publisher. The publishing application also receives a Section Scroll event. Scroll to the location of the publisher, display this section on the user's screen, and turn on its border.

See "Opening and Closing a Document Containing Sections" beginning on page 2-22 for detailed information on registering and unregistering a section and writing data to an edition. See "Using Publisher and Subscriber Options" beginning on page 2-43 for information on publisher and subscriber options.

After receiving an Apple event sent by the Edition Manager, use the Apple Event Manager to extract the section handle. In addition, you must also call the IsRegisteredSection function to determine whether the section is registered. It is possible (because of a race condition) to receive an event for a section that you recently disposed of or unregistered. One way to ensure that an event corresponds to a valid section is to call the IsRegisteredSection function after you receive an event.

err := IsRegisteredSection (sectionH);

Listing 2-1 illustrates how to use the Apple Event Manager and install an event handler to handle Section Read events. You can write similar code for Section Write events, Section Scroll events, and Section Cancel events.

Listing 2-1 Accepting Section Read events and verifying if a section is registered

{the following goes in your initialization code}
myErr := AEInstallEventHandler(sectionEventMsgClass {'sect'},
                               sectionReadMsgID {'read'},
                               @MyHandleSectionReadEvent, 0,
                               FALSE);

{this is the routine the Apple Event Manager calls when a }
{ Section Read event arrives}

FUNCTION MyHandleSectionReadEvent(theAppleEvent,
                                  reply: AppleEvent;
                                  refCon: LongInt): OSErr;
VAR
   myErr:      OSErr;
   sectionH:   SectionHandle;
BEGIN
   {get section handle out of Apple event message buffer}
   myErr := MyGetSectionHandleFromEvent(theAppleEvent, sectionH);
   IF myErr = noErr THEN
   BEGIN
      IF IsRegisteredSection(sectionH) = noErr THEN
         {if section is registered, read the new data}
         MyHandleSectionReadEvent := DoSectionRead(sectionH);
   END 
   ELSE
      MyHandleSectionReadEvent := myErr;
END; {MyHandleSectionReadEvent}


{this routine reads in subscriber data and updates its display}
FUNCTION DoSectionRead(subscriber: SectionHandle): OSErr;
BEGIN
   {your code here}
END;  {DoSectionRead}
{this is part of your Apple event-handling code}
FUNCTION MyGetSectionHandleFromEvent(theAppleEvent: AppleEvent;
                                     VAR sectionH: SectionHandle)
                                     : OSErr;
VAR
   ignoreType:    DescType;
   ignoreSize:    Size;
BEGIN
   {parse section handle out of message buffer}
   MyGetSectionHandleFromEvent
      := AEGetParamPtr( theAppleEvent,    {event to parse}
                        keyDirectObject,  {look for direct }
                                          { object}
                        typeSectionH,     {want a SectionHandle}
                        ignoreType,       {ignore type it could }
                                          { get}
                        @sectionH,        {put SectionHandle }
                                          { here}
                        SizeOf(sectionH), {size of storage for }
                                          { SectionHandle}
                        ignoreSize);      {ignore storage it }
                                          { used}
END; {MyGetSectionHandleFromEvent} 

In addition to the Section Read, Section Write, Section Cancel, and Section Scroll events, your application can also respond to the Create Publisher event. For more information on this event, as well as additional information on how to handle Apple events, see the chapter "Responding to Apple Events" in this book.