Programming Reference: ODDraft

# Programming Reference

## ODDraft

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

Class Hierarchy

    SOMObject
       ODObject
          ODRefCntObject
             ODDraft

Description

An object of the ODDraft class represents a particular version of a document object.

The ODDraft class is implemented differently for different platforms and storage mechanisms.

The set of related classes, ODContainer, ODDocument, ODDraft, and ODStorageUnit, is called a container suite. Container suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with one another at many levels.

An OpenDoc document can contain one or more drafts, and each draft can contain one or more storage units. Each document, draft, and storage unit has a unique ID. If a storage unit is used to store data for a persistent object, the storage unit's ID is also used as the ID of the persistent object.

Because each draft corresponds to a version of its document, a document can be defined as a collection of version-drafts. The document shell or container application creates or accesses a draft of a document by calling the CreateDraft, AcquireDraft, and AcquireBaseDraft methods of that document.

Each draft has permissions that control access to it. Drafts are created with exclusive read and write permissions. The document shell or container application can change a draft's permissions when it calls the document's AcquireDraft and AcquireBaseDraft methods. Access to a draft is guaranteed to be exclusive only if the draft has exclusive read and write permissions. Many methods of ODDraft require a particular kind of access to the draft; for example, the CreateFrame method requires write access. Before calling one of these methods, you should call the draft's GetPermissions method and check that the draft's current permissions allow the required access.

Drafts are linearly derived in a document. The drafts of a document can be thought of as a stack; the oldest draft, called the base draft, is at the bottom of the stack and the most recent is at the top. Although part editors can access any draft of a document, only the most recent (topmost) draft can be modified; all earlier drafts are readonly.

The ODDraft class has a set of CreateClass and AcquireClass methods for creating and retrieving persistent objects for various classes: parts, frames, link objects, and link-source objects. For example, the CreateFrame method creates a new frame object matching the specifications you provide; the AcquireFrame method recreates the ODFrame object stored in the specified storage unit.

Many OpenDoc methods modify the content of a draft, and therefore, the draft must be notified so that it can save these changes. If this draft contains no changes since it was last saved, it is said to be clean; if it contains changes, it is said to be dirty. For example, after a successful call to the CreateFrame method, the draft is dirty. You can call the SetChangedFromPrev method when your part's content has changed; that method marks the draft as dirty so that content changes will be saved.

You can copy or clone the persistent objects in a draft into a specified storage unit. All cloning must be performed within a transaction; the Bento container suite allows only one cloning transaction at any given time.

- To initiate a cloning transaction, call the draft's BeginClone method. This method returns a unique draft key that identifies the transaction.

- To copy a persistent object, call the draft's Clone method, passing as parameters the draft key returned by the BeginClone method, the ID of the object to be cloned, the ID of the destination storage unit, and the ID of the frame object specifying the scope of the cloning operation.

  The draft's Clone method calls the CloneInto method of the object being cloned. If that object has persistent references, it clones any referenced objects within the specified scope. Objects referenced by strong persistent references are strongly cloned by recursive calls to the Clone method; objects referenced by weak persistent references are weakly cloned by calls to the WeakClone method.

- To commit the cloning transaction, call the draft's EndClone method. Until the EndClone method has successfully executed, there is no guarantee that all the objects have been copied.

- To terminate the transaction unsuccessfully, call the draft's AbortClone method. You should call this method if the cloning operation cannot be completed for any reason.

For more information on how ODDraft and other container-suite classes are used, see the chapters on storage and OpenDoc runtime features in the OpenDoc Programming Guide.

Methods

The methods defined by the ODDraft class include:

- AbortClone
- AcquireDraftProperties
- AcquireFrame
- AcquireLink
- AcquireLinkSource
- AcquirePart
- AcquirePersistentObject
- AcquireStorageUnit
- BeginClone
- ChangedFromPrev
- Clone
- CreateFrame
- CreateLinkSource
- CreateLinkSpec
- CreatePart
- CreateStorageUnit
- EndClone
- Externalize
- GetDocument
- GetID
- GetPermissions
- GetPersistentObjectID
- IsValidID
- ReleasePart
- RemoveChanges
- RemoveFrame
- RemoveFromDocument
- RemoveFromDocument
- RemoveLinkSource
- RemovePart
- RemoveStorageUnit
- SaveToAPrevious
- SetChangedFromPrev
- WeakClone

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

### AbortClone

This method aborts the specified cloning transaction.

Signature

    void AbortClone (ODDraftKey key)

Parameters

key (ODDraftKey) - input

  The draft key of the cloning transaction to be aborted.

Returns

