Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 2 - Edition Manager / Using the Edition Manager

Opening and Closing a Document Containing Sections

When opening a document that contains sections, your application should use the GetResource function to get the section record and the alias record for each publisher and subscriber. Set the alias field of the section record to be the handle to the alias. See the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox for detailed information on the GetResource function.

You also need to register each section using the RegisterSection function. The RegisterSection function informs the Edition Manager that a section exists.

err := RegisterSection(sectionDocument, sectionH,
                       aliasWasUpdated);

The RegisterSection function adds the section record to the Edition Manager's list of registered sections. This function assumes that the alias field of each section record is a handle to the alias record. The alias record is a reference to the edition container from the section's document. If the RegisterSection function successfully locates the edition container for a particular section, the section is registered through a shared control block. The control block is a private field in the section record.

If the RegisterSection function cannot find the edition container for a particular subscriber, RegisterSection returns the containerNotFoundWrn result code. If the RegisterSection function cannot find the edition container for a particular publisher, RegisterSection creates an empty edition container for the publisher in the last place the edition was located. The Edition Manager sends your application a Section Write event for that section.

When a user attempts to open a document that contains multiple publishers to the same edition, you should warn the user by displaying an alert box (see "Duplicating Publishers and Subscribers" on page 2-58).

When a user opens a document that contains a subscriber (with an update mode set to automatic), receives a new edition, and then closes the document without making any changes to the file, you should update the document and simply allow the user to close it. You do not need to prompt the user to save changes to the file.

When closing a document that contains sections, you must unregister each section (using the UnRegisterSection function) and dispose of each corresponding section record and alias record.

err := UnRegisterSection(sectionH);

The UnRegisterSection function removes the section record from the list of registered sections and unlinks itself from the shared control block.

Listing 2-3 illustrates how to open an existing file that contains sections. As described earlier, you should retrieve the section and alias resources, connect the pair through the alias field of the section record, and register the section with the Edition Manager. There are many different techniques for retrieving resources; this listing shows one technique. If an alias was out of date and was updated by the Alias Manager during the resolve, the Edition Manager sets the aliasWasUpdated parameter of the RegisterSection function to TRUE. This means that you should save the document. Additionally, your application must maintain its own list of registered sections for each open document that contains sections. You use this list to write out new editions for updated publishers within a document.

Listing 2-3 Opening a document containing sections

PROCEDURE MyOpenExistingDocument(thisDocument: MyDocumentInfoPtr);
VAR
   sectionH:            SectionHandle;
   aliasH:              AliasHandle;
   aliasWasUpdated:     Boolean;
   registerErr:         OSErr;
   resID:               Integer;
   theResType:          ResType;
   thisone:             Integer;
   numberOfSections:    Integer;
   aName:               Str255;
BEGIN
   UseResFile(thisDocument^.resForkRefNum);
   {find out the number of section resources}
   numberOfSections := Count1Resources(rSectionType);
   FOR thisone := 1 TO numberOfSections DO
   BEGIN
      sectionH := SectionHandle(Get1IndResource(rSectionType,
                                              thisone));
      IF sectionH = NIL THEN  {something could be wrong with }
         MySectionErr;        { the file, handle appropriately} 
      {get resource ID of the section & use same ID for alias}
      GetResInfo(Handle(sectionH), resID, theResType, aName);
      {detaching is not necessary, but it is convenient}
      DetachResource(Handle(sectionH));
      {get the alias}
      aliasH := AliasHandle(Get1Resource(rAliasType, resID));
      IF aliasH = NIL THEN    {something could be wrong with }
         MyAliasErr;          { the file, handle appropriately} 
      DetachResource(Handle(aliasH));

      {connect section and alias together}
      sectionH^^.alias := aliasH;
      {register the section}
      registerErr := RegisterSection(thisDocument^.fileSpec,
                                     sectionH, aliasWasUpdated);
      {The RegisterSection function may return an error if }
      { a section is not registered. This is not a fatal error. }
      { Continue looping to register remaining sections.}
      {add this section/alias pair to your internal bookkeeping}
      MyAddSectionAliasPair(thisDocument, sectionH, resID);
      IF aliasWasUpdated THEN 
         {If alias has changed, make a note of this. }
         { It's important to know this when you save.}
         MyAliasHasChanged(sectionH);
   END; {end of FOR}
END;