Inside Macintosh: Programmer's Guide to MacApp / Part 1 - MacApp Theory and Architecture

Chapter 7 - Document Handling

Publish and Subscribe

MacApp supports publish and subscribe using the Edition Manager, which became available in Macintosh system software starting with System 7. The Edition Manager supports dynamic data exchange between applications--data can be shared within a single document, between documents created by a single application, or between the documents of two or more applications. The data and applications can be on the same disk or distributed across a network. The Edition Manager is described in detail in the "Edition Manager" chapter of Inside Macintosh: Interapplication Communications.

MacApp's built-in support takes care of much of the overhead required to use the Edition Manager in your application. MacApp supplies menu and alert resources, implements a number of classes, and dispatches Edition Manager Apple events to the objects that can handle them. An application can support publish and subscribe for the data types 'PICT', 'TEXT', and 'snd ' by overriding a relatively small number of methods, most of them in its document class. The Calc sample application distributed with MacApp demonstrates support for publishing and subscribing cell data in a spreadsheet.

Edition Manager Terminology

The following terms are used to describe Edition Manager functions:

• A section is a portion of a document that shares its contents with other documents. There are two kinds of sections:
  • A publisher is a section that makes its data available to other documents or applications.
  • A subscriber is a section that obtains its data from other documents or applications.

• An application publishes data by writing it to a separate file called an edition container. The published data is known as an edition.
• An application subscribes to data by reading it from an edition container.

The Edition Manager sends an Edition Manager event, also called a section event, to inform an application that an action is required. For example, a subscriber may be notified that it should update itself by reading its edition container.

Edition Manager Resources

In the file Edition.r, MacApp supplies a number of resources for its Edition Manager support, including

• an 'aedt' resource, which MacApp uses to map the four section Apple events (Section Read, Section Write, Section Scroll, and Section Cancel) to command constants
• various alert resource definitions used by the Edition Manager

In the file Defaults.r, MacApp supplies additional Edition Manager resources, including

• an Edit menu 'CMNU' resource that includes the Edition Manager menu commands (see "Edition Manager Menu Commands" on page 186)
• an 'aete' resource that includes Edition Manager Apple events supported by MacApp (For more information on 'aete' resources, see Chapter 6, "Scripting.")

Edition Manager Menu Commands

MacApp's Edition Manager support adds publish-and-subscribe menu commands to the Edit menu:

• Create Publisher...

  The Create Publisher menu command is enabled whenever publishable data is selected. When the user chooses Create Publisher, the application displays a create publisher dialog, which may include a preview of the data to be published. If the user clicks the Publish button, the application creates a publisher and writes the selected data to an edition container file, with a filename specified by the user.

• Subscribe To...

  The Subscribe To menu command is enabled whenever the user is able to import data into the current document. When the user chooses Subscribe To, the application displays a subscribe to dialog, which can preview the data in a selected edition container. If the user clicks the Subscribe button, the application creates a subscriber, reads the selected edition container, and displays its data.

• Publisher Options.../Subscriber Options...

  This command's text is toggled based on whether a publisher or subscriber was most recently selected. The Publisher Options command is enabled whenever a publisher is selected; the Subscriber Options command is enabled whenever a subscriber is selected.

  When the user chooses this command, the application puts up a dialog box to display information about the selected publisher or subscriber. The user can modify information in the dialog box or perform certain actions, such as canceling the selected publisher or subscriber.

• Show Borders/Hide Borders

  The text for the Show Borders/Hide Borders command is toggled based on whether the current state is to show borders or hide borders. This menu command should always be enabled.

  When the user changes the state from show to hide, the current view is redrawn with all publisher and subscriber borders hidden. When the user changes the state from hide to show, the view is redrawn with all borders shown.

  Supporting this menu command is optional.