None.

Remarks

You call this method if a cloning transaction cannot be completed for any reason. The key parameter must be set to the draft key value returned by the call to the BeginClone method that started the cloning transaction.

Exception Handling

kODErrInvalidDraftKey | The specified draft key is not the draft key for the current cloning transaction.

Related Methods

- ODDraft::BeginClone
- ODDraft::Clone
- ODDraft::EndClone

### AcquireDraftProperties

This method returns a reference to the storage unit in which this draft stores its properties and data that are global to this draft.

Signature

    ODStorageUnit *AcquireDraftProperties ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to the draft-properties storage unit of this draft.

Remarks

The draft stores information about itself in its draft-properties storage unit. In addition, your part may create properties in this storage unit to store information related to this draft.

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

Exception Handling

kODErrNoDraftProperties | A draft-properties storage unit cannot be created.

### AcquireFrame

This method returns a reference to the frame whose data is stored in the specified storage unit.

Signature

    ODFrame *AcquireFrame (ODStorageUnitID id)

Parameters

id (ODStorageUnitID) - input

  The storage-unit ID for the target frame.

Returns

rv (ODFrame *) - returns

  A reference to the specified frame object.

Remarks

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

Exception Handling

kODErrCannotAcquireFrame | The target frame object cannot be accessed.
kODErrInvalidID | The id parameter is invalid.

Related Methods

- ODDraft::Clone

### AcquireLink

This method returns a reference to the link object whose data is stored in the specified storage unit or that can be constructed from the given link specification.

Signature

    ODLink *AcquireLink (ODStorageUnitID id,
                         ODLinkSpec *linkSpec)

Parameters

id (ODStorageUnitID) - input

  The ID of the storage unit providing the link data or kODNULLID if the link is to be constructed.

linkSpec (ODLinkSpec *) - input

  A reference to a link-specification object from which the link is to be constructed or kODNULL if the id parameter is not null.

Returns

rv (ODLink *) - returns

  A reference to the specified link object.

Remarks

If your part is the destination of a link, you call this method to create a link object; you also call this method in your part's InitPartFromStorage method to recreate the link object from its stored data.

If the id parameter is not null, the linkSpec parameter is ignored. In this case, the id parameter must be the ID of the link object's storage unit, and this method recreates the link object from the content of the specified storage unit.

If the id parameter is null, the linkSpec parameter must be a link-specification object returned by a previous call to the CreateLinkSpec method. In this case, this method uses the information in the link-specification object to construct the link object.

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

Exception Handling

kODErrCannotAcquireLink | The requested link object cannot be recreated from the specified storage unit or link-specification object.
kODErrInvalidID | No link object was specified; the id parameter is kODNULLID, and the linkSpec parameter is kODNULL.

Related Methods

- ODDraft::CreateLinkSpec
- ODPart::InitPartFromStorage

### AcquireLinkSource

This method returns a reference to the link-source object whose data is stored in the specified storage unit.

Signature

    ODLinkSource *AcquireLinkSource (ODStorageUnitID id)

Parameters

id (ODStorageUnitID) - input

  The ID of the storage unit for the target link.

Returns

rv (ODLinkSource *) - returns

  A reference to the specified link-source object.

Remarks

If you part is the source of a link, you can call this method in your part's InitPartFromStorage method to recreate a link-source object from its stored data.

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

Exception Handling

kODErrCannotAcquireLink | The companion link object does not exist and cannot be created.
kODErrInvalidID | The id parameter was invalid.

Related Methods

- ODDraft::CreateLinkSource
- ODPart::InitPartFromStorage

### AcquirePart

This method returns a reference to the part whose data is stored in the specified storage unit.

Signature

    ODPart *AcquirePart (ODStorageUnitID id)

Parameters

id (ODStorageUnitID) - input

  The storage-unit ID for the target part.

Returns

rv (ODPart *) - returns

  A reference to the specified part object.

Remarks

You call this method to recreate a part object from its stored data.

If a part with the indicated ID does not exist, this method calls the binding object to attempt to construct a new part. If this attempt fails, AcquirePart returns kODNULL. After this method executes successfully, the return value is a fully functional part object with a reference count greater than or equal to 1.

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.

Exception Handling

kODErrInvalidID | The id parameter is invalid.

Related Methods

- ODDraft::CreatePart

### AcquirePersistentObject

This method returns a reference to the part or frame with the specified scripting ID.

Signature

    ODPersistentObject *AcquirePersistentObject (ODPersistentObjectID objectID,
                                                 ODObjectType *objectType)

Parameters

