Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Cloning and Copying Collection Objects

CloneCollection

You can use the CloneCollection function to clone a collection object--that is, to increment its owner count.

Collection CloneCollection (Collection target);

target

A reference to the collection object you want to clone.

function result

A reference to the cloned collection. (This result is effectively a copy of the reference you provide in the target parameter.)

DESCRIPTION

The CloneCollection function increments the owner count of the collection object referenced by the target parameter, and, as a programming convenience, returns a reference to this collection as the function result.

Typically, you use this function to increment a collection object's owner count to represent a new reference to the collection object. For example, if you want two variables in your application to reference a single collection object, you can use this code to maintain the correct owner count:

firstReference = NewCollection();
secondReference = CloneCollection(firstReference);

Disposing of either reference (using the DisposeCollection function) simply decrements the collection's owner count. Disposing of the remaining reference decrements the owner count again and frees the memory associated with the collection.

The CloneCollection function does not return an error code.

SEE ALSO

For general information about QuickDraw GX objects, see the chapter "Introduction to QuickDraw GX" in Inside Macintosh: QuickDraw GX Objects.

For examples of this function, see "Cloning or Copying a Collection" beginning on page 5-14.

To decrement the owner count of a collection object, use the DisposeCollection function, which is described in the previous section. To determine the owner count of an existing collection object, use the CountCollectionOwners function, which is described in the next section.

To copy a collection object, use the CopyCollection function, which is described on page 5-57.