Programming Reference: ODFrame

# Programming Reference

## ODFrame

Class definition file | Frame.idl
Class C++ Binding | Frame.xh

Class hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODPersistentObject
                ODFrame

Description

An object of the ODFrame class describes the display area of an embedded part in the content of its containing part.

A frame object represents an area of content of a part; it marks the geometric boundary between an embedded part and its containing part. There are several possible configurations and states for frames:

Active frame | A frame that has the selection focus. Editing takes place in the active frame; that frame displays the selection or insertion point.
Bundled frame | A frame whose content does not respond to geometry-based user events. A mouse click within a bundled frame selects the frame's part, but does not activate it.
Containing frame | A frame in which one or more frames are embedded. Each embedded frame has one containing frame; each containing frame has one or more embedded frames.
Display frame | A frame within which the part's content is drawn. Each display frame represents a particular view of a part's content.
Embedded frame | A frame within which one of the part's embedded parts is displayed.
Nonpersistent frame | A frame that exists only as an in-memory object. A nonpersistent frame does not have a storage unit and is not stored persistently.
Overlaid frame | An embedded frame that floats above a containing part's content (including other embedded frames). Overlaid frames do not need to negotiate for space except as required by the constraints of the containing part size.
Root frame | A frame in which the root part of a window is displayed. The root frame shape is the same as the content area of the window.
Subframe | A frame that is both an embedded frame in, and a display frame of, a part. A part can create an embedded frame, make it a subframe of its own display frame, and then display itself in that subframe. When a subframe has the selection focus, the active frame border is displayed around its containing frame.

Your part creates a new frame object for its embedded parts by calling its draft's CreateFrame method. Your part accesses a previously stored frame object by calling its draft's AcquireFrame method. These methods return a reference to a frame object.

Frame Geometry

There are several things that define the geometry of a frame.

Content extent | This describes how much offset is used to calculate the bias transform. The bias transform is the vertical extent of the content area of a part in a frame (in essence, the height of a part's page). For more information related to bias transforms, see the class description of the ODCanvas.
Frame shape | This defines the area that the containing part propagates to an embedded part's display frame. The frame's containing part controls the frame shape.
Internal transform | This describes how the part's content is positioned, scaled, or otherwise transformed within the frame. It represents the mapping from the coordinate space of the frame's content to the coordinate space of the frame.
Used shape | This defines the area of an embedded part's frame that has actual content to display. The actual content is the part of the frame that the containing part should not draw over. However, the containing part is free to wrap content to the contour of the used shape. The embedded part controls the used shape.

A frame must have a valid frame shape. The used shape does not need to be set; if it is not, the used shape is the same as the frame shape. For more information related to shape objects, see the class description of ODShape.

A frame must have a valid internal transform which, if not explicitly set, is the identity transform. For more information related to transform objects, see the class description of ODTransform.

The ODFrame class includes several methods that specify geometry (shape and transform) objects. Because these objects necessarily assume a coordinate system, the ODFrame methods include a biasCanvas parameter that allows you to specify a canvas to whose coordinate space the geometry is biased. The bias canvas uses a bias transform to convert from the coordinate system used for drawing on the canvas to the coordinate system (platform-normal coordinates) used by the current graphics system. When the bias canvas is specified, it is applied to the returned object.

Each part in an OpenDoc document controls the position, size, and shape of the frames embedded within it. At the same time, embedded parts may want to change the size, shape, or number of frames they are displayed in. Through a process called frame negotiation, an embedded part and its containing part agree on the frames the part displays in. Each part can initiate the negotiation, although the containing part has unilateral control over the outcome.

Frame Hierarchy

A frame must maintain a reference to its part. The frame ensures that it is registered with its part on that part's internal list of display frames when the frame is created (by calling its part's DisplayFrameAdded method) and that it is removed from that part's internal list of display frames when the frame is deleted (by calling its part's DisplayFrameRemoved method).

A frame maintains a reference to its containing frame. The value of the reference is null if the specified frame is the root frame of a window. The reference value does not usually change, unless the frame was create before an embedding location was selected. A frame does not hold direct references to its embedded frames. Only the frame's part knows which frames are embedded in the frame.

A frame maintains a list of its facets. Facets hold nonpersistent information about the layout of parts, or describe the location of a frame on a particular canvas for display and event dispatching. There may be more than one facet per frame. This list may be empty if the specified frame is scrolled out of view or otherwise not visible. For more information related to facet objects, see the class description for ODFacet.

Displaying Information

There are two characteristics that describe how a part is displayed within a frame.

- The view type describes the basic visual representation of a part. Parts must support the standard set of view types (large icon, small icon, thumbnail, or frame view). The view type should be set only by the frame's part.