objectID (ODPersistentObjectID) - input

  The scripting ID of the desired object.

objectType (ODObjectType *) - output

  The type of the returned object. This parameter can be set to one of the following values:

  kODFrameObject | A frame.
  kODPartObject | A part.

Returns

rv (ODPersistentObject *) - returns

  A reference to the part or frame with the specified scripting ID.

Remarks

You call this method to obtain a reference to a part or frame, given the ID that identifies it for scripting purposes. This method should be used only for scripting.

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

Exception Handling

kODErrInvalidParameter | The objectID parameter is invalid.
kODErrInvalidPersistentObjectID | This draft has no persistent object with the specified ID, or the object is of a type that cannot be acquired.

### AcquireStorageUnit

This method returns a reference to the storage unit with the specified ID.

Signature

    ODStorageUnit *AcquireStorageUnit (ODStorageUnitID id)

Parameters

id (ODStorageUnitID) - input

  The ID of the target storage unit.

Returns

rv (ODStorageUnit *) - returns

  A reference to the specified storage-unit object.

Remarks

You call this method to recreate a storage unit object from its stored data. The id parameter must be the ID of a storage unit in this draft.

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

Exception Handling

kODErrInvalidID | The id parameter is invalid.

Related Methods

- ODDraft::CreateStorageUnit

### BeginClone

This method initiates a cloning transaction to transfer data from this draft to the specified destination draft.

Signature

    ODDraftKey BeginClone (ODDraft *destDraft,
                           ODFrame *destFrame,
                           ODCloneKind kind)

Parameters

destDraft (ODDraft *) - input

  A reference to the destination draft to which objects are to be cloned.

destFrame (ODFrame *) - input

  A reference to the destination frame or kODNULL if the clone operation is not a paste or a drop.

  This parameter allows OpenDoc to detect an attempt to move a part into one of its embedded frames. For paste operations, this parameter should be set to the part's active frame. For drop operations, this parameter should be set to the drop target frame. In all other cases, this parameter should be kODNULL.

kind (ODCloneKind) - input

  The kind of clone operation to be performed. Set the parameter to a valid ODCloneKind. For a list of ODCloneKind types, see ODCloneKind.

Returns

rv (ODDraftKey) - returns

  The draft key for this cloning transaction.

Remarks

This method sets up a cloning transaction of the specified kind and returns a unique draft key that identifies the transaction. Other methods involved in cloning require you to supply this draft key as a parameter. The Bento container suite allows only one cloning transaction at any given time.

After calling this method, you call the draft object's Clone method to clone a particular persistent object. To commit a successful cloning transaction, call this draft object's EndClone method; before the EndClone method has successfully executed, there is no guarantee that all the objects have been copied. If the cloning operation cannot be completed for any reason, you must terminate the transaction by calling this draft object's AbortClone method.

Exception Handling

kODErrCloningInProgress | Another cloning process is in progress.
kODErrInconsistentCloneKind | The specified clone kind is used inconsistently. For example, a paste or drop clone kind can occur only following a copy or cut operation.
kODErrInvalidCloneKind | The specified clone kind is invalid.
kODErrInvalidDestinationDraft | The specified destination draft is invalid for the specified clone kind.

Related Methods

- ODDraft::AbortClone
- ODDraft::Clone
- ODDraft::EndClone

### ChangedFromPrev

This method is called by the document shell or container application to indicate whether this draft contains any changes from the previous draft.

Signature

    ODBoolean ChangedFromPrev ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether this draft contains any changes from the previous draft:

  kODTrue | This draft contains changes from the previous draft.
  kODFalse | This draft does not contain changes from the previous draft.

Remarks

The document shell or container application calls this method to see whether this draft contains changes from the previous draft; if so, the draft must be notified so that it can save these changes. If this draft contains no changes since it was last saved, it is said to be clean and this method returns kODFalse; if it contains changes, it is said to be dirty and this method returns kODTrue.

You can call the SetChangedFromPrev method when your part's content has changed; this marks the draft as dirty so that content changes will be saved.

A draft cannot be marked clean after it has been marked dirty. However, you can call the RemoveChanges method to remove all the changes from this draft.

Related Methods

- ODDraft::RemoveChanges
- ODDraft::SetChangedFromPrev

### Clone

This method clones the specified persistent object or storage unit.

Signature

    ODID Clone (ODDraftKey key,
                ODID fromObjectID,
                ODID toObjectID,
                ODID scope)

Parameters

key (ODDraftKey) - input

  The draft key of the current cloning transaction.

fromObjectID (ODID) - input

  The ID of the persistent object or storage unit to be cloned.

