Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Adding and Replacing Items in a Collection

ReplaceIndexedCollectionItem

You use the ReplaceIndexedCollectionItem function to replace the variable-length data of an item in a collection given the item's index.

OSErr ReplaceIndexedCollectionItem(Collection target, long index,
                                   long itemSize, void *itemData);

target

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

index

The collection index associated with the item to replace.

itemSize

The item's size.

itemData

A pointer to the item's data.

DESCRIPTION

The ReplaceIndexedCollectionItem function replaces the variable-length data associated with 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 that item with a new item (if the existing item is not locked--if it is, this function returns a collectionItemLockedErr result code). The new 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 itemSize and itemData parameters

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

The itemSize parameter determines how many bytes of information this function copies into the new item. If you specify 0 for this parameter, or provide nil for the itemData parameter, this function copies no information into the variable-length data of the new item, or removes the variable-length data if the item already exists.

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.

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 replace a collection item using the item's tag and ID (rather than the item's index), use the ReplaceIndexedCollectionItem function, described on page 5-63.

To remove an item from a collection, use the functions described in the next section.