Inside Macintosh: OpenDoc Class Reference /

Part 1 - Classes and Methods

ODPart

Superclasses

ODPersistentObject --> ODRefCntObject --> ODObject

Subclasses

none

An object of a subclass of ODPart represents a part editor.

Description

Parts are the building blocks of OpenDoc documents. A compound document can contain one or more parts, each manipulated by a part editor. A part editor is much like an application; it can display and change the content of a part, handle events, perform disk I/O, and accept scripting commands. A part editor directly manipulates the content, the intrinsic content, of its part.

The ODPart class is an abstract superclass that you must subclass to create your part editor. Your implementation is the executable code that provides the structure and behavior of your parts. When you subclass ODPart, you need to override only those methods that represent specific capabilities supported by your part editor.

OpenDoc or another part creates your part object by calling the draft's CreatePart method (page 168). OpenDoc or another part can also access a previously created, stored part by calling the draft's AcquirePart method (page 156). These methods return a reference to a part object.

Layout and Imaging

OpenDoc provides an environment for managing the geometric relationships among frames and objects when your part draws itself. OpenDoc notifies each part when the part editor must draw the part. Each part is responsible for drawing its own content (including, at certain times, the borders of its embedded frames). A part does not draw the interiors of its embedded frames because they contain the content of other parts (which must draw themselves). Drawing may occur asynchronously, in response to update events, or when activation or deactivation affects highlighting. A part editor typically draws in the context of a particular facet. The part editor gets the clipping, transform, and layout information from the facet and its frame, and then must make platform-specific graphics calls to actually draw the lines, polygons, text, and so on that make up its part.

A container part can define a set of container properties (such as text font, background color, or pen width) that it prefers its embedded parts to adopt to enhance the visual continuity between them. Embedded parts that can read a given container part's container properties can then adopt those properties that are appropriate.

View Type and Presentation

Each frame has a view type, the basic visual representation of a part in that frame. Parts must support the standard set of view types (large icon, small icon, thumbnail, and frame view). The presentation of a frame describes a particular style of display for a part's content within the frame when its view type is framed. Presentations are part-defined; your part editor determines what types of presentations your part can handle. Your part is notified if its containing part changes the view type or presentation of one of its display frames.

Frame Negotiation

Each part in an OpenDoc document controls the position, size, and shape of its embedded frames. If an embedded part needs to change the size, shape, or number of frames it is displayed in, it must negotiate for that change with its containing part. Frame negotiation allows an embedded part to communicate its needs to its containing part.

Initialization and Storage

Your part editor must be able to initialize its parts, as well as read and write their content to and from persistent storage in its document. The data of each part in a document is kept in at least one storage unit, the basic unit of persistent storage, distinct from data in other parts. You use the contents property of your storage unit for storing all your part's data.

Your part-editor code should never pass out a pointer to somSelf, except to supported extensions and your embedded-frames iterator. Instead, your part must store and pass out a reference to a part wrapper--an object that forwards all method calls to your part. Part wrappers insulate OpenDoc from requiring a direct reference to your part. A reference to a stored part wrapper is specified in your part's InitPart method (page 529) or InitPartFromStorage method (page 530). The reference is defined for the lifetime of your part; once set, it cannot be changed.

Event Handling

OpenDoc handles events such as mouse clicks and keystrokes, menu commands, activation and deactivation of windows, and other platform-specific events. Part editors do not receive events directly from the operating system; rather, OpenDoc receives events, interprets them, and dispatches them, using the dispatcher, to the appropriate part editor's HandleEvent method (page 526). Based on information in an event, your part editor might update your part, open or close windows, perform editing operations, transfer data, perform menu commands, or perform other operations. For more information on event handling in OpenDoc, see the chapter on user events in the OpenDoc Programmer's Guide for the MacOS.

Keeping Track of Display Frames and Embedded Frames

Your part can display its content in one or more frames at the same time, displaying either duplicate views or different aspects of the same part. This makes it easy for your part to be visible in several windows or to have several different presentations. Identical views of your part in two or more separate display frames must be synchronized, meaning that any editing or other changes to one display frame forces updating of the others. If your part is a containing part, your part calls its embedded frame's AttachSourceFrame method (page 481) to initiate synchronization of it embedded frames.