toObjectID (ODID) - input

  The ID of the destination persistent object or storage unit or kODNULLID to create a new storage unit in the destination draft.

scope (ODID) - input

  The ID of the frame that defines the scope of this cloning operation or kODIDALL if all referenced objects are within scope.

Returns

rv (ODID) - returns

  The ID of the destination persistent object or storage unit. The ID of a persistent object is the same as the ID of its storage unit.

Remarks

The following summary describes how to use this method:

- You start a cloning transaction by calling this draft object's BeginClone method, that returns the draft key identifying the cloning transaction.

- Next, call this draft object's Clone method, passing as parameters the draft key returned by the BeginClone method, the ID of the object to be cloned, the ID of the destination storage unit, and the frame object specifying the scope.

- Finally, call this draft object's EndClone method, passing as a parameter the draft key returned by the BeginClone method. The EndClone method commits the cloning transaction and performs the data transfer.

The key parameter is the draft key of the current cloning transaction, which was returned by a call to this draft object's BeginClone method and passed to the calling object's CloneInto method.

The fromObjectID parameter identifies the object to be cloned. If a persistent object exist with the specified ID, that persistent object is cloned; otherwise, the storage unit with the specified ID is cloned.

The toObjectID parameter specifies the ID of the destination storage unit. If the toObjectID parameter is null, a new destination storage unit is created in the destination draft.

If the object being cloned has persistent references to other objects, the scope parameter determines which of the referenced objects are within the scope of this cloning operation. Typically, the scope parameter is the ID of a frame and only those objects embedded in that frame are within scope. In the rare case in which the scope parameter is kODIDALL, all referenced objects are within scope.

This method passes its key parameter, the destination storage unit, and its scope parameter to the CloneInto method of the persistent object or storage unit being cloned. If that persistent object or storage unit has persistent references, its CloneInto method clones any persistently referenced objects that are within the scope of this cloning operation. Objects referenced by strong persistent references are strongly cloned by recursive calls to the Clone method; objects referenced by weak persistent references are weakly cloned by calls to the WeakClone method.

You must not use the returned ID until the end of the current cloning transaction. Furthermore, before you try to access the persistent object or storage unit with the corresponding ID, you must call the IsValidID method to verify that the ID is still valid.

Exception Handling

kODErrInvalidDraftKey | The specified draft key is not the draft key for the current cloning transaction.
kODErrInvalidID | The toObjectID parameter did not specify a valid destination object or storage unit.

Related Methods

- ODDraft::AbortClone
- ODDraft::BeginClone
- ODDraft::EndClone
- ODDraft::IsValidID
- ODDraft::WeakClone
- ODPersistentObject::CloneInto
- ODStorageUnit::CloneInto

### CreateFrame

This method creates a new frame in this draft.

Signature

    ODFrame *CreateFrame (ODObjectType frameType,
                          ODFrame *containingFrame,
                          ODShape *frameShape,
                          ODCanvas *biasCanvas,
                          ODPart *part,
                          ODTypeToken viewType,
                          ODTypeToken presentation,
                          ODBoolean isSubframe,
                          ODBoolean isOverlaid)

Parameters

frameType (ODObjectType) - input

  The type of the frame to be created. This parameter can be set to one of the following values:

  kODFrameObject | A regular frame.
  kODNonPersistentFrameObject | A nonpersistent frame.

containingFrame (ODFrame *) - input

  A reference to the containing frame of the frame to be created.

frameShape (ODShape *) - input

  A reference to the frame shape to be created.

biasCanvas (ODCanvas *) - input

  A reference to the canvas to whose coordinate space the new frame is biased or kODNULL to use the standard platform coordinate bias.

part (ODPart *) - input

  A reference to the part to be displayed in the new frame.

viewType (ODTypeToken) - input

  A tokenized string representing the initial view type for the new 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.

presentation (ODTypeToken) - input

  The initial presentation of the new frame.

isSubframe (ODBoolean) - input

  A flag indicating whether the new frame is a subframe.

  kODTrue | The new frame is a subframe.
  kODFalse | The new frame is be a subframe.

isOverlaid (ODBoolean) - input

  A flag indicating whether the new frame should be an overlaid frame.

  kODTrue | The new frame should be an overlaid frame.
  kODFalse | The new frame should not be an overlaid frame.

Returns

rv (ODFrame *) - returns

  A reference to the newly created frame object.

Remarks

This method constructs and returns a frame object in this draft; the new frame has the characteristics specified by parameters. You can create a regular frame (kODFrameObject) only if this draft's current permissions provide write access.

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

If this method executes successfully, it marks this draft as dirty.

