Programming Reference: ODPart

# Programming Reference

## ODPart

Class Definition File | Part.idl
Class C++ Binding | Part.xh

Class Hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODPersistentObject
                ODPart

Description

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

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 of its part, called its intrinsic content.

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. If 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. OpenDoc or another part can also access a previously created, stored part by calling the draft's AcquirePart method. 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 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 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 support 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 wrapper is specified in your part's InitPart or InitPartFromStorage method. 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. 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 Programming Guide.

Keeping Track of Display Frames and Embedded Frames

Your part can display its content in one or more frames at the same time, displaying 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 to initiate synchronization of its 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 class description for ODFrame.

Part Kinds and Binding

Parts store their data in formats defined by a part kind, a typing scheme analogous to a file type. OpenDoc uses the concept of part kinds 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 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 the ODPart class that you must override to have a functioning part editor, as well as those that you can optionally override to participate in specific protocols. Some protocols, layout, imaging, and activation, are required of all part editors, and you must override some or all of the associated methods. Other protocols, embedding or undoing, are not required, and you do not need to override any of their methods if your parts do not participate. Your parts should participate in all protocols.

Table 1. Required and Optional ODPart Protocols

Protocol | Required Overrides | Optional Overrides
--- | --- | ---

Layout

    AttachSourceFrame
    ContainingPartPropertiesUpdated
    DisplayFrameAdded
    DisplayFrameClosed
    DisplayFrameConnected
    DisplayFrameRemoved
    FacetAdded
    FacetRemoved
    FrameShapeChanged
    GeometryChanged
    Open
    SequenceChanged

    AcquireContainingPartProperties*
    RevealFrame*

Imaging

    CanvasChanged
    Draw
    GetPrintResolution
    HighlightChanged
    PresentationChanged
    ViewTypeChanged

    AdjustBorderShape*
    CanvasUpdated*

Activation

    AbortRelinquishFocus
    BeginRelinquishFocus
    CommitRelinquishFocus
    FocusAcquired
    FocusLost

User Events

    AdjustMenus
    HandleEvent

Storage

    CloneInto**
    ClonePartInfo
    Externalize**
    ExternalizeKinds
    InitPart
    InitPartFromStorage
    ReadPartInfo
    WritePartInfo

    somInit**
    somUninit**

Binding | ChangeKind |

Memory Management

ReleaseAll**

    Acquire**
    Purge**
    Release**

Linking

LinkStatusChanged

    CreateLink
    EditInLinkAttempted*
    FulfillPromise
    LinkUpdated
    RevealLink

Embedding

    CreateEmbeddedFramesIterator*
    EmbeddedFrameUpdated*
    RemoveEmbeddedFrame*
    RequestEmbeddedFrame*
    RequestFrameShape*
    UsedShapeChanged*

Clipboard

    FulfillPromise

Drag and Drop

    DragEnter
    DragLeave
    DragWithin
    Drop
    DropCompleted
    FulfillPromise

Undo

    DisposeActionState
    ReadActionState
    RedoAction
    UndoAction
    WriteActionState

Extensions

    AcquireExtension**
    HasExtension**
    ReleaseExtension**

Semantic Events

    EmbeddedFrameSpec*

Note:

>     *  Required of all parts that support embedding.
>     ** Defined in a superclass of ODPart;
>        see "Overriding Inherited Methods."

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.

- Acquire
- AcquireExtension
- CloneInto
- Externalize
- HasExtension
- Purge
- Release
- ReleaseAll
- ReleaseExtension
- somInit
- somUninit

Methods

The methods defined by the ODPart class include the following, grouped by purpose:

Initialization and Storage

- ClonePartInfo
- ExternalizeKinds
- InitPart
- InitPartFromStorage
- ReadPartInfo
- WritePartInfo

Binding

- ChangeKind
- GetRealPart
- IsRealPart
- ReleaseRealPart

Imaging

- CanvasChanged
- CanvasUpdated
- Draw
- GetPrintResolution
- HighlightChanged

Facet Manipulation

- FacetAdded
- FacetRemoved
- GeometryChanged

Frame Negotiation

- FrameShapeChanged
- RequestEmbeddedFrame
- RequestFrameShape

Display Frame Manipulation

- AttachSourceFrame
- DisplayFrameAdded
- DisplayFrameClosed
- DisplayFrameConnected
- DisplayFrameRemoved
- Open
- PresentationChanged
- SequenceChanged
- ViewTypeChanged

Embedded Frame Manipulation

- AdjustBorderShape
- CreateEmbeddedFramesIterator
- EmbeddedFrameSpec
- RemoveEmbeddedFrame
- RevealFrame
- UsedShapeChanged

Focus Manipulation

- AbortRelinquishFocus
- BeginRelinquishFocus
- CommitRelinquishFocus
- FocusAcquired
- FocusLost

Event Handling

- AdjustMenus
- HandleEvent

Undo

- DisposeActionState
- ReadActionState
- RedoAction
- UndoAction
- WriteActionState

Linking

- BreakLink (OS/2)
- BreakLinkSource (OS/2)
- CreateLink
- EditInLinkAttempted
- EmbeddedFrameUpdated
- LinkBroken (OS/2)
- LinkStatusChanged
- LinkUpdated
- RevealLink
- ShowLink (OS/2)
- UpdateFromLinkSource (OS/2)

Data Interchange

- DragEnter
- DragLeave
- DragWithin
- Drop
- DropCompleted
- FulfillPromise

Container Properties

- AcquireContainingPartProperties
- ContainingPartPropertiesUpdated

Menu Bar Creation

- CreateRootMenuBar (OS/2)

Overridden Methods | There are no methods overridden by the ODPart class.

### AbortRelinquishFocus

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