Your part must maintain a list of all frames in which it is displayed. In addition, if your part is a containing part, it must maintain a list of all frames directly embedded within it. For embedded frames, you may use whatever format for that list that works best for your implementation, but you must provide an embedded-frames iterator (a subclass of ODEmbeddedFramesIterator) to allow access to the frames.

For efficient memory usage, your part does not need to keep frame objects in memory for all its embedded frames or display frames. Instead, it can release frames as they become invisible through scrolling and then get them back from the draft as they become visible. For more information related to frame objects, see the ODFrame class description (page 294).

Part Kind and Binding

Parts store their data in formats defined by part kind, a typing scheme analogous to file type. OpenDoc uses the concept of part kind to determine what part editor is to be associated with a given part in a document. You can design your part editor to manipulate more than one part kind, and your part can be stored with multiple representations of its data, each of a different part kind. To maximize fidelity in case your part is later edited by a different part editor, your part editor must always store its part kinds in order from highest fidelity to lowest.

Linking

Your part uses linking to export updatable data to another part, or to incorporate or embed an updatable copy of another part's data into your part. If your part is the source of a link, you interact with a link-source object; if your part is the destination of a link, you interact with a link object.

Overriding ODPart Methods

The following table lists the methods of ODPart that you must override to have a functioning part editor, as well as those that you can optionally override to participate in specific protocols. Note that some protocols, such as layout, imaging, and activation, are required of all part editors, and you must override some or all of the methods associated with them. Other protocols, such as embedding or undo, are not required, and you need not override any of their methods if your parts do not participate. It is, of course, strongly recommended that your parts participate in all protocols.

Required and optional ODPart overrides

Protocol	Required overrides	Optional overrides
Layout	AttachSourceFrame ContainingPartPropertiesUpdated DisplayFrameAdded DisplayFrameClosed DisplayFrameConnected DisplayFrameRemoved FacetAdded FacetRemoved FrameShapeChanged GeometryChanged Open SequenceChanged	AcquireContainingPartProperties[1] RevealFrame[1]
Imaging	CanvasChanged Draw GetPrintResolution HighlightChanged PresentationChanged ViewTypeChanged	AdjustBorderShape[1] CanvasUpdated[1]
Activation	AbortRelinquishFocus BeginRelinquishFocus CommitRelinquishFocus FocusAcquired FocusLost
User events	AdjustMenus HandleEvent
Storage	CloneInto[2] ClonePartInfo Externalize[2] ExternalizeKinds InitPart InitPartFromStorage ReadPartInfo WritePartInfo	somInit[2] somUninit[2]
Binding	ChangeKind
Memory management	ReleaseAll[2]	Acquire[2] Purge[2] Release[2]
Linking	LinkStatusChanged	CreateLink EditInLinkAttempted[1] FulfillPromise LinkUpdated RevealLink
Embedding		CreateEmbeddedFramesIterator[1] EmbeddedFrameUpdated[1] RemoveEmbeddedFrame[1] RequestEmbeddedFrame[1] RequestFrameShape[1] UsedShapeChanged<[1]
Clipboard		FulfillPromise
Drag and drop		DragEnter DragLeave DragWithin Drop DropCompleted FulfillPromise
Undo		DisposeActionState ReadActionState RedoAction UndoAction WriteActionState
Extensions		AcquireExtension[2] HasExtension[2] ReleaseExtension[2]
Semantic events		EmbeddedFrameSpec[1]

Overriding Inherited Methods

The following methods are inherited and available for use by your subclass of ODPart. You need to override only those methods that represent specific capabilities supported by your part editor.

somInit

The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.

When you subclass ODPart, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.

Your override of this method should initialize the new instance variables in your part. The SOM library calls this method when your part is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in your part's InitPart or InitPartFromStorage method.

somUninit

The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.

When you subclass ODPart, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.

Your override of this method should dispose of any storage created for your part, including any storage related to additional instance variables initialized in your part. The SOM library calls this method when your part is deleted; this method must not fail.

HasExtension