• Stop All Editions

  The Stop All Editions menu command is always enabled. When the user chooses this command for the first time, it becomes checked. Additional choices toggle the checked state.

  When Stop All Editions is checked, the application temporarily stops all updating of sections within the document. It stops all publishers from sending data to editions, and all subscribers from receiving new editions.

  When Stop All Editions is chosen again, the application removes the checkmark and updates any subscribers that are set up to receive new editions automatically.

  Supporting this menu command is optional.

Edition Manager Classes

MacApp defines several classes to work with the Edition Manager:

• Designator classes specify a portion of a document's data for publishing or subscribing.
• Section classes work with designators and know how to publish or subscribe to data.
• The TEditionDocument class extends the TFileBasedDocument class to work with publish and subscribe sections.
• The TSectionBehavior class handles mouse operations related to publish and subscribe. The TEditionDocument class adds a TSectionBehavior object whenever you call the DoAddSectionBehavior method.
• The TSectionMgr behavior class handles section Apple events from the Edition Manager by creating section commands to perform the specified actions. An instance of the TSectionMgr class is added to the application object.
• Command classes based on subclasses of the TSectionCommand class perform the section read, section write, section scroll, and section cancel operations.
• Section adorner classes know how to draw borders for publish and subscribe sections in views.
• The section iterator class knows how to iterate over the publisher and subscriber sections in a document's section list.

These classes are described in greater detail in the sections that follow.

The Designator Classes

MacApp supplies the TDesignator class and its subclasses, TLinearDesignator, TVRectDesignator, and TRegionDesignator, to aid in specifying the data for a selected area of your document. A designator knows how to read and write its range. If you wish to publish or subscribe to data that can't be designated with one of these classes, you define a subclass to work with your data representation.

Designators are recommended for keeping track of selections in all applications. MacApp's TPublisher and TSubscriber classes use designators to work with the data they publish or subscribe to.

The Section Classes

The TSection class is an abstract class that encapsulates the common behavior for objects that publish and subscribe to data. Each TSection object has a reference to the document that owns it and each can

• register and unregister itself with the Edition Manager
• create itself from resources in the document's resource fork
• store itself in the document's resource fork

The TSection class has two subclasses for publishing or subscribing to data. The first, TPublisher, publishes data to an edition container file. Publisher objects tell the document to write the designated data to a stream by calling the TDocument::DoWriteData method.

The other subclass, TSubscriber, reads data from an edition container file. Subscriber objects tell the document to read the data from a stream by calling the TDocument::DoReadData method.

The TPublisher and TSubscriber classes support publish and subscribe for the data types 'PICT', 'TEXT', and 'snd '. To support other data types, your application can extend these classes.

The TEditionDocument Class

The TEditionDocument class is a subclass of TFileBasedDocument that adds a number of fields and methods for publishing and subscribing. The edition document keeps a list containing all publisher and subscriber section objects in use by the document. Its DoSetupMenus method enables publish and subscribe menu commands, and its DoMenuCommand method responds when a user chooses one of those commands.

When you initialize an instance of TEditionDocument (or a subclass), you call the IEditionDocument method, passing a parameter that specifies the document type for publisher edition container files created by the document. The IEditionDocument method calls InitUSectionMgr, which (the first time it is called) creates a behavior object of type TSectionMgr and adds it to your application object.

Methods You Override

Although TEditionDocument has many methods that deal with publishing and subscribing, your document can ignore most of them. A document subclass of TEditionDocument generally overrides just the following methods:

DoReadData, DoWriteData
These are actually methods of TDocument. You override them to read subscribed data from an edition container or write published data to a container.

DoAddBorder, DoDeleteBorder
You must override these methods to add or remove section borders. (You use section adorners to actually draw or erase the borders.)

CanSubscribe

The CanSubscribe method in TEditionDocument returns TRUE if there is a user selection, the selection contains something, and there isn't another subscriber currently selected. If your document has other subscribe criteria, you override this method.

CanPublishSelection

