Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Cloning or Copying a Collection

You use the CloneCollection and CopyCollection functions to clone and copy collection objects. You clone a collection object if you want to make a copy of the reference to the collection object, and you copy a collection object if you want to make a copy of the entire object, including all of its items.

For example, if you have a reference to a collection object stored in the variable aCollection, you can create a new reference to this collection using

newCollection = CloneCollection(aCollection);

which increments the owner count of the collection object referenced by the aCollection variable and returns a copy of the reference as the function result. After this call to the CloneCollection function, the newCollection and aCollection variables reference the same collection object, which has an incremented owner count.

You can create a copy of a collection object, including a copy of all its items, using

newCollection = CopyCollection(aCollection, nil);

The CopyCollection function does not increment the owner count of the aCollection collection. Instead, it creates a new collection object with an owner count of 1, copies all of the information from the aCollection collection into the new collection, and returns a reference to the new collection. After this call to the CopyCollection function, the newCollection and aCollection variables reference two distinct collections--you can make changes to one without affecting the other.

You can use the second parameter of the CopyCollection function to provide a reference to an existing collection object, in which case the function copies the information from the collection referenced by the first parameter into the collection referenced by the second parameter. If the collection referenced by the second parameter already has information in it, the function

• removes all of the items in the second collection--including locked items--before copying the items from the first collection into the second collection
• copies the default attribute values from the first collection into the second collection

The CopyCollection function does not copy the owner count or the exception procedure of the first collection; it leaves the owner count and the exception procedure of the second collection unchanged.

You can find more information about the CloneCollection function on page 5-56. You can find more information about the CopyCollection function on page 5-57.