Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Getting Information About a Collection Item

GetTaggedCollectionItemInfo

You use the GetTaggedCollectionItemInfo function to obtain information about a specific collection item given the item's collection tag and tag list position.

OSErr GetTaggedCollectionItemInfo(Collection source,
                                  CollectionTag tag,
                                  long position,
                                  long *id,
                                  long *index,
                                  long *itemSize,
                                  void *attributes);

source

A reference to the collection object containing the item you want to obtain information about.

tag

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

position

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

id

A pointer to a long 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 a long 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 a long 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 to a long value. 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.

DESCRIPTION

The GetTaggedCollectionItemInfo function allows you to obtain information about a specific collection item in the collection referenced by the source parameter. You specify the item in the source collection using the tag and position parameters. In the tag parameter you specify the collection tag of the desired item and in the position parameter you specify the tag list position of the desired item.

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:

• A tag list position of 1 indicates the first item with the specified tag.
• A tag list position of 2 indicates the second item with the specified tag.

By sequentially incrementing the position 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.

The GetTaggedCollectionItemInfo function returns information in the id, index, itemSize, and attributes parameters:

• If you provide a pointer in the id parameter, the function uses this parameter to return the collection ID of the specified item.
• If you provide a pointer in the index parameter, the function uses this parameter to return the collection index of the specified item.
• If you provide a pointer in the itemSize parameter, the function uses this parameter to return the size in bytes of the variable-length data associated with the specified collection item.
• If you provide a pointer in the attributes parameter, the function uses this parameter to return a copy of the attributes associated with the specified collection item.

RESULT CODES

collectionIndexRangeErr

-5752

Index is out of range.

SEE ALSO

For information about collection items and their associated collection tags, collection IDs, and variable-length data, see "Collection Items" beginning on page 5-8. For information about tag list positions, see "Methods of Identifying Collection Items" beginning on page 5-11.

For examples of this function, see "Determining the Collection Index of an Item" beginning on page 5-19, "Determining the Size of an Item's Variable-Length Data" beginning on page 5-22, and "Getting and Setting the Attributes of an Item" beginning on page 5-24.

To obtain information about a collection item using the collection tag and collection ID to specify the item, use the GetCollectionItemInfo function, described on page 5-76.

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