The HasExtension method returns a Boolean value that indicates whether an object supports a specified extension; it is inherited from the ODObject class.

ODBoolean HasExtension (in ODType extensionName);

When you subclass ODPart, you can override this method if your part supports extensions. If your part does not support the specified extension, your override method must call its inherited method at the end of your implementation. The client of the extension object must be prepared in the event that the specified extension is not supported.

Your override of this method should return kODTrue if your part supports the specified extension, otherwise kODFalse. A client of an extension object calls this method to determine whether your part supports extensions, for example, scripting.

AcquireExtension

The AcquireExtension method returns a reference to a specified extension object; it is inherited from the ODObject class.

ODExtension AcquireExtension (in ODType extensionName);

When you subclass ODPart, you can override this method if your part supports extensions. If your part does not support the specified extension, your override method must call its inherited method at the end of your implementation. The client of the extension object must be prepared in the event that the specified extension is not supported.

Your override of this method should return a reference to your part's extension object (for example, a semantic interface object). A client of an extension object calls this method to obtain a reference to the specified extension.

ReleaseExtension

The ReleaseExtension method releases a specified extension object; it is inherited from the ODObject class.

void ReleaseExtension (in ODExtension extension);

When you subclass ODPart, you can override this method if your part supports extensions. If your part does not support the specified extension, your override method must call its inherited method at the end of your implementation. The client of the extension object must be prepared in the event that the specified extension is not supported.

Your override of this method should release the specified extension object (acquired when your part's AcquireExtension method was called). A client of an extension object calls this method when it finishes working with your part's extension.

Acquire

The Acquire method increments an object's reference count by 1; it is inherited from the ODRefCntObject class.

void Acquire ();

When you subclass ODPart, you can override this method if your part performs any specific actions when its reference count is incremented. Your override method must call its inherited method at the beginning of your implementation.

The inherited Acquire method increments your part's reference count by 1. A part editor calls this method when it stores a reference to your part. When the reference is replaced or removed, a part editor calls your part's Release method.

Release

The Release method decrements an object's reference count by 1 and tells the draft to release the object from memory if the object's reference count becomes 0; it is inherited from the ODRefCntObject class.

void Release ();

When you subclass ODPart, you can override this method if your part needs to release an object and reclaim valuable resources like memory. Your override method must call its inherited method at the beginning of your implementation.

The inherited Release method decrements your part's reference count by 1. The inherited method may delete your part from memory (if your part's reference count becomes 0). A part editor calls this method when it no longer needs a reference to your part.

The Release method must not return an exception; any exceptions thown by calls in the implementation must be caught and not reraised.

ReleaseAll

The ReleaseAll method releases all transitory references to other reference-counted objects; it is inherited from the ODPersistentObject class.

void ReleaseAll ();

When you subclass ODPart, you can override this method if your part maintains references to other persistent objects. Your override method must call its inherited method at the end of your implementation.

Your override of this method should release all persistent objects it points to, remove any link specifications your part has written to the clipboard, relinquish all foci, and clear any undo actions it has written to the undo stack. However, the implementation must not make any call that changes the persistent state of another object.

The ReleaseAll method must not return an exception; any exceptions thown by calls in the implementation must be caught and not reraised.

For any extension that cannot be deleted because of a positive reference count, your override method must also call its base extension's BaseRemoved method. If your part's embedded frames are being traversed by an embedded-frames iterator when your part is deleted, your override method must also call your embedded-frames iterator's PartRemoved method.

OpenDoc calls this method once before your part is deleted, for example, when your part's document is closed. If the part being deleted has a promise, the promise is resolved before the part is deleted.

CloneInto

The CloneInto method clones a persistent object by copying its data into a specified storage unit; it is inherited from the ODPersistentObject class.

void CloneInto (in ODDraftKey key, 
                in ODStorageUnit toSU, 
                in ODFrame scope);

When you subclass ODPart, you must override this method to support data interchange of internal data. Your override method must call its inherited method at the beginning of your implementation. The inherited method clones the kODPropCreateDate, kODPropModDate, and kODPropModUser properties.

Your override of this method should write your part's data into the specified storage unit and clone any additional objects to which your part has strong and weak persistent references and that are within the specified scope. OpenDoc calls this method if your part is being copied to the clipboard, the drag-and-drop object, or a link-source object.