Exception Handling

kODErrCannotCreateFrame | The frame object cannot be created.
kODErrInvalidObjectType | The specified frame type is not kODFrameObject or kODNonPersistentFrameObject.

Related Methods

- ODDraft::AcquireFrame
- ODSession::Tokenize

### CreateLinkSource

This method creates a new link-source object in this draft.

Signature

    ODLinkSource *CreateLinkSource (ODPart *part)

Parameters

part (ODPart *) - input

  A reference to the part containing the source content of the link.

Returns

rv (ODLinkSource *) - returns

  A reference to the newly created link-source object.

Remarks

You typically call this method from your part's CreateLink method when creating the source of a link. You can call this method only if this draft's current permissions provide write access.

Because all link-source objects have a unique link object companion, this method fails if the companion object cannot be created.

This method initializes the reference count of the returned link-source object. When you have finished using this link-source object, you should call its Release method.

If this method executes successfully, it marks this draft as dirty.

Exception Handling

kODErrCannotCreateLink | The link-source object or the companion link object cannot be created.

Related Methods

- ODDraft::AcquireLinkSource
- ODPart::CreateLink

### CreateLinkSpec

This method creates a link-specification object for the specified part.

Signature

    ODLinkSpec *CreateLinkSpec (ODPart *part,
                                ODByteArray *data)

Parameters

part (ODPart *) - input

  A reference to the source part creating this link specification or kODNULL to create an empty link specification.

data (ODByteArray *) - input

  A byte array whose buffer contains arbitrary data to be placed in the link specification or kODNULL to create an empty link specification.

Returns

rv (ODLinkSpec *) - returns

  A reference to the newly created link-specification object.

Remarks

For a link to be created, this method must be called by both the source part and the destination part of a data transfer operation.

- A source part that supports linking calls this method to create a link-specification object. The part parameter is a reference to the source part. The buffer of the data parameter can contain any data that the source part's CreateLink method may need for creating the specified link.

  In addition to writing the source content to the clipboard or drag-and-drop object, the source part calls the WriteLinkSpec method of the returned link-specification object to write link-specification data as a signal that the source can create a link.

  After calling this method, the source part is responsible for deallocating the data parameter and its buffer.

- The user who pastes or drops the source data to a destination part can request a link by means of the Paste As dialog box. When this happens, the destination part calls the method to create an empty link-specification object. The part and data parameters are both null. The destination part then calls the ReadLinkSpec method of the returned link-specification object to read the link-specification data. The destination part creates the link by passing the link-specification object to its draft's AcquireLink method.

The calling part should delete the link-specification object when it has finished using it.

If this method executes successfully, it marks this draft as dirty.

Related Methods

- ODDraft::AcquireLink
- ODLinkSpec::ReadLinkSpec
- ODLinkSpec::WriteLinkSpec
- ODPart::CreateLink

### CreatePart

This method creates a new part in this draft.

Signature

    ODPart *CreatePart (ODType partType,
                        ODEditor optionalEditor)

Parameters

partType (ODType) - input

  The part kind for the new part or kODNULL if the part kind is to be set at a later time.

optionalEditor (ODEditor) - input

  The part editor to be used if the normal binding fails or kODNoEditor if you choose not to specify an editor.

Returns

rv (ODPart *) - returns

  A reference to the newly created part object.

Remarks

You can call this method only if this draft's current permissions provide write access.

This method calls the new part's InitPart method to initialize the part object.

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

If this method executes successfully, it marks this draft as dirty.

Exception Handling

kODErrCannotCreatePart | The specified part object cannot be created.

Related Methods

- ODDraft::AcquirePart
- ODPart::InitPart

### CreateStorageUnit

This method creates a new storage unit in this draft.

Signature

    ODStorageUnit *CreateStorageUnit ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to the newly created storage-unit object.

Remarks

You can call this method only if this draft's current permissions provide write access.

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

If this method executes successfully, it marks this draft as dirty.

Related Methods

- ODDraft::AcquireStorageUnit

### EndClone

This method commits the specified cloning transaction.

Signature

    void EndClone (ODDraftKey key)

Parameters

key (ODDraftKey) - input

  The draft key for the cloning transaction to be committed.

Returns

None.

Remarks

You must call this method to end a successful cloning transaction. The key parameter must be set to the draft returned by a call to the BeginClone method that started the cloning transaction.

If the cloning transaction cannot be completed for any reason, you should call the AbortClone method instead of this method.

After this method executes successfully, the destination draft of the cloning transaction contains copies of all the persistent objects and storage units whose CloneInto methods were called by this draft's Clone method during the transaction.

