Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Adding and Replacing Items in a Collection

AddCollectionItem

You use the AddCollectionItem function to add a new item to a collection or to replace an existing item in a collection.

OSErr AddCollectionItem (Collection target,
                         CollectionTag tag, long id,
                         long itemSize, void *itemData);

target

A reference to the collection you want to add the item to.

tag

The collection tag you want to associate with the new item.

id

The collection ID you want to associate with the new item.

itemSize

The size in bytes of the item's variable-length data.

itemData

A pointer to the item's variable-length data.

DESCRIPTION

The AddCollectionItem function adds an item to the collection referenced by the target parameter. This new item contains

• the collection tag specified by the tag parameter
• the collection ID specified by the id parameter
• the attributes specified by the default attributes of the target collection
• 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.

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 original item and replaces it with the new one, unless the existing item is locked. If it is locked, this function returns a collectionItemLockedErr result code.

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.

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.

For examples using this function, see "Adding Items to a Collection" beginning on page 5-17 and "Replacing Items in a Collection" beginning on page 5-28.

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

To remove an item from a collection, use the functions described in "Removing Items From a Collection" beginning on page 5-65.