Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: QuickDraw GX Environment and Utilities /
Chapter 5 - Collection Manager / Collection Manager Reference
Functions / Working With Macintosh Memory Manager Handles


You use the AddCollectionItemHdl function to add a new item to a collection or to replace an existing item in a collection, specifying the item's variable-length data using a handle rather than a pointer and a data size.

OSErr AddCollectionItemHdl (Collection target,
                            CollectionTag tag, long id,
                            Handle itemData);
A reference to the collection you want to add the item to.
The collection tag you want to associate with the new item.
The collection ID you want to associate with the new item.
A Macintosh Memory Manager handle to the item's variable-length data.
The AddCollectionItemHdl function adds an item to the collection referenced by the target parameter. This new item contains:

This function copies the information referenced by the itemData parameter into the new item; after calling this function, you may alter this information or free the memory referenced by this parameter without affecting the collection.

If the target collection already contains an item with the same collection tag and collection ID as specified in the tag and id parameters, this function removes the variable-length data from the original item and replaces it with the new data, unless the existing item is locked. If it is locked, this function returns a collectionItemLockedErr result code.

memFullErr-108Can't allocate memory.
collectionItemLockedErr-5750Can't replace locked item.
For information about collection items, see "Collection Items" beginning on page 5-8.

For information about locking collection items, see "Getting and Setting the Attributes of an Item" beginning on page 5-24. To lock a collection item, use the functions described in "Editing Item Attributes" beginning on page 5-82.

To add or replace a collection item using a pointer (rather than a handle) to the item's variable-length data, use the AddCollectionItem function, described on page 5-62.

To replace a collection item using the item's collection index (rather than the item's collection tag and collection ID), use the ReplaceIndexedCollectionItemHdl function, described in the next section.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996