When the user selects a particular export format, clsApp sends msgExport to that format's translator. The message argument for msgExport points to an
EXPORT_DOC structure that contains:
exportType A tag that indicates the export type in the EXPORT_FORMAT structure that the user selected.
source A locator for the source document.
destination An open file handle on the destination.
path The path to the destination document.
The translator should use this information to export the information in the document into the file. It is the exporting application's responsibility to clean up any invalid file handles. If the export fails, this includes the destination file handle provided by msgExport.
Chapter 82 / The Selection Manager
The selection manager provides a mechanism for keeping track of what process owns the current selection, the data the user has selected for subsequent action such as copying or deleting. Because the selection can be owned by many different types of objects, the selection manager does not do any formatting.
The selection manager keeps track of the selection owner, even when the object that contains the selection is not on screen.
clsSelection defines messages that allow objects to request ownership of the selection. clsSelection can record the current selection owner before changing ownership to another object.
An instance of clsSelection-theSelectionManager-keeps track of the current selection owner and the preserved selection, if any. theSelectionManager is the only instance of clsSelection.
Topics covered in this chapter:
• Selection concepts.
• Determining the selection.
• Existing PenPoint classes that handle the selection.
• Selection messages that operate on the selection.
• Selection messages sent to selection owners.
• Selection messages passed to the selection manager.
Concepts
No more than one object can own the current selection at anyone time. Objects can request ownership of the selection. There doesn't always have to be a selection.
If the user hasn't selected anything, there is no selection owner.
The Selection Manager
The ownership of the selection is administered by theSelectionManager, the only instance of clsSelection. theSelectionManager has the following responsibilities:
• It handles the transition between the current selection owner and the new selection owner.
• It keeps track of the current selection owner.
• It sends messages to observers of theSelectionManager when selection ownership changes.
156 PENPOINT ARCHITECTURAL REFERENCE Part 9 / Utility Classes
The theSelectionManager is the only instance of the selection class, clsSelection, which defines two categories of messages:
• Messages that provide function for theSelectionManager.
• Abstract messages for common operations performed by owners of the selection. These abstract messages fall into two categories:
• Messages that an object or one of its ancestors must respond to (such as "delete the selection" or "yield the selection"). If these messages reach clsObject, it sends msgNotU nderstood.
• Messages that an object and its ancestors have the option of ignoring (such as "make yourself the selection"). If these messages reach clsObject, it returns stsIgnored.
You must always use ObjectCallO when you pass messages to theSelectionManager.
Selection Owners
Just about any object can own the selection, so long as it handles the required clsSelection messages. For example, when an object that owns the selection receives a message asking it to yield the selection, it must yield the selection and return.
Certain object types can't own the selection, either because there is no way for them to receive messages from theSelectionManager, or because other objects cannot communicate with them. These object types are:
• Objects that do not have global scope.
• Global objects that cannot receive messages (those for which objCapSend is disabled).
Any attempt to give an object of this type ownership of the selection will return a scope violation status code, stsScope Violation.
Preserving the Selection
There are times when you need to preserve the current selection while allowing the user to make a selection iri another window. Generally, the only time this is true is when using an option sheet. For example, the user might select some text in a text editor and then put up an option sheet. theSelectionManager preserves the text selection while the option sheet is up. The user can make a selection in the option sheet, do something with the selection. When the user closes the option sheet, the preserved text selection is restored.
CHAPTER 82 / THE SELECTION MANAGER 157 The Selection Class Messages
Selection Transitions
While theSelectionManager requests one object to yield ownership and gives ownership to another object, there is a time when the owner of the selection is not defined. If another clsSelection message arrives in this time, problems could arise.
To avoid these problems, some clsSelection messages return stsSelYieldlnProgress while it is in transition from one owner to another. For example, if you request the DID of the current selection owner (by sending msgSelOwner to
theSelectionManager) while ownership is in transition, msgSelOwner returns stsSelYieldlnProgress.
Certain other messages, rather than return stsSelYieldlnProgress, just wait longer than usual to complete, until the new owner is established. These messages are:
msgSelSetOwner msgSelDelete
A deadlock situation can occur if you receive msgSelYield and immediately send msgSelSetOwner to theSelectionManager, with your DID as the object to own the selection. Eventually the block on the requests times out, allowing your object to continue.