Externalize

The Externalize method writes a persistent object to storage; it is inherited from the ODPersistentObject class.

void Externalize ();

When you subclass ODPart, you can override this method if your part maintains persistent content. Your override method must call its inherited method at the beginning of your implementation.

Your override of this method should write your part's persistent state to the properties and values your part created when it initialized itself in your part's InitPart method (page 529); it should write sufficient information to allow your InitPartFromStorage method (page 530) to restore your part to its current state. Your part editor calls this method when your part stores its content data.

Purge

The Purge method frees memory on request; it is inherited from the ODObject class.

ODSize Purge (in ODSize size);

Every subclass of ODObject can override this method and should do so if it creates caches and temporary buffers. When you subclass ODPart, you must override this method or risk running out of available memory. Your override method must call its inherited method at some point in your implementation (it does not matter where). You should save the size value returned by the inherited method because you will need it to compute the value to return from your override method.

Your override of this method should free any caches, noncritical buffers, or objects (up to the amount of memory specified). If absolutely necessary, your part can first write any data it needs to persistent storage, although that is not recommended because writing to storage requires additional memory allocation. Your override of this method should add the number of bytes actually freed to the number returned by the inherited method and return the sum as the total amount of memory released. OpenDoc calls this method in low-memory situations; you should not allocate memory for this operation.

Methods

This section presents summary descriptions of the ODPart methods grouped according to purpose, followed by detailed descriptions in alphabetical order.

Initialization and Storage

InitPart

Initializes this part object.

InitPartFromStorage

Initializes this part object from its stored data.

ReadPartInfo

Should read the part info data for a display frame of this part from the specified storage-unit view object.

WritePartInfo

Should write the part info data for a display frame of this part into the specified storage-unit view object.

ClonePartInfo

Should clone a display frame's part info data into the specified storage-unit view object.

ExternalizeKinds

Should write to storage a representation for each part kind within the specified kind list that this part supports.

Binding

ChangeKind

Should change this part's preferred kind.

IsRealPart

Returns a Boolean value that indicates whether this part is an actual part (as opposed to a part wrapper).

GetRealPart

Returns a reference to a part object encapsulated by the part wrapper.

ReleaseRealPart

Releases the part object encapsulated by the part wrapper.

Imaging

CanvasChanged

Should transfer asynchronous imaging to a new canvas.

CanvasUpdated

Should copy the content of the specified canvas (owned by this part) to its parent canvas.

Draw

Should draw this part within the area that needs updating in the specified facet.

GetPrintResolution

Should return the minimum desired resolution, in dots per inch, required for printing the content of the specified display frame.

HighlightChanged

Should update the highlight state of the specified facet of this part.

Facet Manipulation

FacetAdded

Should notify this part that a facet has been added to one of its display frames.

FacetRemoved

Should notify this part that a facet has been removed from one of its display frames.

GeometryChanged

Should notify this part that the clip shape or external transform (or both) of one of this part's facets has changed.

Frame Negotiation

FrameShapeChanged

Should notify this part that the frame shape of one of its display frames has changed.

RequestEmbeddedFrame

Should create a new display frame for the specified embedded part.

RequestFrameShape

Should negotiate a new frame shape for the specified frame embedded in this part.

Display Frame Manipulation

AttachSourceFrame

Should associate a source frame with a display frame for this part.

DisplayFrameAdded

Should add the specified frame to this part's internal list of display frames.

DisplayFrameClosed

Should notify this part that one of its display frames has been closed.

DisplayFrameConnected

Should add the specified frame to this part's internal list of display frames.

DisplayFrameRemoved

Should remove the specified frame from this part's internal list of display frames.

PresentationChanged

Should notify this part that the presentation of one of its display frames has changed.

ViewTypeChanged

Should notify this part that the view type of one of its display frames has changed.

SequenceChanged

Should notify this part that the sequencing of this part's display frame within its frame group has changed.

Open

Should create or activate a window in which a frame of this part is the root frame.

Embedded Frame Manipulation

AdjustBorderShape

Should adjust the shape of an embedded frame's active frame border.