Exception Handling

kODErrInvalidDraftKey | The specified draft key is not the draft key for the current cloning transaction.
kODErrMoveIntoSelf | This clone transaction attempted to move a part into one of its embedded frames or embed one of the part's display frames into another of its display frames.

Related Methods

- ODDraft::AbortClone
- ODDraft::BeginClone
- ODDraft::Clone

### Externalize

This method is called by the document shell or container application to write to storage all persistent objects and storage units of this draft object.

Signature

    ODDraft *Externalize ()

Parameters

None.

Returns

rv (ODDraft *) - returns

  A reference to this draft object.

Remarks

This method calls the Externalize method on all the persistent objects and storage-unit objects created through this draft and then writes to persistent storage any internal structures of this draft object.

Related Methods

- ODPart::ExternalizeKinds
- ODPersistentObject::Externalize
- ODStorageUnit::Externalize

### GetDocument

This method is called by the document shell or container application to retrieve a reference to the document object that created this draft.

Signature

    ODDocument *GetDocument ()

Parameters

None.

Returns

rv (ODDocument *) - returns

  A reference to the document object that created this draft.

Remarks

This method does not increment the reference count of the returned document; the caller should not call that document's Release method.

### GetID

This method is called by the document shell or container application to retrieve the draft ID of this draft.

Signature

    ODDraftID GetID ()

Parameters

None.

Returns

rv (ODDraftID) - returns

  The ID of this draft.

### GetPermissions

This method returns this draft's current permissions.

Signature

    ODDraftPermissions GetPermissions ()

Parameters

None.

Returns

rv (ODDraftPermissions) - returns

  The kind of access that is currently allowed for this draft. This method returns one of the following values:

  kODDPExclusiveWrite | Read and exclusive-write access.
  kODNone | No access.
  kODDPReadOnly | Readonly access.
  kODSharedWrite | Read and shared-write access.
  kODTransient | Navigation-only access.

Remarks

You can make changes to this draft only if its current permissions allow write access (exclusive or shared). Only the most recent draft of a document can allow write access.

The Bento container suite supports only the kODDPReadOnly and kODDPExclusiveWrite draft permissions.

### GetPersistentObjectID

This method returns the scripting ID of the specified part or frame.

Signature

    ODPersistentObjectID GetPersistentObjectID (ODPersistentObject *object,
                                                ODObjectType objectType)

Parameters

object (ODPersistentObject *) - input

  A reference to the persistent object.

objectType (ODObjectType) - input

  The type of persistent object. This parameter can be set to one of the following parameters:

  kODFrameObject | A frame.
  kODPartObject | A part.

Returns

rv (ODPersistentObjectID) - returns

  The ID, to be used for scripting purposes, of the specified part or frame.

Remarks

You can call this method to obtain the ID that identifies the specified part or frame for scripting purposes.

Exception Handling

kODErrInvalidPersistentObject | The specified persistent object is not valid.

Related Methods

- ODDraft::AcquirePersistentObject

### IsValidID

This method indicates whether the specified object ID is valid.

Signature

    ODBoolean IsValidID (ODID id)

Parameters

id (ODID) - input

  The object ID.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified object ID is valid.

  kODTrue | The specified object ID is valid.
  kODFalse | The specified object ID is invalid.

Remarks

You should call this method after the end of a cloning transaction and before using an ID returned by the Clone or WeakClone method during that transaction.

The id parameter is an ID returned by the Clone or WeakClone method during the recent cloning transaction. If the corresponding object was not strongly cloned during the transaction, the ID is now invalid and should not be used.

Related Methods

- ODDraft::Clone
- ODDraft::WeakClone

### ReleasePart

This method releases the specified part of this draft.

Signature

    void ReleasePart (ODPart *part)

Parameters

part (ODPart *) - input

  A reference to the part to be released.

Returns

None.

Remarks

You should call this method only from your part's Release method when the part's reference count is decremented to 0.

### RemoveChanges

This method is called by the document shell or container application to remove all changes made in the draft.

Signature

    ODDraft *RemoveChanges ()

Parameters

None.

Returns

rv (ODDraft *) - returns

  A reference to this draft object with its changes removed.

Remarks

This method can be called only if the draft's current permissions provide write access.

After this method executes successfully, this draft is empty, and a subsequent call to the ChangedFromPrev method returns kODFalse.

### RemoveFrame

This method removes the specified frame from this draft.

Signature

    void RemoveFrame (ODFrame *frame)

Parameters

frame (ODFrame *) - input

  A reference to the frame object to be removed.

Returns

None.