Signature

    void AbortRelinquishFocus (ODTypeToken focus,
                               ODFrame *ownerFrame,
                               ODFrame *proposedFrame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type that was to be relinquished.

  This parameter must be the tokenized form of a focus constants or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to an ODFocusType constant. For a list of ODFocusType constants, see ODFocusType

ownerFrame (ODFrame *) - input

  A reference to a display frame that owns the focus.

proposedFrame (ODFrame *) - input

  A reference to a frame that originally requested the focus.

Returns

None.

Remarks

A request for a focus set is conditional; if any focus owner is unwilling to relinquish a focus, then none are acquired. Your part's AbortRelinquishFocus method should give those focus owners who have indicated willingness to relinquish the focus an opportunity to back out of changes initiated when OpenDoc first called your part's BeginRelinquishFocus method. When a request for a focus set fails because one of the focus owners will not relinquish ownership, OpenDoc aborts the request to relinquish all of the focuses by calling each part's AbortRelinquishFocus method.

Your part's AbortRelinquishFocus method should return your part to the state where it possessed the focus before continuing to use that focus; how it does this is dependent on your part editor and the type of focus relinquished. Calling this method should have no effect if your part's BeginRelinquishFocus method returned kODFalse.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::BeginRelinquishFocus
- ODPart::CommitRelinquishFocus
- ODSession::Tokenize

### AcquireContainingPartProperties

This method writes into a storage unit the container properties this part associates with the specified embedded frame and then returns the storage unit.

Signature

    ODStorageUnit *AcquireContainingPartProperties (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to an embedded frame of this part.

Returns

rv (ODStorageUnit *) - returns

  A reference to the storage unit that contains the container properties for the specified frame.

Remarks

The part embedded in this part calls this method to request the container properties that this part associates with the embedded part's display frame.

Before returning the storage unit object, your part's AcquireContainingPartProperties method should call the storage unit object's Acquire method. When the caller has finished using the returned storage unit, it should call the storage unit object's Release method.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | The specified frame is not an embedded frame of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

Related Methods

- ODPart::ContainingPartPropertiesUpdated

### AdjustBorderShape

This method adjusts the shape of an embedded frame's active frame border.

Signature

    ODShape *AdjustBorderShape (ODFacet *embeddedFacet,
                                ODShape *shape)

Parameters

embeddedFacet (ODFacet *) - input

  A reference to an embedded facet whose active frame border is to be adjusted.

shape (ODShape *) - input

  A reference to a shape object defining the current active frame border or kODNULL if the active frame border is transferred to an embedded part of another part.

Returns

rv (ODShape *) - returns

  A reference to a revised shape object to use for the embedded frame's active frame border, clipped by this part's content and used shape.

Remarks

OpenDoc calls this method when a frame embedded in this part has the selection focus. OpenDoc draws the active frame border, associated with the frame's facet, on the border of the facet's frame. Your part's AdjustBorderShape method may be called multiple times for a containing part that has several facets for the same embedded frame.

Your part's AdjustBorderShape method should clip the specified shape to account for content elements (including other embedded frames) that obscure portions of the active frame border, and then return the shape. Before returning the shape object, your part's AdjustBorderShape method should call the shape object's Acquire method (unless it modifies the requested shape object and returns that same object). When the caller has finished using the returned shape object, it should call the shape object's Release method.

Your part's AdjustBorderShape method should also adjust the clip shape of your part's facet to account for portions of the active frame border that obscure your content.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFacet | The specified facet is not an embedded facet of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

### AdjustMenus

This method should prepare this part's menus for display.

Signature

    void AdjustMenus (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame whose menus are to be displayed.

Returns

None.

Remarks

OpenDoc calls this method when this part has the menu focus or is the root part and when there is a mouse-down event in the menu bar.

Your part's AdjustMenus method should perform any actions necessary to enable and disable menu items as appropriate to its current state. Your part's AdjustMenus method can use the ODMenuBar methods to change the appearance of your menu items, or it can make platform-specific calls to directly enable, disable, mark or change the text of your menu items.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### AttachSourceFrame

This method should associate a source frame with a display frame for this part.

Signature

    void AttachSourceFrame (ODFrame *frame,
                            ODFrame *sourceFrame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame for this part.

sourceFrame (ODFrame *) - input

  A reference to a display frame to be used as the source for the specified display frame.

Returns

None.

Remarks

This part's containing part calls this method. This method tells this part to keep two or more of its display frames synchronized. The containing part calls this method immediately after creating a new display frame for this part.

Your part's AttachSourceFrame method should perform any actions necessary to synchronize the frames. If the two frames have identical presentations, your method should copy all embedded frames in the source frame into other frames (and attach the copied embedded frames to their source frames by calling the embedded part's AttachSourceFrame method).

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### BeginRelinquishFocus

This method should indicate whether this part is willing to relinquish the requested focus and should prepare this part to do so.

Signature

    ODBoolean BeginRelinquishFocus (ODTypeToken focus,
                                    ODFrame *ownerFrame,
                                    ODFrame *proposedFrame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be relinquished.

  This parameter must be the tokenized form of a focus constants or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to an ODFocusType constant. For a list of ODFocusType constants, see ODFocusType.

ownerFrame (ODFrame *) - input

  A reference to a display frame that owns the focus.

proposedFrame (ODFrame *) - input

  A reference to a frame requesting ownership of the focus.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this part is willing to relinquish the requested focus.

  kODTrue | This part is willing to relinquish the requested focus.
  kODFalse | This part is not willing to relinquish the requested focus.

Remarks

OpenDoc calls this method when ownership of the specified focus is requested and this part is the current owner. Upon receiving this call, this part decides whether it can relinquish the specified focus. Each part has part-specific requirements that must be met before it can relinquish a focus. If these requirements are met, this part should be ready to relinquish the focus.

Your part's BeginRelinquishFocus method should return kODTrue or kODFalse, based on the type of focus and the identities of the frames (current and proposed focus owners) passed in. In most cases, your method should return kODTrue. However, your method might return kODFalse, for example, if your part is displaying a modal dialog box and another part is requesting the modal focus. In that case, because your part does not want to yield the modal focus until its modal dialog box closes, your method should return kODFalse. In situations when your method does return kODFalse, your part's AbortRelinquishFocus method does not need to take any action.

Your part's BeginRelinquishFocus method should also ensure that, during the process of relinquishing the specified focus and before your part's CommitRelinquishFocus method is called, your part does not enter a state where the focus cannot be relinquished.

Exception Handling

kODErrInvalidFrame | The specified owner frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::AbortRelinquishFocus
- ODPart::CommitRelinquishFocus
- ODSession::Tokenize

### BreakLink (OS/2)

This method should indicate that the user chose, in the Link page of the Properties notebook, to break a link connection.

Signature

    void BreakLink (ODLink *link)

Parameters

link (ODLink *) - input

  The link object to be disconnected from its link source.

Returns

None.

Remarks

There is no default action in this method except to raise an exception, kODErrSubClassResponsibility.

Your part should unregister and release the link object and update any tables maintained by the part which associated the link object with the link content. This includes identifying embedded frames within this content as no longer being part of this link target and calling the ChangeLinkStatus method.

Exception Handling

kODErrSubClassResponsibility | The subclass must override this method.

Override Policy

If you subclass ODPart, you must override this method. Your override method must call the link's Release method.

### BreakLinkSource (OS/2)

This method should indicate that the user has chosen, in the Link Source page of the Properties notebook, to break a link source from all connected links.

Signature

    void BreakLinkSource (ODLinkSource *linkSource)

Parameters

linkSource (ODLinkSource *) - input

  The link source object to be discarded.

Returns

None.

Remarks

There is no default action in this method except to raise an exception kODErrSubClassResponsibility.

Your part should update any tables maintained by the part which associate the link-source object with the link-source content. This includes identifying embedded frames within this content as no longer being part of this link source and calling the ChangeLinkStatus method.

Exception Handling

kODErrSubClassResponsibility | The subclass must override this method.

Override Policy

If you subclass ODPart, you must override this method. Your override method must call the link source's SetSourcePart method with the sourcePartSU parameter set to kODNULL and then release the link-source object.

### CanvasChanged

This method should transfer asynchronous imaging to a new canvas.

Signature

    void CanvasChanged (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to a facet with the new canvas.

Returns

None.

Remarks

OpenDoc calls this method if an offscreen canvas is assigned to, changed, or removed from your part's facet while your part is running. Your part must prepare to draw on the new canvas, update the cached information, and alter asynchronous display information.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### CanvasUpdated

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

Signature

    void CanvasUpdated (ODCanvas *canvas)

Parameters

canvas (ODCanvas *) - input

  A reference to a canvas that is to be updated.

Returns

None.

Remarks

Your part's CanvasUpdated method is called when an area of a canvas owned by this part changes and needs to be updated. The owning part's facet calls this method to allow the owning part to copy the image of the offscreen canvas to its parent canvas during updates.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.

Override Policy

If you subclass ODPart you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

### ChangeKind

This method should change this part's preferred kind.

Signature

    void ChangeKind (ODType kind)

Parameters

kind (ODType) - input

  The preferred kind to be assigned to this part.

Returns

None.

Remarks

OpenDoc calls this method if the user has chosen a new preferred kind for this part in the Properties notebook (for example, a request that a Styled Text part change into an ASCII part).

After your part's ChangeKind method executes successfully, your part should begin using the specified part kind as its preferred kind and begin manipulating your part's data in the new format. Your part should write the preferred kind into a kODPropPreferredKind property in its storage unit and store its part kinds in order from highest fidelity to lowest.

Exception Handling

kODErrUnsupportedKind | The part does not support that kind of content. (This exception is supported by the part developer.)

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function. Your override method must be implemented, not implemented only when a part supports multiple kinds.

### ClonePartInfo

This method should clone a display frame's part-information data into the specified storage-unit view object.

Signature

    void ClonePartInfo (ODDraftKey key,
                        ODInfoType partInfo,
                        ODStorageUnitView *storageUnitView,
                        ODFrame *scope)

Parameters

key (ODDraftKey) - input

  The draft key identifying a particular cloning operation. The key provides thread-safe access to cloning.

partInfo (ODInfoType) - input

  The part-information data to be cloned.

storageUnitView (ODStorageUnitView *) - input

  A reference to a storage-unit view object that is focused to the frame's part-information property, but not to any value within that property.

scope (ODFrame *) - input

  A reference to a display frame that defines the scope of the cloning operation. All cloned storage units must be within the scope of the specified frame.

Returns

None.

Remarks

When a document is saved as a copy (the Save a Copy command from the Document menu) or data is transferred (using drag-and-drop or linking), OpenDoc may ask your part to save a display frame's part-information data to a particular storage unit. OpenDoc calls this method when it writes the part-information data for a display frame of your part.

Your part's ClonePartInfo method must get the storage unit associated with the specified storage-unit view and focus it to the values in the frame's part-information property as necessary to write the formats it needs.

Your part's ClonePartInfo method should write out the part-information data. Your part's ClonePartInfo method should also clone any additional objects to which your part has strong persistent references and that are within the specified display frame's scope.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::ReadPartInfo
- ODPart::WritePartInfo

### CommitRelinquishFocus

This method should complete this part's relinquishing of ownership of the specified focus.

Signature

    void CommitRelinquishFocus (ODTypeToken focus,
                                ODFrame *ownerFrame,
                                ODFrame *proposedFrame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be relinquished.

  This parameter must be the tokenized form of a focus constants or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to an ODFocusType constant. For a list of ODFocusType constants, see ODFocusType.

ownerFrame (ODFrame *) - input

  A reference to a display frame that owns the focus.

proposedFrame (ODFrame *) - input

  A reference to a frame that requested the focus.

Returns

None.

Remarks

Your part's CommitRelinquishFocus method should complete the process initiated when OpenDoc first called your part's BeginRelinquishFocus method. If all focus owners in a given request for a focus set are willing to relinquish focus, OpenDoc calls each part's CommitRelinquishFocus method.

Your part's CommitRelinquishFocus method should perform any actions necessary to relinquish the specified focus to OpenDoc. Some actions depend on the nature and implementation of the part itself, but others are standard. Your part's CommitRelinquishFocus method should remove menus or palettes of your part's frame, remove highlighting, and relinquish any external resources associated with the specified focus. Remember that the focus might be moving from one frame to another of the same part, so the exact actions can vary.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::AbortRelinquishFocus
- ODPart::BeginRelinquishFocus
- ODSession::Tokenize

### ContainingPartPropertiesUpdated

This method should notify this part that its containing part's container properties have changed.

Signature

    void ContainingPartPropertiesUpdated (ODFrame *frame,
                                          ODStorageUnit *propertyUnit)

Parameters

frame (ODFrame *) - input

  A reference to a display frame to which the container properties apply.

propertyUnit (ODStorageUnit *) - input

  A reference to a storage unit that contains the changed container properties.

Returns

None.

Remarks

This part's containing part calls this method when the container properties it provides for adoption have changed. Your part's ContainingPartPropertiesUpdated method should inspect the specified storage unit for container properties that this part can understand. Where applicable, your method should adopt those container properties for its own appearance or behavior. It ignores inapplicable container properties, without generating an exception.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::AcquireContainingPartProperties

### CreateEmbeddedFramesIterator

This method creates an embedded-frames iterator to give callers access to all embedded frames of this part.

Signature

    ODEmbeddedFramesIterator *CreateEmbeddedFramesIterator (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame whose embedded frames the iterator traverses.

Returns

rv (ODEmbeddedFramesIterator *) - returns

  A reference to a new embedded-frames iterator object.

Remarks

Your part's CreateEmbeddedFramesIterator method should create, initialize, and return an embedded-frames iterator. Your part calls this method if it needs to apply an operation to all frames directly embedded within a display frame of another part. It is your responsibility to delete the iterator when it is no longer needed.

While you are using an embedded-frames iterator, you should not modify the list of embedded frames for the part. You must postpone adding items to or removing items from the list of embedded frames for the part until after you have deleted the iterator.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | This specified frame is not a display frame of this part.
kODErrOutOfMemory | There is not enough memory to allocate embedded-frames iterator object.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

### CreateLink

This method creates a link-source object for this part.

Signature

    ODLinkSource *CreateLink (ODByteArray *data)

Parameters

data (ODByteArray *) - input

  A byte array whose buffer contains the data of a link specification, created earlier by this part, that defines the content of the link source to be linked.

Returns

rv (ODLinkSource *) - returns

  A reference to a new link-source object to be used to represent the data.

Remarks

OpenDoc calls this method when the user decides to create a link when pasting in or dropping data that originated in this part. If a link already exists to the specified source content, this method should return the existing link-source object; otherwise, this method should create a new link-source object and copy the source content into it.

The data in a link specification is private to the part writing it. The data is only returned to this part when the CreateLink method actually creates a link-source object. If your part creates a link-source object, your part must maintain information about what portion of its content has been linked so that it may update the link-source object when the content data changes.

Before returning the link-source object, your part's CreateLink method should call the link-source object's Acquire method. When the caller has finished using the returned link-source object, it should call the link-source object's Release method.

Exception Handling

kODErrDoesNotLink | This part does not support linking.
kODErrOutOfMemory | There is not enough memory to allocate the link-source object.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### CreateRootMenuBar (OS/2)

This method creates a menu bar for a root frame to be used as a basis for the active frame's menu bar.

Signature

    ODMenuBar *CreateRootMenuBar (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A pointer to the root frame of the window for which the menu bar is to be created.

Returns

menuBar (ODMenuBar *) - returns

  The menu bar to be used as the base menu bar for this window.

  The value returned from the window-state object's CopyBaseMenuBar method should become the window's base menu bar.

  The caller of this method is responsible for releasing the menu bar when it has finished using it. If this method passes out several references to the same menu bar, this method increments the reference count of that menu-bar object for each reference after the first.

Exception Handling

kODErrOutOfMemory | There is not enough memory to allocate the menu bar.

### DisplayFrameAdded

This method should add the specified frame to this part's internal list of display frames.

Signature

    void DisplayFrameAdded (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame to be added.

Returns

None.

Remarks

OpenDoc calls this method only when a new display frame has been added to this part during frame object initialization.

Your part's DisplayFrameAdded method should perform any actions necessary to handle the addition of the specified frame to your part's internal list of display frames. Some actions depend on the nature and implementation of the part itself, but others are standard, such as adding the new frame to your part's internal list of display frames, verifying that you can support the frame's view type and presentation, and adding any needed part-information data to the frame.

Your part should not perform any layout or imaging tasks as a result of a display frame being added; it should wait until your part's FacetAdded method is called, at which time the frame becomes visible.

Your part's DisplayFrameAdded method is typically called after OpenDoc or this part's containing part calls a draft's CreateFrame method. By contrast, a part's DisplayFrameConnected method is called after OpenDoc or this part's containing part calls a draft's AcquireFrame method.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DisplayFrameConnected

### DisplayFrameClosed

This method should notify this part that one of its display frames has been closed.

Signature

    void DisplayFrameClosed (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame to be closed.

Returns

None.

Remarks

OpenDoc calls this method when this part's document or window closes.

Your part's DisplayFrameClosed method should update your part's internal list of display frames and other related structures to reflect the removal of the specified display frame from memory, and it should close any embedded frames. In addition, your method should call the arbitrator's RelinquishFocusSet method to relinquish any focuses owned by the display frame being closed.

Your part's DisplayFrameClosed method should not alter a part's stored list of displayed frames; it reflects the deletion of the instantiated frame object. By contrast, OpenDoc calls a part's DisplayFrameRemoved method to permanently remove one of the part's display frames.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DisplayFrameRemoved

### DisplayFrameConnected

This method should add the specified frame to this part's internal list of display frames.

Signature

    void DisplayFrameConnected (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame to be connected.

Returns

None.

Remarks

OpenDoc calls this method when a previously stored display frame is initialized and reconnected to this part. When this part's document opens, or as each display frame of this part becomes visible through scrolling or resizing, OpenDoc calls this method when it or this part's containing part instantiates and connects one of this part's previously stored display frames.

Your part's DisplayFrameConnected method should update your part's internal list of display frames and other related structures to reflect the connection of the specified display frame. If the specified frame is already in the list, no action is taken. Your part should also update relevant information in the display frame, for example, its used shape and presentation.

Your part's DisplayFrameConnected method is typically called after OpenDoc or this part's containing part calls a draft's AcquireFrame method. By contrast, a part's DisplayFrameAdded method is called after OpenDoc or this part's containing part calls a draft's CreateFrame method.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DisplayFrameAdded

### DisplayFrameRemoved

This method should remove the specified frame from this part's internal list of display frames.

Signature

    void DisplayFrameRemoved (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame to be removed.

Returns

None.

Remarks

To permanently delete one of its embedded frames, this part's containing part calls the embedded frame's Remove method. After removing the embedded frame, OpenDoc calls this method to notify this part of the removal.

Your part's DisplayFrameRemoved method should perform any actions necessary to remove a frame. For example, it should remove any frames (and part information) embedded within the specified frame. Your part's DisplayFrameRemoved method should update your part's internal list of display frames and other related structures to reflect the removal of the specified display frame. In addition, your method should call the arbitrator's RelinquishFocusSet method to relinquish any focuses owned by the display frame being removed.

By contrast, OpenDoc calls a part's DisplayFrameClosed method to clean up when the part's document or window closes.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DisplayFrameClosed

### DisposeActionState

This method dispose of the undo-action data.

Signature

    void DisposeActionState (ODActionData *actionState,
                             ODDoneState doneState)

Parameters

actionState (ODActionData *) - input

  A byte array whose buffer contains the data previously logged by this part to allow it to undo the action.

doneState (ODDoneState) - input

  The state of the undo action. This parameter can be set to one of the following values:

  kODDone | The actions was done and is now on the document's undo stack.
  kODRedone | The action was done, undone, and redone and is now on the document's undo stack.
  kODUndone | The action was done and undone and is now on the document's redo stack.

Returns

None.

Remarks

OpenDoc calls this method when it disposes of the undo-action data. After this method executes successfully, memory for the action state is reclaimed and is no longer usable for undo operations, effectively committing the action.

Exception Handling

kODErrDoesNotUndo | The specified action is not an undo action of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::RedoAction
- ODPart::WriteActionState

### DragEnter

This method begins tracking a drag operation.

Signature

    ODDragResult DragEnter (ODDragItemIterator *dragInfo,
                            ODFacet *facet,
                            ODPoint *where)

Parameters

dragInfo (ODDragItemIterator *) - input

  A reference to a drag-item iterator that can access the list of storage units of the dragged data.

facet (ODFacet *) - input

  A reference to a facet where the drag point is located.

where (ODPoint *) - input

  The location of the drag point, expressed in frame coordinates.

Returns

rv (ODDragResult) - returns

  A flag indicating whether this part can accept the dragged data in the given facet.

  kODTrue | This part can accept the dragged data.
  kODFalse | This part cannot accept the dragged data.

Remarks

OpenDoc calls this method when the drag point has entered the specified facet of this part during a drag operation. Before calling this method, OpenDoc calls the IsDroppable method of the facet's frame to ensure that this part is able to receive a drop.

Your part's DragEnter method should examine the part kinds of the dragged data (using the drag-item iterator specified by the dragInfo parameter), and determine whether it can accept the dragged data. Your part should not at this point attempt to read data from any of the storage units supplied by the drag-item iterator. If your part can accept a drop, it should provide the appropriate feedback to the user, such as displaying its drag border or changing the cursor appearance. If your part cannot handle the part kinds of the dragged data, it should take no action. If your part's DragEnter method returns kODFalse, OpenDoc assumes your part cannot accept a drop. OpenDoc will not make additional calls to your DragWithin and Drop methods as long as the mouse pointer remains in this facet.

Exception Handling

kODErrDoesNotDrop | This part does not support drag and drop.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DragLeave
- ODPart::DragWithin

### DragLeave

This method finishes tracking a drag operation and deactivates this part from the drag tracking.

Signature

    void DragLeave (ODFacet *facet,
                    ODPoint *where)

Parameters

facet (ODFacet *) - input

  A reference to a facet where the drag point is located.

where (ODPoint *) - input

  The location of the drag point, expressed in frame coordinates.

Returns

None.

Remarks

OpenDoc calls this method when the drag point has left the specified facet of this part during a drag operation. After this method executes successfully, the part is guaranteed not to receive DragWithin or Drop messages until you receive another DragEnter message.

Your part's DragLeave method should clean up after a drag operation. For example, you should remove the drag border on the frame, remove highlighting from any content highlighted during drag tracking, and change the cursor appearance back to its original form.

Exception Handling

kODErrDoesNotDrop | This part does not support drag and drop.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DragEnter
- ODPart::DragWithin

### DragWithin

This method tracks a drag operation and provides graphical feedback regarding possible drop targets.

Signature

    ODDragResult DragWithin (ODDragItemIterator *dragInfo,
                             ODFacet *facet,
                             ODPoint *where)

Parameters

dragInfo (ODDragItemIterator *) - input

  A reference to a drag-item iterator that can access the list of storage units of the dragged data.

facet (ODFacet *) - input

  A reference to a facet where the drag point is located.

where (ODPoint *) - input

  The location of the drag point, expressed in frame coordinates.

Returns

rv (ODDragResult) - returns

  A flag indicating whether this part can accept the dragged data in the given facet.

  kODTrue | This part can accept the dragged data in the given facet.
  kODFalse | This part cannot accept the dragged data in the given facet.

Remarks

Your part's DragWithin method allows your part to do any desired processing inside of its display frame. For example, if your part allows objects to be dropped only on individual hot spots, it may change its feedback based on mouse-pointer location. If the mouse is not over these hot spots, the cursor might need to be changed to reflect that no dropping can be done, even though the mouse is in a droppable frame. OpenDoc calls this method continuously when the drag point is within the borders of the specified facet's frame.

Your part's DragWithin method should examine the part kinds of the dragged data (using the drag-item iterator specified by the dragInfo parameter) and determine whether it can accept the dragged data. At this point, your part should not attempt to read data from any of the storage units supplied by the drag-item iterator. If your part can accept a drop, it should provide the appropriate feedback to the user, for example, by displaying its drag border or changing the cursor appearance. If your part cannot handle the part kinds of the dragged data, it should take no action. If your part's DragWithin method returns kODFalse, OpenDoc assumes you no longer wish to accept a drop in this facet. It will not make additional calls to your DragWithin or Drop methods as long as the mouse pointer remains in this facet.

Your part's DragWithin method also represents an opportunity for your part to examine the state of the machine. For example, some parts may want to know whether the modifier keys are down while a drag operation is in progress.

Exception Handling

kODErrDoesNotDrop | This part does not support drag and drop.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DragEnter
- ODPart::DragLeave

### Draw

This method should draw this part within the area that needs updating in the specified facet.

Signature

    void Draw (ODFacet *facet,
               ODShape *invalidShape)

Parameters

facet (ODFacet *) - input

  A reference to the facet in which this part is to draw.

invalidShape (ODShape *) - input

  A reference to a shape object defining the area of the facet that needs updating, expressed in frame coordinates.

Returns

None.

Remarks

OpenDoc calls this method when an update event occurs that involves a facet of this part. Your part's Draw method should make the actual platform-specific drawing calls.

Your part's Draw method should draw this part's content on the facet's canvas, updating the portion of the facet specified in the invalid shape. Your part must determine whether it should draw on the screen or to a printer, and then draw itself appropriately.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frames of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFacet::Draw
- ODFacet::Update
- ODWindow::Update

### Drop

This method moves or copies the dragged data in to this part.

Signature

    ODDropResult Drop (ODDragItemIterator *dropInfo,
                       ODFacet *facet,
                       ODPoint *where)

Parameters

dropInfo (ODDragItemIterator *) - input

  A reference to a drag-item iterator that describes the content, as well as the types and values, of the dragged data.

facet (ODFacet *) - input

  A reference to a facet where the drop has occurred.

where (ODPoint *) - input

  The location of the drop point, expressed in frame coordinates.

Returns

rv (ODDropResult) - returns

  This result is an ODDropResult value. See ODDropResult.

Remarks

The copy and move semantics are determined by examining the drag attributes and determining whether to display the Paste As dialog box. If a link is created, your part's Drop method should return kODDropCopy, regardless of the drag attribute.

OpenDoc calls this method when the mouse button is released while the drag point is within a facet that can accept a drop.

Your part's Drop method should examine the part kinds of the dragged data (using the drag-item iterator specified by the dropInfo parameter) and determine whether it can accept the dragged data. If your part can accept a drop, this method should incorporate or embed the dropped data and return an appropriate return value indicating the result of the drop operation. If your part cannot accept a drop, this method should return kODDropFail.

Exception Handling

kODErrDoesNotDrop | This part does not support drag and drop.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODDragAndDrop::GetDragAttributes (OS/2, Windows)
- ODDragAndDrop::ShowPasteAsDialog (OS/2, Windows)
- ODPart::DropCompleted

### DropCompleted

This method notifies this part that a drop operation, resulting from an asynchronous drag initiated from this part, is complete.

Signature

    void DropCompleted (ODPart *destPart,
                        ODDropResult dropResult)

Parameters

destPart (ODPart *) - input

  A reference to a part where the drop is to be completed.

dropResult (ODDropResult) - input

  The result of the drop operation. This result is an ODDropResult value. See ODDropResult.

Returns

None.

Remarks

OpenDoc calls this method to notify the source part of the drop result. This part should examine the drop result to determine how the source part's content should be updated.

Exception Handling

kODErrDoesNotDrop | This part does not support drag and drop.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODDragAndDrop::StartDrag
- ODPart::Drop

### EditInLinkAttempted

This method indicates whether this part maintains the destination of a link that includes the embedded frame.

Signature

    ODBoolean EditInLinkAttempted (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to an embedded frame, in which the edit was attempted, of this part.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this part maintains the destination of a link that includes the embedded frame.

  kODTrue | This part maintains the destination of a link that includes the embedded frame.
  kODFalse | This part does not maintain the destination of a link that includes the embedded frame.

Remarks

OpenDoc calls this method to notify this part that an attempt was made to edit content within a frame embedded in the destination of a link maintained by this part. The frame may be embedded at any depth within this part or its embedded parts.

Without making itself active, your part should display an alert box informing the user of the attempted edit to linked content and allow the user to find the source of the link or to break the link. If the user chooses to break the link, your part should change the link status of the embedded frame; the user can then retry the editing operation in the still-active frame.

Your part's EditInLinkAttempted method is not called by most parts. If your part's active frame is within a link destination and the user attempts to edit its content, you call the frame's EditInLink method instead of this method.

Exception Handling

kODErrDoesNotLink | This part does not support linking.

Override Policy

If you subclass ODPart, you can override this method if you support linking and embedding. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts that support linking.

Related Methods

- ODFrame::EditInLink

### EmbeddedFrameSpec

This method creates an object specifier for the specified embedded frame in this part.

Signature

    void EmbeddedFrameSpec (ODFrame *embeddedFrame,
                            ODObjectSpec *spec)

Parameters

embeddedFrame (ODFrame *) - input

  A reference to an embedded frame of this part.

spec (ODObjectSpec *) - input

  The object specifier for the frame.

Returns

None.

Remarks

An object specifier is a designation of a content object within a part. An object specifier is used to determine the target of a semantic event (a message sent to a part or one of its content elements). Object specifiers can be names (for example, "blue rectangle") or logical designations (such as "word 1 of line 2 of the embedded frame 3"). OpenDoc or parts can call this method to create an object specifier for an embedded frame to distinguish it from other frames.

If your part is an embedded part, this method should first obtain the specifier for your part's display frame by calling the EmbeddedFrameSpec method of your part's containing part and then concatenate that returned specifier with the object specifier for the specified embedded frame.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | The specified frame is not an embedded frame of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts that support scripting.

### EmbeddedFrameUpdated

This method updates any of this part's link-source objects that are affected by a change to the specified embedded frame.

Signature

    void EmbeddedFrameUpdated (ODFrame *frame,
                               ODUpdateID change)

Parameters

frame (ODFrame *) - input

  A reference to an embedded frame whose content has changed.

change (ODUpdateID) - input

  The updated ID associated with the frame.

Returns

None.

Remarks

An embedded frame's ContentUpdated method calls this method when its content changes. Your part's EmbeddedFrameUpdated method is called recursively for all containing parts in the frame hierarchy through the root part of the window displaying the embedded frame whose content has changed. This part is not responsible for notifying its containing part of the change. This part may ignore the notification if it is uninterested in changes in embedded content.

If the embedded frame is involved in a link source with your part, your part's EmbeddedFrameUpdated method should update the link-source object with the new data.

Your part's EmbeddedFrameUpdated method may be called multiple times with the same update ID. However, your part should wait a certain length of time (perhaps, a second) before updating its display so that subsequent calls to your method (with the same update ID) do not result in multiple updates for the same change.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.

Override Policy

If you subclass ODPart, you can override this method if you want your part to do something special in response to the EmbeddedFrameUpdated notification. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

Related Methods

- ODFrame::ContentUpdated

### ExternalizeKinds

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

Signature

    void ExternalizeKinds (ODTypeList *kindset)

Parameters

kindset (ODTypeList *) - input

  A reference to a type list specifying a set of part kinds.

Returns

None.

Remarks

OpenDoc calls this method. OpenDoc does not ensure that your part supports a subset of the part kinds in the specified kind list; you should write a representation for as many of the part kinds in the specified kind list that your part supports.

A part's ExternalizeKinds method does not specify anything about the ordering of those kinds in the content property of your part. Make sure that the ordering of the values in your contents property reflects your part editor's fidelity order.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### FacetAdded

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

Signature

    void FacetAdded (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to a facet that has been added.

Returns

None.

Remarks

OpenDoc calls this method when your part's containing part adds a facet to one of your part's display frames. If your part is the root part in a window, OpenDoc calls this method when the window is opened.

Your part's FacetAdded method should perform any actions necessary to handle the addition of the new facet to one of your part's display frames. Some actions depend on the nature and implementation of your part itself, but others are standard. Standard actions include creating facets for all visible embedded frames within the area of the added facet, storing appropriate part-information data in the facet, examining the facet's canvas to make sure your part editor understands how to draw on that canvas, and creating an offscreen canvas, if the facet needs one.

If your part does not support asynchronous display and is not a container part, it is not necessary for your part to do anything except possibly validate that it can draw to its canvas.

Note:

> On Windows, your part should ensure that the facet has a valid, non-null canvas before using the canvas when that canvas is from `facet->GetCanvas(ev)`. For example, the canvas must be valid before a call to the canvas' IsDynamic or IsOffscreen method.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::FacetAdded
- ODPart::FacetRemoved

### FacetRemoved

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

Signature

    void FacetRemoved (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to a facet that has been removed.

Returns

None.

Remarks

OpenDoc calls this method when your part's containing part removes a facet from one of your part's display frames. If your part is the root part in a window, OpenDoc also calls this method when the window is closed.

Your part's FacetRemoved method should perform any actions necessary to handle the removal of the facet. In general, the actions performed by this method should reverse those performed by the FacetAdded method. If your part does not support asynchronous display and is not a container part, its response to this call is minimal.

Exception Handling

kODErrInvalidFacet | The specified facet is not a facet of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::FacetRemoved
- ODPart::EmbeddedFrameSpec

### FocusAcquired

The method should notify this part that one of its display frames has acquired the specified focus.

Signature

    void FocusAcquired (ODTypeToken focus,
                        ODFrame *ownerFrame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be acquired.

  This parameter must be the tokenized form of a focus constants or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to an ODFocusType constant. For a list of ODFocusType constants, see ODFocusType.

ownerFrame (ODFrame *) - input

  A reference to the display frame that has acquired the focus.

Returns

None.

Remarks

OpenDoc calls this method to notify this part that the ownership of a focus has been transferred to it. For example, if a containing part uses the arbitrator's TransferFocus method to transfer a focus directly from one embedded part to another, the focus module calls the destination part's FocusAcquired method.

Your part's FocusAcquired method is not called when the part requests a focus or focus set using the arbitrator's RequestFocus and RequestFocusSet methods.

Your part's FocusAcquired method should perform any actions necessary to indicate that it has acquired the focus. For example, acquiring the selection focus might cause your part to highlight its selection.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::FocusLost
- ODSession::Tokenize

### FocusLost

The method should notify this part that one of its display frames has lost the specified focus.

Signature

    void FocusLost (ODTypeToken focus,
                    ODFrame *ownerFrame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type that was lost.

  This parameter must be the tokenized form of a focus constants or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to an ODFocusType constant. For a list of ODFocusType constants, see ODFocusType.

ownerFrame (ODFrame *) - input

  A reference to a display frame that has lost the focus.

Returns

None.

Remarks

OpenDoc calls this method to notify this part that the ownership of a focus has been unilaterally removed. For example, a focus module might detect that some physical hardware connection has been broken. Or if a containing part uses the arbitrator's TransferFocus method to transfer a focus directly from one embedded part to another, the focus module calls the source part's FocusLost method.

Your part's FocusLost method is not called when this part loses a focus because another part has requested it using the arbitrator's RequestFocus and RequestFocusSet methods. In this case, the part's CommitRelinquishFocus method is called if the part agrees to relinquish the focus.

Your part's FocusLost method should perform any actions necessary to indicate that it has lost the focus, for example, closing connections and removing highlighting. Your part should avoid inappropriate behavior after it has lost the focus. For example, your part should not attempt to adjust menus or display a menu bar when your part does not have the menu focus.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::AbortRelinquishFocus
- ODPart::BeginRelinquishFocus
- ODPart::CommitRelinquishFocus
- ODPart::FocusAcquired
- ODSession::Tokenize

### FrameShapeChanged

This method should notify this part that the frame shape of one of its display frames has changed.

Signature

    void FrameShapeChanged (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame that was reshaped.

Returns

None.

Remarks

OpenDoc calls this method when it or this part's containing part changes the frame shape of one of this part's display frames.

This part should perform any actions necessary to respond to the new shape. For example, your part should change its content layout, change its used shape, or resize its embedded frames.

Your part also has the option of requesting a different frame shape using its display frame's RequestFrameShape method, though it must be able to accept the shape it is given. If the size of the frame is insufficient, your part may ask its containing part for additional frames by calling its containing part's RequestEmbeddedFrame method.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::ChangeFrameShape
- ODPart::RequestEmbeddedFrame
- ODPart::RequestFrameShape

### FulfillPromise

This method fulfills a promise by providing the content data the promise represents.

Signature

    void FulfillPromise (ODStorageUnitView *promiseSUView)

Parameters

promiseSUView (ODStorageUnitView *) - input

  A reference to a storage-unit view object that contains the promise. This is the same value created by the storage unit's SetPromiseValue method.

Returns

None.

Remarks

A promise is a specification of data to be transferred at a future time. For data interchange using drag-and-drop or the clipboard, the part transferring data should usually delay the actual data transfer, instead providing a promise that is fulfilled only when the transfer is ultimately required.

If a data transfer involves a very large amount of data, your part can choose to put out a promise instead of actually writing the data to a storage unit. Your part's FulfillPromise method can then write the actual data only if and when a transfer to another part occurs. When cloning in the FulfillPromise method, the clone kind should be the same as the one used when the promise was written. OpenDoc calls this method when a promise must be fulfilled.

Exception Handling

kODErrNoPromises | This part did not make the promise.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODStorageUnit::SetPromiseValue

### GeometryChanged

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

Signature

    void GeometryChanged (ODFacet *facet,
                          ODBoolean clipShapeChanged,
                          ODBoolean externalTransformChanged)

Parameters

facet (ODFacet *) - input

  A reference to a facet with the changed geometry.

clipShapeChanged (ODBoolean) - input

  A flag indicating whether the clip shape has changed.

  kODTrue | The clip shape has changed.
  kODFalse | The clip shape has not changed.

externalTransformChanged (ODBoolean) - input

  A flag indicating whether the external transform has changed.

  kODTrue | The external transform has changed.
  kODFalse | The external transform has not changed.

Returns

None.

Remarks

OpenDoc calls this method when this part's facet changes its clip shape, external transform, or both, or when this part's facet is repositioned or clipped differently.

Your part's GeometryChanged method should use the new clip shape for display. If your part only displays in response to update events, it does not need to do anything but check the clip shape each time it draws. If your part supports asynchronous display (for example, clocks and movies), it must notice the new clip shape and limit its display accordingly.

Exception Handling

kODErrInvalidFacet | The specified facet is not a facet of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFacet::ChangeGeometry

### GetPrintResolution

This method should return the minimum desired resolution required for printing the content of the specified display frame.

Signature

    ODULong GetPrintResolution (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame for which the resolution is needed.

Returns

rv (ODULong) - returns

  The minimum desired resolution, expressed in dots per inch.

Remarks

The root part calls this method when creating the document's print job to guarantee that it can display the highest-resolution part.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### GetRealPart

This method returns a reference to a part object encapsulated by the part wrapper.

Signature

    ODPart *GetRealPart ()

Parameters

None.

Returns

rv (ODPart *) - returns

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

Remarks

Use of this method must conform to the following constraints:

- Only one client at a time may have access to the actual part Clients should not hold on to a reference to the actual part object for longer than absolutely necessary. Never store a reference to the part object and do not pass it as a parameter to other objects.

- Your part's GetRealPart method increments the reference count of the returned part. When you have finished using the actual part, you should call its ReleaseRealPart method. If another client attempts to get the actual part before the ReleaseRealPart method is called, an exception is generated.

Your part's GetRealPart method is almost never called unless you really need to access the actual part.

Exception Handling

kODErrPartNotWrapper | The method was called on an actual part, not a part wrapper.

Override Policy

If you subclass ODPart, you must not override this method.

Related Methods

- ODPart::IsRealPart
- ODPart::ReleaseRealPart

### HandleEvent

This method should attempt to handle the specified user event.

Signature

    ODBoolean HandleEvent (ODEventData *event,
                           ODFrame *frame,
                           ODFacet *facet,
                           ODEventInfo *eventInfo)

Parameters

event (ODEventData *) - in/out

  A platform-specific structure representing an event. On return, the fields of the structure may have been modified.

frame (ODFrame *) - input

  A reference to a display frame in which the event occurred.

facet (ODFacet *) - input

  A reference to a facet in which the event occurred or kODNULL for events not based on geometry (such as keyboard events) or events outside a modal focus.

eventInfo (ODEventInfo *) - in/out

  A platform-specific structure that contains additional event information. On return, the relative fields of the structure are filled in if the event was handled.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this part handled the event.

  kODTrue | This part handled the event.
  kODFalse | This part was not able to handle the event.

Remarks

OpenDoc calls this method to pass user events to this part.

If this part has set the doesPropagateEvents flag for any of its embedded frames (by calling the embedded frame's SetPropagateEvents method), this part then receives any event not handled by an embedded frame in addition to it own events.

Exception Handling

kODErrInvalidFacet | The specified facet is not a facet of this part.
kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::SetPropagateEvents

### HighlightChanged

This method should update the highlight state of the specified facet of this part.

Signature

    void HighlightChanged (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to a facet of the part.

Returns

None.

Remarks

OpenDoc calls this method when the highlight state of one of your part's facets changes. This allows your part to draw its content consistently with the content highlighting of your part's containing part.

Your part's HighlightChanged method should adjust your part's presentation in the facet to its new highlight state. The new state is found by calling the facet's GetHighlight method.

Exception Handling

kODErrInvalidFacet | The specified facet is not a facet of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFacet::ChangeHighlight
- ODFacet::GetHighlight

### InitPart

This method should initialize this part object.

Signature

    void InitPart (ODStorageUnit *storageUnit,
                   ODPart *partWrapper)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to the empty storage unit to be used by this part as its primary persistent storage.

partWrapper (ODPart *) - input

  A reference to the part wrapper representing this part.

Returns

None.

Remarks

OpenDoc calls this method only once for the persistent lifetime of this part, when it is first created and has no stored data to read. After this method executes successfully, this part object is initialized and ready for use.

Your part's InitPart method, rather than its somInit method, should handle any initialization code that can potentially fail. Your part's InitPart method may attempt to allocate extra memory for your part instance, get resources that your part might need, or set up your part's persistent storage.

The inherited InitPart method creates and stores the kODPropCreateDate, kODPropModDate, and kODPropModUser properties; your part's storage unit maintains the kODPropModDate and kODPropModUser properties.

Override Policy

If you subclass ODPart, you must override this method. Your override method must call its inherited method at the beginning of your implementation.

### InitPartFromStorage

This method should initialize this part object from its stored data.

Signature

    void InitPartFromStorage (ODStorageUnit *storageUnit,
                              ODPart *partWrapper)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to a specified storage unit from which this part should read its persistent state.

partWrapper (ODPart *) - input

  A reference to a part wrapper representing this part.

Returns

None.

Remarks

When a document containing this part is opened, or if this part is added to a document by means of data transfer, the part must be instantiated and read into memory. OpenDoc calls this method to initialize the runtime part object from persistent storage.

Your part's InitPartFromStorage method is similar to its InitPart method, except that it reads in data. OpenDoc passes a storage unit to your part, from which your part reads itself. Your part is responsible for reading the storage unit and preparing itself to receive other messages. Your part should retrieve, from its content property, the value that represents the data stream to be read.

Override Policy

If you subclass ODPart, you must override this method. Your override method must call its inherited method at the beginning of your implementation.

### IsRealPart

This method indicates whether this part is an actual part (as opposed to a part wrapper).

Signature

    ODBoolean isRealPart ()

Parameters

None.

Returns

isRealPart (ODBoolean) - returns

  A flag indicating whether this part is a part or part wrapper.

  kODTrue | This part is an actual part.
  kODFalse | This part is a part wrapper.

Remarks

Your part's IsRealPart method is almost never called unless you really need to access the actual part.

Override Policy

If you subclass ODPart, you must not override this method.

Related Methods

- ODPart::GetRealPart
- ODPart::ReleaseRealPart

### LinkBroken (OS/2)

This method is used by the Link Source pages of the Properties notebook to indicate that the use has broken a link from the link source end.

Signature

    void LinkBroken (ODLink *link)

Parameters

None.

Returns

link (ODLink *) - returns

  The link object to break a link with.

Returns

None.

Remarks

There is no default action in this method except to raise an exception kODErrSubClassResponsibility.

Exception Handling

kODErrSubClassResponsibility | The subclass must override this method.

Override Policy

If you subclass ODPart, you must override this method. Your override method must perform any part-specific cleanup and should call the link's Release method.

### LinkStatusChanged

This method should notify this part that the link status of one of its display frames has changed.

Signature

    void LinkStatusChanged (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame whose link status has changed.

Returns

None.

Remarks

OpenDoc calls this method. Your part's LinkStatusChanged method should call the ChangeLinkStatus method of each embedded frame affected by the display frame change, assigning it the same link status as the display frame.

If the value kODNotInLink was assigned in the ChangeLinkStatus method, your part's LinkStatusChanged method can still get the status of this part's display frame (its containing frame).

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::ChangeLinkStatus

### LinkUpdated

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

Signature

    void LinkUpdated (ODLink *updatedLink,
                      ODUpdateID change)

Parameters

updatedLink (ODLink *) - input

  A reference to a link that has changed.

change (ODUpdateID) - input

  The update ID associated with the link; an identifier for a particular version of link-source data.

Returns

None.

Remarks

Each link object maintains a registry of dependent parts. If this part is registered as a dependent of the link source (by having called the link's RegisterDependent method), OpenDoc calls this method when the link destination object changes.

Your part's LinkUpdated method should retrieve the data from the link, and incorporate or embed that data into your part at the link's destination, thereby replacing any previous content of the link.

It is no a mandate to update link destinations immediately. For example, if the destination is scrolled offscreen but is registered as a dependent of the link, updating is not required until the destination scrolls back into view. A part editor can perform link updating as a background task.

Exception Handling

kODErrDoesNotLink | The specified link is not a link of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODLink::RegisterDependent

### Open

This method should create or activate a window in which a frame of this part is the root frame.

Signature

    ODID Open (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a frame that is being opened into a window or kODNULL if the frame does not exist.

Returns

rv (ODID) - returns

  The ID associated with the window.

Remarks

Your part is responsible for creating windows in which it is the root part, even when OpenDoc is opening a saved draft. Your part's Open method is called in these circumstances:

- When this part is initially created from a stationery document, OpenDoc calls this method and passes kODNULL for the frame parameter. There is no previously stored frame or window information

- When this part is an embedded part whose frame is selected, and the user chooses the Open Selection command from the Document menu, this part's containing part calls this part's Open method and passes a reference to the selected frame in the frame parameter.

- When this part is the root part of a document being opened, OpenDoc calls this method and passes a reference to the root frame in the frame parameter. The root frame is annotated with a storage unit containing window information; if the root frame has no window information, this part should instead open a default window.

For more information on opening windows, see the chapter on windows and menus in the OpenDoc Programming Guide.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODWindowState::Internalize

### PresentationChanged

This method should notify this part that the presentation of one of its display frames has changed.

Signature

    void PresentationChanged (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame for this part.

Returns

None.

Remarks

OpenDoc calls this method when this part's display frame changes its presentation.

Your part's PresentationChanged method should examine the new presentation using its frame's GetPresentation method. It should then display itself in the specified display frame according to the indicated presentation. If your part does not support the requested presentation, it should instead pick a presentation that it can support and then call its frame's SetPresentation method to update the presentation in the frame.

Exception Handling

kODErrInvalidFrame | The specified frame is a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::ChangePresentation
- ODFrame::SetPresentation

### ReadActionState

This method reads the undo action data from the specified storage-unit view object.

Signature

    ODActionData ReadActionState (ODStorageUnitView *storageUnitView)

Parameters

storageUnitView (ODStorageUnitView *) - input

  A reference to a storage-unit view object that contains the action data.

Returns

rv (ODActionData) - returns

  A byte array whose buffer contains the data previously logged by this part to allow it to undo the action.

Remarks

OpenDoc calls this method when it reads the undo action data from persistent storage. Your part's ReadActionState method will not be called in OpenDoc 1.0 due to the lack of a persistent undo model; it is provided here for compatibility with future versions of OpenDoc.

Exception Handling

kODErrDoesNotUndo | The specified action is not an undo action of this part.
kODErrOutOfMemory | There is not enough memory to read the data.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DisposeActionState
- ODPart::WriteActionState

### ReadPartInfo

This method should read the part-information data for a display frame of this part from the specified storage-unit view object.

Signature

    ODInfoType ReadPartInfo (ODFrame *frame,
                             ODStorageUnitView *storageUnitView)

Parameters

frame (ODFrame *) - input

  A reference to a display frame for this part.

storageUnitView (ODStorageUnitView *) - input

  A reference to a storage-unit view object that is focused to the frame's part-information property, but not to any value within that property.

Returns

rv (ODInfoType) - returns

  The information stored in the frame's part information.

Remarks

When a document is reopened, OpenDoc may ask this part to read a display frame's part-information data from a particular storage unit back into memory. OpenDoc calls this method when it reads in the part-information data for a display frame of this part.

Your part's ReadPartInfo method should get the storage unit associated with the specified storage-unit view and focus it to the values in the frame's part-information property as necessary to read in the formats it needs.

Your part's ReadPartInfo method should read the data from the storage unit and place it in a block of memory, if necessary. (Your part must first allocate the block of memory.) In simple cases, part-information data could be simple data, such as an integer, which does not require a block of memory. Your part's ReadPartInfo method should then return the memory block to the frame for storage so that your part can access it later.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.
kODErrOutOfMemory | There is not enough memory to allocate the part-information data.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::ClonePartInfo
- ODPart::WritePartInfo

### RedoAction

This method redoes the specified action.

Signature

    void RedoAction (ODActionData *actionState)

Parameters

actionState (ODActionData *) - input

  A byte array whose buffer contains the data previously logged by this part to allow it to redo the action.

Returns

None.

Remarks

A part may need to give the user the capability of repeating the effects of recently undone commands. OpenDoc calls this method when the user chooses to redo an action of this part.

Your part is responsible for notifying the clipboard when a cut, copy, or paste operation is done, undone, or redone. If your part's RedoAction method is called, it should remove the object from its content model and notify the clipboard that the cut was redone.

Exception Handling

kODErrDoesNotUndo | The specified action is not an undo action of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::UndoAction

### ReleaseRealPart

This method releases the part object encapsulated by the part wrapper.

Signature

    void ReleaseRealPart ()

Parameters

Returns

None.

Remarks

For part wrappers, this method marks the part object as available for access by another client. Your part's ReleaseRealPart method is almost never called unless you really need to access the actual part.

Exception Handling

kODErrPartNotWrapper | This method was called on an actual part, not a part wrapper.

Override Policy

If you subclass ODPart, you must not override this method.

Related Methods

- ODPart::GetRealPart
- ODPart::IsRealPart

### RemoveEmbeddedFrame

This method removes the specified embedded frame from this part's content.

Signature

    void RemoveEmbeddedFrame (ODFrame *embeddedFrame)

Parameters

embeddedFrame (ODFrame *) - input

  A reference to a embedded frame of this part.

Returns

None.

Remarks

An embedded part calls this part's RemoveEmbeddedFrame method when it no longer wants to display itself in the specified frame.

If your part supports embedding, your part's RemoveEmbeddedFrame method should respond to a request to remove an embedded frame. Your part's RemoveEmbeddedFrame method should remove only frames that were added by calls to your part's RequestEmbeddedFrame method.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | The specified frame is not an embedded frame of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

Related Methods

- ODPart::RequestEmbeddedFrame

### RequestEmbeddedFrame

This method should create a new display frame for the specified embedded part.

Signature

    ODFrame *RequestEmbeddedFrame (ODFrame *containingFrame,
                                   ODFrame *baseFrame,
                                   ODShape *frameShape,
                                   ODPart *embedPart,
                                   ODTypeToken viewType,
                                   ODTypeToken presentation,
                                   ODBoolean isOverlaid)

Parameters

containingFrame (ODFrame *) - input

  A reference to a display frame in which to embed the new frame.

baseFrame (ODFrame *) - input

  A reference to a sibling frame of the frame to be created, and also a display frame for the embedded part.

frameShape (ODShape *) - input

  A reference to a requested shape for the new frame, expressed in frame coordinates of the containing frame.

embedPart (ODPart *) - input

  A reference to a part that is to be displayed in the new frame.

viewType (ODTypeToken) - input

  A tokenized string representing the view type to be assigned to this part's frame.

  This parameter must be the tokenized form of one of the following view-type constants. You can call the session object's Tokenize method to obtain a token corresponding to one of these constants.

  kODViewAsFrame | Framed view type.
  kODViewAsLargeIcon | Large-icon (standard) view type.
  kODViewAsSmallIcon | Small-icon view type.
  kODViewAsThumbNail | Thumbnail view type

presentation (ODTypeToken) - input

  A tokenized string representing the presentation to be assigned to this part's frame.

isOverlaid (ODBoolean) - input

  A flag indicating whether this part's frame is to be an overlaid frame.

  kODTrue | The part's frame is to be an overlaid frame.
  kODFalse | The part's frame is not to be an overlaid frame.

Returns

rv (ODFrame *) - returns

  A reference to a new frame object.

Remarks

An embedded part calls its containing part's RequestEmbeddedFrame method when it needs an extra frame to flow content into, for example, an additional column or additional page of text. The part must specify one of its current display frames as a base frame; the new frame is a sibling of the base frame, and it is in the same group as the base frame.

If your part supports embedding, it may need to respond to a request to add an embedded frame. Your part's RequestEmbeddedFrame method should call your draft's CreateFrame method to create the new frame and then return it to the embedded part.

Before returning the frame object, your part's RequestEmbeddedFrame method should call the frame object's Acquire method. When the caller has finished using the returned frame object, it should call the frame object's Release method.

For more information on frame negotiation, see the layout and embedding chapter in the OpenDoc Programming Guide.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | The specified sibling frame is not an embedded frame of this part.
kODErrOutOfMemory | There is not enough memory to embed a part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only be container parts.

Related Methods

- ODDraft::CreateFrame
- ODSession::Tokenize

### RequestFrameShape

This method negotiates a new frame shape for the specified frame embedded in this part.

Signature

    ODShape *RequestFrameShape (ODFrame *embeddedFrame,
                                ODShape *frameShape)

Parameters

embeddedFrame (ODFrame *) - input

  A reference to an embedded frame for which the frame-shape change is requested.

frameShape (ODShape *) - input

  A reference to a requested shape, expressed in the frame coordinates of the embedded frame.

Returns

rv (ODShape *) - returns

  A reference to a new shape for the embedded frame, expressed in frame coordinates.

Remarks

OpenDoc calls this method to initiate a frame negotiation process requested by this part's embedded part.

Your part's RequestFrameShape method should decide what new shape to give an embedded frame, using the requested frame shape as a guideline, and return a reference to the shape object it allows the embedded frame to have. The embedded frame stores the shape as its new frame shape and returns the shape to its part so that its part knows what its new shape is. The embedded part must accept the returned shape, although it may make further requests for different shapes or additional frames.

Before returning the shape object, your part's RequestFrameShape method should call the shape object's Acquire method. When the caller has finished using the returned shape object, it should call the shape object's Release method.

For more information on frame negotiation, see chapter on the layout and embedding in the OpenDoc Programming Guide.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

Related Methods

- ODFrame::RequestFrameShape

### RevealFrame

This method makes the specified embedded frame visible by scrolling it into view.

Signature

    ODBoolean RevealFrame (ODFrame *embeddedFrame,
                           ODShape *revealShape)

Parameters

embeddedFrame (ODFrame *) - input

  A reference to an embedded frame of this part.

revealShape (ODShape *) - input

  A reference to a shape object, expressed in frame coordinates, that indicates the portion of the frame to be revealed.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this part was able to reveal the frame.

  kODTrue | This part was able to reveal the frame.
  kODFalse | This part was not able to reveal the frame.

Remarks

An embedded part calls this part's RevealFrame method when it needs to become visible, such as in conjunction with a keyboard event which requires an undisplayed area of a window to scroll into view.

Your part's RevealFrame method should scroll one of your part's display frames, if necessary, to make the specified embedded frame visible. If your part has no visible display frames, it should ask its containing part to reveal one of them. If your part has no display frames, or if your part's containing frame cannot reveal the display frame, your method should open a frame in a new window.

Exception Handling

kODErrCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | The specified frame is not an embedded frame of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

Related Methods

- ODFrame::AcquireFrameShape

### RevealLink

This method shows the content at the source of a link.

Signature

    void RevealLink (ODLinkSource *linkSource)

Parameters

linkSource (ODLinkSource *) - input

  A reference to a link-source object representing the linked content to be revealed.

Returns

None.

Remarks

OpenDoc calls this method when a link source needs to be shown; this method is not called by parts.

Your part's RevealLink method should select the linked content to be revealed in one of its frames, scroll the frame into view using its containing part's RevealFrame method, and make that frame active. If your part has no visible display frames, or if your part's containing frame cannot reveal the display frame, your method should open a frame in a new window.

Exception Handling

kODErrDoesNotLink | The specified link is not a link of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::RevealFrame

### SequenceChanged

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

Signature

    void SequenceChanged (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame whose sequence has been reordered.

Returns

None.

Remarks

OpenDoc calls this method when this part's containing part adds a new frame to the group or reorders the frames in the group. The containing part calls its embedded frame's ChangeSequenceNumber method to initiate the change.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::ChangeSequenceNumber

### ShowLink (OS/2)

This method is used by the Link page of the Properties notebook to indicate that the user requests the part to show the link.

Signature

    void ShowLink (ODLink *link)

Parameters

link (ODLink *) - input

  The link object to be shown.

Returns

None.

Remarks

There is no default action in this method except to raise an exception kODErrSubClassResponsibility.

Exception Handling

kODErrSubClassResponsibility. | The subclass must override this method.

Override Policy

If you subclass ODPart, you must override this method.

### UndoAction

This method undoes the specified action.

Signature

    void UndoAction (ODActionData *actionState)

Parameters

actionState (ODActionData *) - input

  A byte array whose buffer contains the data previously logged by this part to allow it to undo the action.

Returns

None.

Remarks

OpenDoc calls this method when the user chooses to undo an action of this part.

Your part may need to give the user the capability of reversing the effects of recently executed commands. If it does, your part's UndoAction method should perform any reverse editing necessary to restore itself to the state it possessed before the specified action.

Your part is responsible for notifying the clipboard when a cut, copy, or paste operation is done, undone, or redone. When a part cuts an object to the clipboard, a reference to the object should be saved in an undo action. If your part's UndoAction method is called, it should reinstate the object into its content model from its undo information and notify the clipboard that the cut was undone.

Exception Handling

kODErrDoesNotUndo | The specified action is not an undo action of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::RedoAction

### UpdateFromLinkSource (OS/2)

This method is used by the Link Source page of the Properties notebook to indicate that the user requested the part to update the link source. As a side-effect, the registered links also get updated.

Signature

    void UpdateFromLinkSource (ODLinkSource *linkSource)

Parameters

linkSource (ODLinkSource *) - input

  The link source object whose links are to be updated.

Returns

None.

Remarks

There is no default action in this method except to raise an exception kODErrSubClassResponsibility.

Exception Handling

kODErrSubClassResponsibility | The subclass must override this method.

Override Policy

If you subclass ODPart, you must override this method.

### UsedShapeChanged

This method notifies this part that the used shape of one of its embedded frames has changed.

Signature

    void UsedShapeChanged (ODFrame *embeddedFrame)

Parameters

embeddedFrame (ODFrame *) - input

  A reference to an embedded frame of this part.

Returns

None.

Remarks

OpenDoc calls this method when a frame embedded in this part changes its used shape. Containing parts that have wrapped their content to the contour of an embedded frame's used shape (as in text wrapping) need to adjust the layout of that content for the new used shape.

Exception Handling

kODCannotEmbed | This part does not support embedding.
kODErrInvalidFrame | The specified frame is not an embedded frame of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function. This method needs to be implemented only by container parts.

Related Methods

- ODFrame::ChangeUsedShape

### ViewTypeChanged

This method should notify this part that the view type of one of its display frames has changed.

Signature

    void ViewTypeChanged (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to a display frame for this part.

Returns

None.

Remarks

OpenDoc calls this method when this part's display frame changes its view type.

Your part's ViewTypeChanged method should examine the new view type using its frame's GetViewType method. It should then display itself in the specified display frame according to the indicated view type. If your part does not support the requested view type, it should instead pick a view type that it can support and then call its frame's SetViewType method to update the view type in the frame.

Exception Handling

kODErrInvalidFrame | The specified frame is not a display frame of this part.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODFrame::GetViewType
- ODFrame::SetViewType

### WriteActionState

This method writes the undo action data into the specified storage-unit view object.

Signature

    void WriteActionState (ODActionData *actionState,
                           ODStorageUnitView *storageUnitView)

Parameters

actionState (ODActionData *) - input

  A byte array whose buffer contains the data previously logged by this part to allow it to redo the action.

storageUnitView (ODStorageUnitView *) - input

  A reference to a storage-unit view object where the action data is to be written to storage.

Returns

None.

Remarks

OpenDoc calls this method when it writes the undo action data to persistent storage. Your part's WriteActionState method will not be called in OpenDoc 1.0 due to the lack of a persistent undo model; it is provided here for compatibility with future versions of OpenDoc.

Exception Handling

kODErrDoesNotUndo | The specified action is not an undo action of this part.

Override Policy

If you subclass ODPart, you can override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::DisposeActionState
- ODPart::ReadActionState

### WritePartInfo

This method should write the part-information data for a display frame of this part into the specified storage-unit view object.

Signature

    void WritePartInfo (ODInfoType partInfo,
                        ODStorageUnitView *storageUnitView)

Parameters

partInfo (ODInfoType) - input

  The part-information data to write.

storageUnitView (ODStorageUnitView *) - input

  A reference to a storage-unit view object that is focused to the frame's part-information property, but not to any value within that property.

Returns

None.

Remarks

When a document is saved (using the Save command from the Document menu), OpenDoc may ask this part to save a display frame's part-information data to a particular storage unit. OpenDoc calls this method when it writes out the part-information data for a display frame of a part.

Your part's WritePartInfo method should get the storage unit associated with the specified storage-unit view and focus it to the values in the frame's part-information property as necessary to write the formats it needs.

Override Policy

If you subclass ODPart, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::ClonePartInfo
- ODPart::ReadPartInfo

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]