Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Working With Macintosh Memory Manager Handles

ReplaceIndexedCollectionItemHdl

You use the ReplaceIndexedCollectionItemHdl function to replace the variable-length data of an item in a collection given the item's collection index, specifying the item's new variable-length data using a handle rather than a pointer and a data size.

OSErr ReplaceIndexedCollectionItemHdl(Collection target, 
                                      long index,
                                      Handle itemData);

target

A reference to the collection containing the item you want to replace.

index

The collection index associated with the item you want to replace.

itemData

A Macintosh Memory Manager handle to the new variable-length data.

DESCRIPTION

The ReplaceIndexedCollectionItemHdl function replaces the variable-length data of an item in the target collection. You specify which item to replace using the index parameter. If the target collection does not contain an item whose collection index matches the value of the index parameter, this function returns a collectionIndexRangeErr result code.

If the target collection does contain an item with the specified index, this function replaces the data in that item with new data (if the existing item is not locked--if it is, this function returns a collectionItemLockedErr result code). The resulting item contains

• the same collection tag as the original item
• the same collection ID as the original item
• the same attributes as the original item
• the variable-length data specified by the itemData parameter

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

RESULT CODES

memFullErr	-108	Can't allocate memory.
collectionItemLockedErr	-5750	Can't replace locked item.
collectionIndexRangeErr	-5752	Index is out of range.

SEE ALSO

For information about collection items, see "Collection Items" beginning on page 5-8.

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

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