Remarks

OpenDoc calls this method internally. Parts, the document shell, and container applications do not call this method.

When this method is called, the reference count of the specified frame must be 1, and this draft's current permissions must provide write access.

If this method executes successfully, it marks this draft as dirty. The specified frame is no longer a valid object, and this draft no longer contains a frame object with the corresponding ID.

Exception Handling

kODErrRefCountGreaterThanZero | After the specified frame was released, its reference count was greater than 0.
kODErrRefCountNotEqualOne | The reference count of the specified frame's storage unit is not 1.
kODErrIllegalNullFrameInput | The frame parameter is null.

Related Methods

- ODDraft::Clone
- ODDraft::AcquireFrame
- ODFrame::Remove

### RemoveFromDocument

This method is called by the document shell or container application to remove this draft from its document and destroy this draft.

Signature

    void RemoveFromDocument ()

Parameters

None.

Returns

None.

Remarks

This method can be called only if this draft is empty, is not the base draft of its document, and has a reference count of 1.

After this method executes successfully, this draft is no longer a valid draft object.

### RemoveLink

This method removes the specified link object from this draft.

Signature

    void RemoveLink (ODLink *link)

Parameters

link (ODLink *) - input

  A reference to the link object to be removed.

Returns

None.

Remarks

OpenDoc calls this method internally. Parts, the document shell, and container applications do not call this method.

When this method is called, the reference count of the specified link object must be 1, and this draft's current permissions must provide write access.

If this method executes successfully, it marks this draft as dirty. The specified link object is no longer a valid object, and this draft no longer contains a link object with the corresponding ID.

Exception Handling

kODErrRefCountGreaterThanZero | After the specified frame was released, its reference count was greater than 0.
kODErrRefCountNotEqualOne | The reference count of the specified link object's storage unit is not 1.
kODErrInvalidPersistentObject | The link parameter is null or does not specify a valid persistent object.

Related Methods

- ODDraft::AcquireLink

### RemoveLinkSource

This method removes the specified link-source object from this draft.

Signature

    void RemoveLinkSource (ODLinkSource *link)

Parameters

link (ODLinkSource *) - input

  A reference to the link-source object to be removed.

Returns

None.

Remarks

OpenDoc calls this method internally. Parts, the document shell, and container applications do not call this method.

When this method is called, the reference count of the specified link-source object must be 1, and this draft's current permissions must provide write access.

After this method executes successfully, it marks this draft as dirty. The specified link-source is no longer a valid object, and this draft no longer contains a link-source object with the corresponding ID.

Exception Handling

kODErrRefCountGreaterThanZero | After the specified frame was released, its reference count was greater than 0.
kODErrRefCountNotEqualOne | The reference count of the specified link-source object's storage unit is not 1.
kODErrInvalidPersistentObject | The link parameter is null or does not specify a valid persistent object.

Related Methods

- ODDraft::AcquireLinkSource

### RemovePart

This method removes the specified part from this draft.

Signature

    void RemovePart (ODPart *part)

Parameters

part (ODPart *) - input

  A reference to the part object to be removed.

Returns

None.

Remarks

OpenDoc calls this method internally. Parts, the document shell, and container applications do not call this method.

When this method is called, the reference count of the specified part must be 1, and this draft's current permissions must provide write access.

If this method executes successfully, it marks this draft as dirty. The specified part is no longer a valid object, and this draft no longer contains a part object with the corresponding ID.

Exception Handling

kODErrRefCountGreaterThanZero | After the specified frame was released, its reference count was greater than 0.
kODErrRefCountNotEqualOne | The reference count of the specified part's storage unit is not 1.
kODErrIllegalNullPartInput | The part parameter is null.

Related Methods

- ODDraft::AcquirePart
- ODDraft::CreatePart

### RemoveStorageUnit

This method removes the specified storage unit from this draft.

Signature

    void RemoveStorageUnit (ODStorageUnit *storageUnit)

Parameters

storageUnit (ODStorageUnit *) - input

  A reference to the storage-unit object to be removed.

Returns

None.

Remarks

OpenDoc calls this method internally. Parts, the document shell, and container applications do not call this method.

When this method is called, the reference count of the specified storage unit must be 1, and this draft's current permissions must provide write access.

If this method executes successfully, it marks this draft as dirty. The specified storage unit is no longer a valid object, and this draft no longer contains a storage-unit object with the corresponding ID.

Note:

> Do not use this method to remove the storage unit associated with a persistent object.

Exception Handling

kODErrInvalidRefCount | The persistent-object reference count is not correct.
kODErrInvalidStorageUnit | The specified storage unit is not a valid storage unit.
kODErrNullStorageUnitInput | The storageUnit parameter is null.

