Carbon


GetTaggedCollectionItemInfo

Header: Collections.h Carbon status: Supported

Obtains information about a specific collection item given the item’s collection tag and tag list position.

OSErr GetTaggedCollectionItemInfo (
    Collection c, 
    CollectionTag tag, 
    SInt32 whichItem, 
    SInt32 *id, 
    SInt32 *index, 
    SInt32 *itemSize, 
    SInt32 *attributes
);
c

A reference to the collection object containing the item you want to obtain information about. The behavior of this function is undefined if you do not provide a reference to a valid collection object.

tag

The collection tag associated with the item you want to obtain information about.

whichItem

The tag list position of the item you want to obtain information about.

id

A pointer to an SInt32 value. On return, this value represents the collection ID associated with the specified item. You may specify the constant dontWantId for this parameter if you do not want to determine the specified item’s collection ID.

index

A pointer to an SInt32 value. On return, this value represents the collection index of the specified item. You may specify the constant dontWantIndex for this parameter if you do not want to determine the specified item’s collection index.

itemSize

A pointer to an SInt32 value. On return, this value indicates the size in bytes of the data associated with the specified item. You may specify the constant dontWantSize for this parameter if you do not want to determine the specified item’s data size.

attributes

A pointer. On return, this value contains a copy of the attributes associated with the specified item. You may specify the constant dontWantAttributes for this parameter if you do not want a copy of the item’s attributes.

function result

A result code.

DISCUSSION

Remember that a collection tag and a tag list position uniquely identify a collection item. The tag list position indicates where the collection item would lie in a list made up of all the collection items with the same collection tag. For example:

By sequentially incrementing the whichItem parameter, you can use this function to step through all of the items in a collection that share a collection tag without knowing their collection IDs.

To obtain information about a collection item using the collection tag and collection ID to specify the item, use the GetCollectionItemInfo function.

To obtain information about a collection item using the collection index to specify the item, use the GetIndexedCollectionItemInfo function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.


© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)