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.
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:
|
Overridden Methods | There are no methods overridden by the ODDraft class. |
This method aborts the specified cloning transaction.
Signature
void AbortClone (ODDraftKey key) |
Parameters
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
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
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. |
This method returns a reference to the frame whose data is stored in the specified storage unit.
Signature
ODFrame *AcquireFrame (ODStorageUnitID id) |
Parameters
Returns
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
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
Returns
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
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
Returns
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
This method returns a reference to the part whose data is stored in the specified storage unit.
Signature
ODPart *AcquirePart (ODStorageUnitID id) |
Parameters
Returns
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
This method returns a reference to the part or frame with the specified scripting ID.
Signature
ODPersistentObject *AcquirePersistentObject (ODPersistentObjectID objectID,
ODObjectType *objectType)
|
Parameters
| kODFrameObject | A frame. |
| kODPartObject | A part. |
Returns
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. |
This method returns a reference to the storage unit with the specified ID.
Signature
ODStorageUnit *AcquireStorageUnit (ODStorageUnitID id) |
Parameters
Returns
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
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
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.
Returns
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
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
| 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
This method clones the specified persistent object or storage unit.
Signature
ODID Clone (ODDraftKey key,
ODID fromObjectID,
ODID toObjectID,
ODID scope)
|
Parameters
Returns
Remarks
The following summary describes how to use this method:
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
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
| kODFrameObject | A regular frame. |
| kODNonPersistentFrameObject | A nonpersistent 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. |
| kODTrue | The new frame is a subframe. |
| kODFalse | The new frame is be a subframe. |
| kODTrue | The new frame should be an overlaid frame. |
| kODFalse | The new frame should not be an overlaid frame. |
Returns
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
This method creates a new link-source object in this draft.
Signature
ODLinkSource *CreateLinkSource (ODPart *part) |
Parameters
Returns
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
This method creates a link-specification object for the specified part.
Signature
ODLinkSpec *CreateLinkSpec (ODPart *part,
ODByteArray *data)
|
Parameters
Returns
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.
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 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
This method creates a new part in this draft.
Signature
ODPart *CreatePart (ODType partType,
ODEditor optionalEditor)
|
Parameters
Returns
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
This method creates a new storage unit in this draft.
Signature
ODStorageUnit *CreateStorageUnit () |
Parameters
None.
Returns
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
This method commits the specified cloning transaction.
Signature
void EndClone (ODDraftKey key) |
Parameters
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
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
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
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
Remarks
This method does not increment the reference count of the returned document; the caller should not call that document's Release method.
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
This method returns this draft's current permissions.
Signature
ODDraftPermissions GetPermissions () |
Parameters
None.
Returns
| 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.
This method returns the scripting ID of the specified part or frame.
Signature
ODPersistentObjectID GetPersistentObjectID (ODPersistentObject *object,
ODObjectType objectType)
|
Parameters
| kODFrameObject | A frame. |
| kODPartObject | A part. |
Returns
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
This method indicates whether the specified object ID is valid.
Signature
ODBoolean IsValidID (ODID id) |
Parameters
Returns
| 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
This method releases the specified part of this draft.
Signature
void ReleasePart (ODPart *part) |
Parameters
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.
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
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.
This method removes the specified frame from this draft.
Signature
void RemoveFrame (ODFrame *frame) |
Parameters
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
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.
This method removes the specified link object from this draft.
Signature
void RemoveLink (ODLink *link) |
Parameters
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
This method removes the specified link-source object from this draft.
Signature
void RemoveLinkSource (ODLinkSource *link) |
Parameters
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
This method removes the specified part from this draft.
Signature
void RemovePart (ODPart *part) |
Parameters
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
This method removes the specified storage unit from this draft.
Signature
void RemoveStorageUnit (ODStorageUnit *storageUnit) |
Parameters
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
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
Returns
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
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
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
Returns
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