- The presentation of a frame describes, for parts whose view type is framed, a particular style of display for a part's content within the frame, for example, a table, bar chart, pie chart, text, or outline. Presentations are part-defined; your part editor determines what types of presentations your part is capable of and defines a presentation designation for each. A containing part may request a particular presentation but the embedded part does not need to honor that request. The presentation should be set only by the frame's part.

A frame's part might store user-defined data in the frame's part information. The part alone interprets or manipulates the data, but the part-information data is stored with the frame and read in only when it is necessary for frame manipulation.

Propagating Events

If one of your part's embedded frames propagates unhandled events to your part, your part has the opportunity to handle those events. In that case, your part's event handler needs to determine if a particular frame is one of its display frames or an embedded frame.

Frame Groups

A frame group is a set of display frames that a part designates as related, for purposes such as flowing content from one frame to another. Each frame group has its own group ID; frames within a frame group have a sequence number that is used to define the position of a frame within its frame group. The group ID and sequence number should be set only by the frame's containing part.

Flags and Link Status

When a part creates a frame, the part sets flags, defined for the lifetime of the frame, that determine whether the frame is a root frame, a subframe, or an overlaid frame; once set, these flags cannot be changed.

A containing part must set the link status for any frame it embeds, even if the embedded part does not support links to its content. The containing part specifies a link status value based solely on the embedded frame's inclusion in links maintained by the containing part. A frame considers the link status of its containing frame when setting its own link status.

Methods

The methods defined for the ODFrame class include:

- AcquireContainingFrame
- AcquireFrameShape
- AcquireInternalTransform
- AcquirePart
- AcquireUsedShape
- AcquireWindow
- ChangeContentExtent
- ChangeFrameShape
- ChangeInternalTransform
- ChangeLinkStatus
- ChangePart
- ChangePresentation
- ChangeSequenceNumber
- ChangeUsedShape
- ChangeViewType
- Close
- ContentUpdated
- CreateFacetIterator
- CreateShape
- CreateTransform
- DoesPropagateEvents
- DrawActiveBorder
- EditInLink
- FacetAdded
- FacetRemoved
- GetContentExtent
- GetFrameGroup
- GetLinkStatus
- GetPartInfo
- GetPresentation
- GetSequenceNumber
- GetViewType
- Invalidate
- InvalidateActiveBorder
- IsDragging
- IsDroppable
- IsFrozen
- IsInLimbo
- IsOverlaid
- IsRoot
- IsSubframe
- Remove
- RequestFrameShape
- SetContainingFrame
- SetDragging
- SetDroppable
- SetFrameGroup
- SetFrozen
- SetInLimbo
- SetPartInfo
- SetPresentation
- SetPropagateEvents
- SetSubframe
- SetViewType
- SetWindow
- Validate

Overridden methods | There are no methods overridden by the ODFrame class.

### AcquireContainingFrame

This method returns a reference to the containing frame of this frame.

Signature

    ODFrame *AcquireContainingFrame ()

Parameters

None.

Returns

rv (ODFrame *) - returns

  A reference to the containing frame of this frame or kODNULL if this frame is a root frame.

Remarks

This method increments the reference count of the returned frame. When you have finished using that frame object, you should call its Release method.

Related Methods

- ODFrame::SetContainingFrame

### AcquireFrameShape

This method returns a reference to the frame shape of this frame.