CreateEmbeddedFramesIterator

Should create an embedded-frames iterator to give callers access to all embedded frames of this part.

RemoveEmbeddedFrame

Should remove the specified embedded frame from this part's content.

EmbeddedFrameSpec

Should create an object specifier for the specified embedded frame in this part.

RevealFrame

Should make the specified embedded frame visible by scrolling it into view.

UsedShapeChanged

Should notify this part that the used shape of one of its embedded frames has changed.

Focus Manipulation

AbortRelinquishFocus

Should reestablish this part's ownership of the focus specified in a previous call to this part's BeginRelinquishFocus method.

BeginRelinquishFocus

Should return a Boolean value that indicates whether this part is willing to relinquish the requested focus and should prepare this part to do so.

CommitRelinquishFocus

Should complete this part's relinquishing of ownership of the specified focus.

FocusAcquired

Should notify this part that one of its display frames has acquired the specified focus.

FocusLost

Should notify this part that one of its display frames has lost the specified focus.

Event Handling

AdjustMenus

Should prepare this part's menus for display.

HandleEvent

Should attempt to handle the specified user event.

Undo

RedoAction

Should redo the specified action.

UndoAction

Should undo the specified action.

DisposeActionState

Should dispose of the undo action data.

ReadActionState

Should read the undo action data from the specified storage-unit view object.

WriteActionState

Should write the undo action data into the specified storage-unit view object.

Linking

CreateLink

Should create a link-source object for this part.

EmbeddedFrameUpdated

Should update any of this part's link-source objects affected by a change to the specified embedded frame.

EditInLinkAttempted

Should return a Boolean value that indicates whether this part maintains the destination of a link that includes the embedded frame.

LinkStatusChanged

Should notify this part that the link status of one of its display frames has changed.

LinkUpdated

Should replace the content at each destination of a link with new content from an updated link object.

RevealLink

Should show the content at the source of a link.

Data Interchange

DragEnter

Should begin tracking a drag operation.

DragWithin

Should track a drag operation and provide graphical feedback regarding possible drop targets.

DragLeave

Should finish tracking a drag operation and deactivate this part from drag tracking.

Drop

Should move or copy the dragged data into this part.

DropCompleted

Should notify this part that a drop operation, resulting from an asynchronous drag initiated from this part, is complete.

FulfillPromise

Should fulfill a promise by providing the content data the promise represents.

Container Properties

AcquireContainingPartProperties

Should write into a storage unit the container properties this part associates with the specified embedded frame and then return the storage unit.

ContainingPartPropertiesUpdated

Should notify this part that its containing part's container properties have changed.

---

[1] Required of all parts that support embedding

---

[2] Defined in a superclass of ODPart; see "Overriding Inherited Methods"

---

Methods

AbortRelinquishFocus
AcquireContainingPartProperties
AdjustBorderShape
AdjustMenus
AttachSourceFrame
BeginRelinquishFocus
CanvasChanged
CanvasUpdated
ChangeKind
ClonePartInfo
CommitRelinquishFocus
ContainingPartPropertiesUpdated
CreateEmbeddedFramesIterator
CreateLink
DisplayFrameAdded
DisplayFrameClosed
DisplayFrameConnected
DisplayFrameRemoved
DisposeActionState
DragEnter
DragLeave
DragWithin
Draw
Drop
DropCompleted
EditInLinkAttempted
EmbeddedFrameSpec
EmbeddedFrameUpdated
ExternalizeKinds
FacetAdded
FacetRemoved
FocusAcquired
FocusLost
FrameShapeChanged
FulfillPromise
GeometryChanged
GetPrintResolution
GetRealPart
HandleEvent
HighlightChanged
InitPart
InitPartFromStorage
IsRealPart
LinkStatusChanged
LinkUpdated
Open
PresentationChanged
ReadActionState
ReadPartInfo
RedoAction
ReleaseRealPart
RemoveEmbeddedFrame
RequestEmbeddedFrame
RequestFrameShape
RevealFrame
RevealLink
SequenceChanged
UndoAction
UsedShapeChanged
ViewTypeChanged
WriteActionState
WritePartInfo

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help