The CanPublishSelection method in TEditionDocument returns TRUE if there is a user selection, the selection contains something, and there isn't already a noncanceled publisher exactly contained in the current selection. If your document has other publish criteria, you override this method.

Reading and Writing Section Data

The edition document's DoWrite method performs several actions:

• It warns the user if the document has multiple publishers to the same edition. (The user is also warned at the time a publisher is created with an edition with the same name as a previous edition.)
• It writes out the edition settings as a resource. The settings include the Boolean state of the fStopAllEditions and fShowSectionBorders fields.
• It iterates through the sections associated with the document and tells each to write itself by calling its DoWrite method.

The edition document's DoRead method creates a section object to read each section resource in the document's resource fork and calls AddSection to add the section to the document's section list.

The TSectionMgr Class

The TSectionMgr class contains code to handle the four section Apple events: Section Read, Section Write, Section Scroll and Section Cancel. These events are dispatched to the section manager's DoAESectionEvent method by the application object's DoScriptCommand method.

When your application receives a section event, MacApp automatically maps it to one of the predefined command constants shown in Table 7-2.

Table 7-2 Table 7-2 MacApp section events

Section event constant	When specified
cSectionRead	When subscribers need to read themselves from disk
cSectionWrite	When publishers need to write themselves to disk
cSectionScroll	When the user clicks the Open Publisher button in the subscriber options dialog box or in the Finder's edition window
cSectionCancel	When the user cancels a section in a document

The section manager handles each of the section commands by creating and posting a command object.

The Section Command Classes

MacApp implements four section command classes, based on the TSectionCommand class, each of which responds to a particular Edition Manager event.

• TSectionReadEventCommand. The Edition Manager sends a Section Read event to notify the application that a new version of the referenced subscriber is available. This happens whenever a new version of the subscriber's publisher is written to the edition container file. TSectionReadEventCommand tells its section object (a TSubscriber object) to read a fresh copy of itself from disk.
• TSectionWriteEventCommand. The Edition Manager sends a Section Write event to notify the application that the referenced publisher needs to publish its contents to the edition container. This can happen in response to two conditions:
  • when the Edition Manager discovers that the edition container, which it creates before sending this event, does not yet exist
  • when the user toggles the automatic/manual setting on the publisher and the publisher is out of date

    TSectionWriteEventCommand tells its section object (a TPublisher object) to publish itself to disk.

• TSectionScrollEventCommand. The Edition Manager sends a Section Scroll event to notify the application that the user clicked the Open Publisher button in the subscriber options dialog box. The Edition Manager first sends the 'odoc' event to your application, so MacApp has opened the document before this event is received. The TSectionScrollEventCommand performs three functions:
  • If the application is not frontmost, it uses the Process Manager to make it so.
  • It tells the document to reveal that portion of itself that corresponds to the publisher.
  • It forces the document to respond by selecting the view that is displaying the publisher, scrolling the window so that the publisher is visible, and selecting the portion of the view that is published.

• TSectionCancelEventCommand. When the user cancels a section, the section manager creates a TSectionCancelEventCommand to
  • cancel the publisher
  • remove the publisher from the document section list
  • delete the publisher's edition container file
  • free the publisher object

Section Adorner Classes

The Macintosh human interface guidelines suggest a 3-pixel border for publishers and subscribers. The border should be 50 percent gray for publishers and 75 percent gray for subscribers, with a 1-pixel white border separating the section from the border.

MacApp uses adorners to provide these borders. The TSectionAdorner class is a subclass of TAdorner that encapsulates common publisher and subscriber adornment. The TPublisherAdorner class draws borders for TPublisher objects and TSubscriberAdorner draws borders for TSubscriber objects.

You can read more about adorners in "Adorners," beginning on page 213. The Calc sample application uses adorners to provide section borders.

The Section Iterator Class

The TSectionIterator class iterates over the publisher and subscriber sections in a document's section list. For example, the TEditionDocument DoNeedDiskSpace method iterates over the document's sections to determine how much space they will take up on disk.