Related Methods

- ODDraft::AcquireStorageUnit
- ODDraft::CreateStorageUnit
- ODStorageUnit::Remove

### SaveToAPrevious

This method is called by the document shell or container application to copy the content of this draft to a specified previous draft of the same document.

Signature

    ODDraft *SaveToAPrevious (ODDraft *to)

Parameters

to (ODDraft *) - input

  A reference to the destination draft object or kODNULL for the draft immediately previous to (below) this draft.

Returns

rv (ODDraft *) - returns

  A reference to this draft object.

Remarks

This method copies the content of all the drafts between this draft (inclusive) and the to draft (exclusive) to the to draft. It then makes all the drafts from this draft (inclusive) to the to draft (exclusive) empty. The document shell can call the CollapseDrafts method of this draft's document object to delete these empty drafts from the document.

For this method to be successful, this draft must have a reference count of 1, meaning that only the caller has a reference to this draft object. In addition, there must be no outstanding drafts between this draft (exclusive) and the to draft (exclusive). An outstanding draft has a reference count greater than 0, meaning that it is being used by some object.

Calling this method is equivalent to calling the SaveToAPrevDraft method of this draft's document, passing this draft as the from parameter, and passing the same to parameter.

Exception Handling

kODErrOutstandingDraft | There are outstanding drafts between this draft (exclusive) and the to draft (exclusive) or this draft has a reference count greater than 1.
kODErrDraftDoesNotExist | The draft does not exist or this draft is not a later draft than the to draft.

Related Methods

- ODDocument::CollapseDrafts
- ODDocument::SaveToAPrevDraft

### SetChangedFromPrev

This method marks this draft as dirty.

Signature

    void SetChangedFromPrev ()

Parameters

None.

Returns

None.

Remarks

A draft is said to be dirty if it contains changes since it was last saved. This method lets you mark a draft as dirty when your part's content changes, so that the content changes will be saved.

This method can be called only if the draft's current permissions provide write access.

A draft cannot be marked clean after it has been marked dirty. However, you can call the RemoveChanges method to remove all the changes from this draft.

Related Methods

- ODDraft::ChangedFromPrev
- ODDraft::RemoveChanges

### WeakClone

This method ensures that, if the specified object is cloned, weak persistent references to it are maintained.

Signature

    ODID WeakClone (ODDraftKey key,
                    ODID objectID,
                    ODID toObjectID,
                    ODID scope)

Parameters

key (ODDraftKey) - input

  The draft key of the current cloning transaction.

objectID (ODID) - input

  The ID of the persistent object or storage unit to be weakly cloned.

toObjectID (ODID) - input

  The ID of the destination persistent object or storage unit or kODNULLID to create a new storage unit in this draft.

scope (ODID) - input

  The ID of the frame that defines the scope of this clone transaction or kODIDALL if all referenced objects are within scope.

Returns

rv (ODID) - returns

  The ID of the duplicated persistent object or storage unit.

Remarks

This method is called by the CloneInto method of persistent objects. You can call this method from your part's CloneInto method if your part has weak persistent references to other objects.

The key parameter is the draft key of the current cloning transaction, which was returned by a call to this draft object's BeginClone method and passed to the calling object's CloneInto method.

The objectID parameter is the ID of an object to be weakly cloned because the calling object has a weak persistent reference to it. The WeakClone method does not guarantee that the specified object will be copied, but if the object is copied because of an existing strong persistent reference to it, the calling object's weak persistent references will be maintained across the clone transaction.

The toObjectID parameter specifies the ID of the destination storage unit. If the toObjectID parameter is null, a new destination storage unit is created in this destination draft, if necessary.

If the object being weakly cloned has persistent references to other objects, the scope parameter determines which of the referenced objects are within the scope of this clone operation. Usually the scope parameter is the ID of a frame, and only those objects embedded in that frame are within scope. In the rare case in which the scope parameter is kODIDALL, all referenced objects are within scope.

You must not use the returned ID until the end of the current cloning transaction. Furthermore, before you try to access the persistent object or storage unit with the corresponding ID, you must call the IsValidID method to verify that the ID is still valid.

Exception Handling

kODErrInvalidID | The toObjectID parameter did not specify a valid destination object or storage unit.

Related Methods

- ODDraft::AbortClone
- ODDraft::BeginClone
- ODDraft::Clone
- ODDraft::EndClone
- ODDraft::IsValidID
- ODStorageUnit::CloneInto
- ODPersistentObject::CloneInto

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