Signature

    ODShape *AcquireFrameShape (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

rv (ODShape *) - returns

  A reference to the frame shape, expressed in frame coordinates.

Remarks

The caller must not modify the returned shape. Only the frame's containing part can modify the frame shape.

This method increments the reference count of the returned shape object. When you have finished using that shape object, you should call its Release method.

Related Methods

- ODFrame::ChangeFrameShape
- ODFrame::RequestFrameShape

### AcquireInternalTransform

This method returns a reference to an internal transform of this frame.

Signature

    ODTransform *AcquireInternalTransform (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

rv (ODTransform *) - returns

  A reference to the internal transform of this frame.

Remarks

The caller must not modify the internal transform. Only this frame's part can modify the internal transform.

This method increments the reference count of the returned transform object. When you have finished using that transform object, you should call its Release method.

Related Methods

- ODFrame::ChangeInternalTransform

### AcquirePart

This method returns a reference to a part displayed in this frame.

Signature

    ODPart *AcquirePart ()

Parameters

None.

Returns

rv (ODPart *) - returns

  A reference to a part displayed in this frame.

Remarks

This method increments the reference count of the returned part object. When you have finished using that part object, you should call its Release method.

Related Methods

- ODFrame::ChangePart

### AcquireUsedShape

This method returns a reference to the used shape of this frame.

Signature

    ODShape *AcquireUsedShape (ODCanvas *biasCanvas)

Parameters

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

rv (ODShape *) - returns

  A reference to the used shape of this frame, expressed in frame coordinates.

Remarks

The caller must not modify the used shape. Only the frame's part can modify the used shape.

This method increments the reference count of the returned shape object. When you have finished using that shape object, you should call its Release method.

Related Methods

- ODFrame::ChangeUsedShape

### AcquireWindow

This method returns a reference to the window in which this frame is displayed.

Signature

    ODWindow *AcquireWindow ()

Parameters

None.

Returns

rv (ODWindow *) - returns

  A reference to the window in which this frame is displayed or kODNULL if this frame does not actually appear in any window (for example, a printing frame does not appear in a window).

Remarks

Only the root frame of a window has a reference to the window; all its embedded frames then inherit this value.

This method increments the reference count of the returned window object. When you have finished using that window object, you should call its Release method.

Related Methods

- ODFacet::GetWindow
- ODFrame::SetWindow

### ChangeContentExtent

This method changes the content extent of this frame.

Signature

    void ChangeContentExtent (ODPoint *contentExtent)

Parameters

contentExtent (ODPoint *) - input

  The content extent to be assigned to this frame.

Returns

None.

Remarks

The content extent is, in essence, the page height of the part displayed in this frame. This method causes the bias transform associated with this frame's content to be recomputed.

Related Methods

- ODFrame::GetContentExtent

### ChangeFrameShape

This method changes the frame shape of this frame.

Signature

    void ChangeFrameShape (ODShape *shape,
                           ODCanvas *biasCanvas)

Parameters

shape (ODShape *) - input

  A reference to a frame shape to be assigned to this frame, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

None.

Remarks

Your part calls its embedded frame's ChangeFrameShape method when it changes the shape of the embedded frame. This method in turn calls the FrameShapeChanged method of the embedded frame's part to notify the part that its frame shape has changed.

If the used shape is the same as the frame shape, this method also calls the UsedShapeChanged method of the embedded frame's part to notify the part that its used shape has changed.

Exception Handling

kODErrIllegalNullShapeInput | The shape parameter is null.

Related Methods

- ODFrame::AcquireFrameShape
- ODFrame::RequestFrameShape
- ODPart::FrameShapeChanged
- ODPart::UsedShapeChanged

### ChangeInternalTransform

This method changes the internal transform of this frame.

Signature

    void ChangeInternalTransform (ODTransform *transform,
                                  ODCanvas *biasCanvas)

Parameters

transform (ODTransform *) - input

  A reference to a internal transform to be associated with this frame.

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

None.

Remarks

Your part calls its display frame's ChangeInternalTransform method to change the position of its content in the frame.

Exception Handling

kODErrIllegalNullTransformInput | The transform parameter is null.

Related Methods

- ODFrame::AcquireInternalTransform

### ChangeLinkStatus

This method changes the link status of this frame.

Signature

    void ChangeLinkStatus (ODLinkStatus status)

Parameters

status (ODLinkStatus) - input

  The link status to be assigned to this frame. For a list of ODLinkStatus constants, see ODLinkStatus.

Returns

None.

Remarks

If your part supports linking or embedding, your part calls this method for each embedded frame that is involved in a link when a link is created, broken or moved. If your part supports linking, your part calls this method for each frame not in a link. This method in turn calls the LinkStatusChanged method associated with this frame's part to notify the part that its link status has changed. In turn, the embedded part's LinkStatusChanged method gives that embedded part a chance to call the ChangeLinkStatus method for other embedded frames.

Exception Handling

kODErrNotInLink | The specified link status is invalid.

Related Methods

- ODFrame::GetLinkStatus
- ODPart::LinkStatusChanged

### ChangePart

This method assigns a new part to this frame.

Signature

    void ChangePart (ODPart *part)

Parameters

part (ODPart *) - input

  A reference to a part to be associated with this frame.

Returns

None.

Remarks

Your part calls this method when it wants to keep one embedded frame and swap parts in and out of it, as is typical for browser-type parts. This method in turn calls the FacetRemoved method associated with this frame's part to remove all facets of this frame from its previous part. This method can also call the FacetAdded method associated with this frame's new part to add all facets associated with the previous part.

Unless this frame was removed or closed, you can assume this frame once had a part.

Exception Handling

kODErrIllegalNullPartInput | The part parameter is null.

Related Methods

- ODPart::FacetAdded
- ODPart::FacetRemoved

### ChangePresentation

This method changes the presentation of this frame.

Signature

    void ChangePresentation (ODTypeToken presentation)

Parameters

presentation (ODTypeToken) - input

  A tokenized string representing the presentation to be assigned to this frame. The presentation values are determined by the part developer. They must be tokenized to ensure they are unique. Non-unique or null values are invalid.

Returns

None.

Remarks

Your part calls its embedded frame's ChangePresentation method to request that it use a new presentation. This method in turn calls the PresentationChanged method of this frame's part to notify the part that its presentation has changed. If the embedded part does not support the requested presentation, it can pick a presentation that it can support and then call its frame's SetPresentation method to update the presentation in the frame.

Exception Handling

kODErrIllegalNullTokenInput | The presentation parameter is null.

Related Methods

- ODFrame::GetPresentation
- ODFrame::SetPresentation
- ODPart::PresentationChanged

### ChangeSequenceNumber

This method assigns a sequence number to this frame in its frame group.

Signature

    void ChangeSequenceNumber (ODULong sequenceNumber)

Parameters

sequenceNumber (ODULong) - input

  The sequence number to be assigned to this frame.

Returns

None.

Remarks

Your part calls its embedded frame's ChangeSequenceNumber method to reorder the sequence of its display frames in its frame group.

Related Methods

- ODFrame::GetSequenceNumber

### ChangeUsedShape

This method assigns a used shape to this frame.

Signature

    void ChangeUsedShape (ODShape *shape,
                          ODCanvas *biasCanvas)

Parameters

shape (ODShape *) - input

  A reference to a used shape to be assigned to this frame, expressed in frame coordinates, or kODNULL if the used shape is the same as the frame shape.

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

None.

Remarks

Your part assigns a used shape to its display frame by calling the frame's ChangeUsedShape method. This method in turn calls the UsedShapeChanged method of the display frame's containing part to notify the containing part that its used shape has changed. OpenDoc sets the drawing region based on the used shape. You cannot draw outside of this region.

Related Methods

- ODFrame::AcquireUsedShape
- ODPart::UsedShapeChanged

### ChangeViewType

This method changes the specified view type of this frame.

Signature

    void ChangeViewType (ODTypeToken viewType)

Parameters

viewType (ODTypeToken) - input

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

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

  kODViewAsFrame | Frame view type.
  kODViewAsLargeIcon | Large-icon (standard) view type.
  kODViewAsSmallIcon | Small-icon view type.
  kODViewAsThumbnail | Thumbnail view type.

Returns

None.

Remarks

Your part calls its embedded frame's ChangeViewType method to request that it use a new view type. This method in turn calls the ViewTypeChanged method of this frame's part to notify the part that its view type has changed. If the embedded part does not support the requested view type, it can 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

kODErrIllegalNullTokenInput | The viewType parameter is null.

Related Methods

- ODFrame::GetViewType
- ODFrame::SetViewType
- ODPart::ViewTypeChanged
- ODSession::Tokenize

### Close

This method prepares this frame to be removed from memory but does not affect persistent storage.

Signature

    void Close ()

Parameters

None.

Returns

None.

Remarks

Your part calls its embedded frame's Close method when a document is being closed after its final save. This method in turn calls the DisplayFrameClosed method associated with this frame's part to notify the part that it is being closed.

During execution of this method, this frame releases its references to the associated part and its containing frame, and this frame should not be used again.

Depending on whether you want to affect persistent storage, your part calls this method or its frame's Remove method.

Related Methods

- ODFrame::Remove
- ODPart::DisplayFrameClosed

### ContentUpdated

This method notifies this frame's containing part that this frame's part has updated its content, so the containing part can update any link sources that it maintains.

Signature

    void ContentUpdated (ODUpdateID change)

Parameters

change (ODUpdateID) - input

  The update ID associated with this frame.

Returns

None.

Remarks

Your part calls its display frame's ContentUpdated method when your part's content changes. Your part should avoid calling this method at every content change; it generally calls this method after a reasonable pause and when the part loses the selection focus. This method may be called multiple times. This method in turn calls the EmbeddedFrameUpdated method for all containing parts in the frame hierarchy through the root part of the window, so that any affected link source can be updated.

Related Methods

- ODPart::EmbeddedFrameUpdated

### CreateFacetIterator

This method creates a frame-facet iterator object for the facets of this frame.

Signature

    ODFrameFacetIterator *CreateFacetIterator ()

Parameters

None.

Returns

rv (ODFrameFacetIterator *) - returns

  A reference to a new frame-facet iterator object.

Remarks

Your part calls this method if it needs to apply an operation to all facets of one of your display frames, such as drawing and changing their shapes. It is your responsibility to delete the iterator when it is no longer needed.

While you are using a frame-facet iterator, you should not modify the list of facets for the frame. You must postpone adding items to or removing items from the list of facets for the frame until after you have deleted the iterator.

Related Methods

- ODFacet::CreateFacetIterator

### CreateShape

This method creates a shape object.

Signature

    ODShape *CreateShape ()

Parameters

None.

Returns

rv (ODShape *) - returns

  A reference to a new shape object.

Remarks

Your part calls this method to create a shape object for any purpose.

This method initializes the reference count of the returned shape object. When you have finished using that shape object, you should call its Release method.

Related Methods

- ODFacet::CreateShape

### CreateTransform

This method creates a transform object.

Signature

    ODTransform *CreateTransform ()

Parameters

None.

Returns

rv (ODTransform *) - returns

  A reference to a new transform object.

Remarks

Your part calls this method to create a transform object for any purpose.

This method initializes the reference count of the returned transform object. When you have finished using that transform object, you should call its Release method.

Related Methods

- ODFacet::CreateTransform

### DoesPropagateEvents

This method indicates whether this frame propagates unhandled events to its containing part.

Signature

    ODBoolean DoesPropagateEvents ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame propagates unhandled events to its containing part.

  kODTrue | This frame propagates unhandled events to its containing part.
  kODFalse | This frame does not propagate unhandled events to its containing part.

Remarks

If one of your part's embedded frames propagates unhandled events to your part, your part has the opportunity to handle those events. In that case, your part's event handler needs to determine if a particular frame is one of its display frames or an embedded frame.

Related Methods

- ODFrame::SetPropagateEvents

### DrawActiveBorder

This method updates the active frame border of this frame.

Signature

    void DrawActiveBorder ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method. This method in turn calls the DrawActiveBorder method associated with each facet of this frame.

Related Methods

- ODFacet::DrawActiveBorder
- ODFrame::InvalidateActiveBorder

### EditInLink

This method indicates whether the part maintaining a link destination that includes this frame can be found.

Signature

    ODBoolean EditInLink ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the part maintaining the link destination that includes this frame can be found.

  kODTrue | The part maintaining the link destination can be found.
  kODFalse | The part maintaining the link destination cannot be found.

Remarks

Your part calls this method when the user attempts to edit in a display frame which has link status of kODInLinkDestination. This method in turn calls the EditInLinkAttempted method of the part that maintains that link destination. The part then displays an alert allowing the user to find the source of the link or to break the link. If the user chooses to break the link, that part changes the link status of the embedded frame accordingly.

If the part maintaining the link destination was found, this method returns kODTrue, and if the link status of this frame was changed, you can then allow editing. In the unlikely event that the part maintaining the link destination cannot be found, this method returns kODFalse, and your part should display an alert informing the user that the destination of the link cannot be edited.

Related Methods

- ODPart::EditInLinkAttempted

### FacetAdded

This method adds the facet to this frame's list of facets and notifies its part of the new facet.

Signature

    void FacetAdded (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to a facet to be added.

Returns

None.

Remarks

OpenDoc calls this method when a facet is added to this frame. This method in turn calls the FacetAdded method associated with this frame's part to notify the part that a facet has been added to one of its display frames.

Related Methods

- ODFrame::FacetRemoved
- ODPart::FacetAdded

### FacetRemoved

This method removes the facet from this frame's list of facets and notifies its part of the deletion.

Signature

    void FacetRemoved (ODFacet *facet)

Parameters

facet (ODFacet *) - input

  A reference to a facet to be removed.

Returns

None.

Remarks

OpenDoc calls this method when a facet is removed. This method in turn calls the FacetRemoved method associated with this frame's part to notify the part that a facet has been removed from one of its display frames.

Related Methods

- ODFacet::RemoveFacet
- ODFrame::FacetAdded
- ODPart::FacetRemoved

### GetContentExtent

This method retrieves the content extent of this frame.

Signature

    void GetContentExtent (ODPoint *contentExtent)

Parameters

contentExtent (ODPoint *) - output

  The content extent of this frame.

Returns

None.

Remarks

The content extent is, in essence, the page height of the part displayed in this frame.

Related Methods

- ODFrame::ChangeContentExtent

### GetFrameGroup

This method returns the group ID of this frame.

Signature

    ODULong GetFrameGroup ()

Parameters

None.

Returns

rv (ODULong) - returns

  The group ID of this frame.

Related Methods

- ODFrame::SetFrameGroup

### GetLinkStatus

This method returns the link status of this frame.

Signature

    ODLinkStatus GetLinkStatus ()

Parameters

None.

Returns

rv (ODLinkStatus) - returns

  The link status of this frame. For a list of ODLinkStatus constants, see ODLinkStatus.

Remarks Your part calls its display frame's GetLinkStatus method to determine if it should allow links to be created to or from the content displayed by this frame. For example, if the link status is kODInLinkDestination, a link should not be created within this frame.

Related Methods

- ODFrame::ChangeLinkStatus

### GetPartInfo

This method returns the part-information data for this frame.

Signature

    ODInfoType GetPartInfo ()

Parameters

None.

Returns

rv (ODInfoType) - returns

  The part-information data for this frame.

Remarks

Your part calls its display frame's GetPartInfo method to retrieve any part-specific information it has stored there.

You should cast the return value to a pointer to your part's own representation of the data.

Related Methods

- ODFacet::GetPartInfo
- ODFrame::SetPartInfo

### GetPresentation

This method returns the presentation of this frame.

Signature

    ODTypeToken GetPresentation ()

Parameters

None.

Returns

rv (ODTypeToken) - returns

  A tokenized string representing this frame's presentation.

Related Methods

- ODFrame::ChangePresentation
- ODFrame::SetPresentation

### GetSequenceNumber

This method returns the sequence number of this frame in its frame group.

Signature

    ODULong GetSequenceNumber ()

Parameters

None.

Returns

rv (ODULong) - returns

  The sequence number of this frame.

Related Methods

- ODFrame::ChangeSequenceNumber

### GetViewType

This method returns the view type of this frame.

Signature

    ODTypeToken GetViewType ()

Parameters

None.

Returns

rv (ODTypeToken) - returns

  A tokenized string representing the view type of this frame.

  This parameter must be the tokenized form off 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 | Frame view type.
  kODViewAsLargeIcon | Large-icon (standard) view type.
  kODViewAsSmallIcon | Small-icon view type.
  kODViewAsThumbnail | Thumbnail view type.

Related Methods

- ODFrame::ChangeViewType
- ODFrame::SetViewType
- ODSession::Tokenize

### Invalidate

This method marks the specified area in this frame as in need of updating.

Signature

    void Invalidate (ODShape *invalidShape,
                     ODCanvas *biasCanvas)

Parameters

invalidShape (ODShape *) - input

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

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

None.

Remarks

Your part calls this method to explicitly invalidate a portion of its display frame. This method in turn calls the Invalidate method associated with each of this frame's facets. The resulting invalid shape is transformed and clipped to the coordinate space of each facet's canvas.

Related Methods

- ODCanvas::Invalidate
- ODFacet::Invalidate
- ODFrame::Validate

### InvalidateActiveBorder

This method marks the active frame border of this frame as in need of updating.

Signature

    void InvalidateActiveBorder ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method. This method in turn calls the InvalidateActiveBorder method of each facet of this frame.

Related Methods

- ODFacet::InvalidateActiveBorder
- ODFrame::DrawActiveBorder

### IsDragging

This method indicates whether this frame is being dragged.

Signature

    ODBoolean IsDragging ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicting whether this frame is being dragged.

  kODTrue | This frame is being dragged.
  kODFalse | This frame is not being dragged.

Remarks

OpenDoc calls this method to determine whether parts can be dropped onto this frame.

Related Methods

- ODFrame::IsDroppable
- ODFrame::SetDragging
- ODFrame::SetDroppable

### IsDroppable

This method indicates whether this frame's part accepts drag-and-drop events in this frame.

Signature

    ODBoolean IsDroppable ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame's part accepts drag-and-drop events in this frame.

  kODTrue | This frame's part accepts drag-and-drop events in this frame.
  kODFalse | This frame's part does not accept drag-and-drop events in this frame.

Remarks

OpenDoc calls this method before calling your part's DragEnter method to ensure that your part's display frame is able to receive a drop.

Related Methods

- ODFrame::IsDragging
- ODFrame::SetDragging
- ODFrame::SetDroppable

### IsFrozen

This method indicates whether this frame is bundled.

Signature

    ODBoolean IsFrozen ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame is bundled.

  kODTrue | This frame is bundled.
  kODFalse | This frame is not bundled.

Related Methods

- ODFrame::SetFrozen

### IsInLimbo

This method indicates whether this frame was removed from a part's content model.

Signature

    ODBoolean IsInLimbo ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame was removed from a part's content model.

  kODTrue | This frame was removed from a part's content model.
  kODFalse | This frame was in a part's content model (such as an embedded frame).

Remarks

Your part calls this method to check whether the frame is in limbo.

The in-limbo flag is not a persistent property of frames; frames that are in limbo are eventually removed. When a frame object is created by a draft, the frame is not in limbo. If this frame was removed from a part's content model, such as by the cut operation, this frame is in limbo, and eventually this frame is removed from the draft by the part that last contained the frame in its content model. If this frame is inserted into a part's content model, such as by a paste or undo of the cut operation, this frame is again not in limbo.

Related Methods

- ODFrame::SetInLimbo

### IsOverlaid

This method indicates whether this frame is an overlaid frame.

Signature

    ODBoolean IsOverlaid ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame is an overlaid frame.

  kODTrue | This frame is an overlaid frame.
  kODFalse | This frame is not an overlaid frame.

Remarks

This method's return value is defined for the lifetime of this frame; once set, it cannot be changed.

Related Methods

- ODFrame::IsRoot
- ODFrame::IsSubframe

### IsRoot

This method indicates whether this frame is the root frame.

Signature

    ODBoolean IsRoot ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame is the root frame.

  kODTrue | This frame is the root frame.
  kODFalse | This frame is not the root frame.

Remarks

This method's return value is defined for the lifetime of this frame; once set, it cannot be changed.

Related Methods

- ODFrame::IsSubframe
- ODFrame::IsOverlaid

### IsSubframe

This method indicates whether this frame is a subframe of its containing frame.

Signature

    ODBoolean IsSubframe ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this frame is a subframe of its containing frame.

  kODTrue | This frame is a subframe of its containing frame.
  kODFalse | This frame is not a subframe of its containing frame.

Related Methods

- ODFrame::IsRoot
- ODFrame::SetSubframe

### Remove

This method prepares this frame to be removed from both memory and persistent storage.

Signature

    void Remove ()

Parameters

None.

Returns

None.

Remarks

Your part calls its embedded frames' Remove method when it permanently removes the frame from its content. This method in turn calls the DisplayFrameRemoved method of this frame's part to notify the part that this frame is being removed. During the execution of the DisplayFrameRemoved method, this frame's part calls its embedded frames' Remove method recursively.

During execution of this method, this frame releases its references to the associated part and its containing frame, and this frame should not be used again. After this method executes successfully, you do not need to call your part's Release method.

Depending on whether you want to affect persistent storage, your part calls this method or its frame's Close method.

Related Methods

- ODFrame::Close
- ODPart::DisplayFrameRemoved

### RequestFrameShape

This method requests a new frame shape for this frame.

Signature

    ODShape *RequestFrameShape (ODShape *shape,
                                ODCanvas *biasCanvas)

Parameters

shape (ODShape *) - input

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

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

rv (ODShape *) - returns

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

Remarks

Your part calls its display frame's RequestFrameShape method when it wants to resize the display frame. This method in turn calls the RequestFrameShape method of this frame's containing part. The containing part returns a reference to the shape object it allows the display frame to have. This frame stores the shape as its new frame shape and returns the shape to your part so that your part knows what the new shape is.

Your part must not modify the returned shape. Only this frame's containing part can modify the frame shape.

This method increments the reference count of the returned shape object. When you have finished using that shape object, you should call its Release method.

Exception Handling

kODErrIllegalNullShapeInput | The shape parameter is null.

Related Methods

- ODFrame::ChangeFrameShape
- ODFrame::AcquireFrameShape
- ODPart::RequestFrameShape

### SetContainingFrame

This method assigns the specified frame as the containing frame of this frame.

Signature

    void SetContainingFrame (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to the frame to be assigned as this frame's containing frame.

Returns

None.

Remarks

You should remove any frame facets before calling this method. Call this method only when a frame is moved, because the frame is created with the correct containing frame.

Related Methods

- ODFrame::AcquireContainingFrame

### SetDragging

This method specifies whether this frame is being dragged.

Signature

    void SetDragging (ODBoolean isDragging)

Parameters

isDragging (ODBoolean) - input

  A flag indicating whether this frame is being dragged.

  kODTrue | This frame is being dragged.
  kODFalse | This frame is not being dragged.

Returns

None.

Remarks

Your part calls this method to indicate whether parts can be dropped on to this frame.

Related Methods

- ODFrame::IsDragging
- ODFrame::IsDroppable
- ODFrame::SetDroppable

### SetDroppable

This method specifies whether this frame's part accepts drag-and-drop events in this frame.

Signature

    void SetDroppable (ODBoolean isDroppable)

Parameters

isDroppable (ODBoolean) - input

  A flag indicating whether this frame's part accepts drag-and-drop events in this frame.

  kODTrue | This frame's part accepts drag-and-drop events in this frame.
  kODFalse | This frame's part does not accept drag-and-drop events in this frame.

Returns

None.

Remarks

Your part calls this method to define its display frame as capable or incapable of accepting a drop.

Related Methods

- ODFrame::IsDragging
- ODFrame::IsDroppable
- ODFrame::SetDragging

### SetFrameGroup

This method assigns a group ID to this frame.

Signature

    void SetFrameGroup (ODULong groupID)

Parameters

groupID (ODULong) - input

  The group ID to be assigned to this frame.

Returns

None.

Remarks

Your part calls its embedded frame's SetFrameGroup method to change its group ID.

Related Methods

- ODFrame::GetFrameGroup

### SetFrozen

This method specifies whether this frame is bundled.

Signature

    void SetFrozen (ODBoolean isFrozen)

Parameters

isFrozen (ODBoolean) - input

  A flag indicating whether this frame is bundled.

  kODTrue | This frame is bundled.
  kODFalse | This frame is not bundled.

Returns

None.

Remarks

Your part calls this method for any embedded frame or display frame.

Related Methods

- ODFrame::IsFrozen

### SetInLimbo

This method specifies whether this frame is to be removed from a part's content model.

Signature

    void SetInLimbo (ODBoolean isInLimbo)

Parameters

isInLimbo (ODBoolean) - input

  A flag indicating whether this frame is to be removed from a part's content model.

  kODTrue | This frame is to be removed from a part's content model.
  kODFalse | This frame is in a part's content model (for example, an embedded frame).

Returns

None.

Remarks

Your part calls this method to specify whether this frame is in limbo.

The in-limbo flag is not a persistent property of frames; frames that are in limbo are eventually removed. If the frame is in limbo, this frame is removed from the draft by the part that last contained the frame in its content model. This method does not need to recursively set the flag of embedded frames.

Related Methods

- ODFrame::IsInLimbo

### SetPartInfo

This method assigns part-information data to this frame.

Signature

    void SetPartInfo (ODInfoType partInfo)

Parameters

partInfo (ODInfoType) - input

  The part-information data to be assigned to this frame.

Returns

None.

Remarks

Your part calls its display frame's SetPartInfo method.

Related Methods

- ODFacet::SetPartInfo
- ODFrame::GetPartInfo

### SetPresentation

This method assigns the specified presentation to this frame.

Signature

    void SetPresentation (ODTypeToken presentation)

Parameters

presentation (ODTypeToken) - input

  A tokenized string representing the presentation to be assigned to this frame. The presentation values are determined by the part developer. They must be tokenized to ensure they are unique. Non-unique or null values are invalid.

Returns

None.

Remarks

Your part calls its display frame's SetPresentation method.

Exception Handling

kODErrIllegalNullTokenInput | The presentation parameter is null.

Related Methods

- ODFrame::ChangePresentation
- ODFrame::GetPresentation

### SetPropagateEvents

This method specifies whether this frame should propagate unhandled events to its containing frame.

Signature

    void SetPropagateEvents (ODBoolean doesPropagateEvents)

Parameters

doesPropagateEvents (ODBoolean) - input

  A flag indicating whether this frame should propagate unhandled events to its containing frame.

  kODTrue | This frame should propagate unhandled events to its containing frame.
  kODFalse | This frame should not propagate unhandled events to its containing frame.

Returns

None.

Remarks

Your part calls its embedded frame's SetPropagateEvents method to indicate whether it wants to receive events not handled by the embedded frame.

Related Methods

- ODFrame::DoesPropagateEvents

### SetSubframe

This method specifies whether this frame is a subframe of its containing frame.

Signature

    void SetSubframe (ODBoolean isSubframe)

Parameters

isSubframe (ODBoolean) - input

  A flag indicating whether this frame is a subframe of a containing frame.

  kODTrue | This frame is a subframe of a containing frame.
  kODFalse | This frame is not a subframe of a containing frame.

Returns

None.

Related Methods

- ODFrame::IsSubframe

### SetViewType

This method assigns the specified view type to this frame.

Signature

    void SetViewType (ODTypeToken viewType)

Parameters

viewType (ODTypeToken) - input

  A tokenized string representing the view type to be assigned to this 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 | Frame view type.
  kODViewAsLargeIcon | Large-icon (standard) view type.
  kODViewAsSmallIcon | Small-icon view type.
  kODViewAsThumbnail | Thumbnail view type.

Returns

None.

Remarks

Your part calls its display frame's SetViewType method.

Exception Handling

kODErrIllegalNullTokenInput | The viewType parameter is null.

Related Methods

- ODFrame::ChangeViewType
- ODFrame::GetViewType
- ODSession::Tokenize

### SetWindow

This method assigns a window to this frame.

Signature

    void SetWindow (ODWindow *window)

Parameters

window (ODWindow *) - input

  A reference to the window to be assigned to this frame.

Returns

None.

Remarks

OpenDoc calls this method when it creates this frame as its root frame. Only the root frame of a window has a reference to the window; all its embedded frames inherit this value.

Exception Handling

kODErrNotRootFrame | The specified frame is not a root frame of this part.

Related Methods

- ODFrame::AcquireWindow

### Validate

This method marks the specified area in this frame as no longer in need of updating.

Signature

    void Validate (ODShape *validShape,
                   ODCanvas *biasCanvas)

Parameters

validShape (ODShape *) - input

  A reference to the shape object defining the area in this frame that no longer needs updating, expressed in frame coordinates.

biasCanvas (ODCanvas *) - input

  A reference to the canvas object to whose coordinate space the geometry is biased or kODNULL if the geometry is in platform-normal coordinates.

Returns

None.

Remarks

Your part calls this method to explicitly mark portions of its display frame that do not need updating. This method in turn calls the Validate method associated with each of this frame's facets. The Validate method transforms and clips the shape from the coordinate space of the facet to the coordinate space of its canvas and subtracts the shape from any existing invalid area of the canvas.

Related Methods

- ODCanvas::Invalidate
- ODFacet::Validate
- ODFrame::Invalidate

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