Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Examining the Collection Tags of a Collection

The Collection Manager provides three functions that allow you to examine the collection tags contained in a specific collection:

• You can use the CollectionTagExists function to determine if any of the items in a specific collection have a specified collection tag.
• You can use the CountCollectionTags function to determine the total number of distinct collection tags contained in the items of a collection.
• You can use the GetIndexedCollectionTag function to examine the value of one of the distinct collection tags contained in a collection.

Every collection has a list of distinct collection tags contained in that collection. The GetIndexedCollectionTag function allows you to step through this list of distinct collection tags, as shown in Listing 5-18.

Listing 5-18 Counting tags in a collection

long numTags, numItems, eachTag, eachItem;
.
.
.
numTags = CountCollectionTags(pointsAndQuotes);

/* iterate through each tag */
for (eachTag = 1; eachTag <= numTags; ++eachTag) {
   GetIndexedCollectionTag(pointsAndQuotes, eachTag, &theTag);
   numItems = CountTaggedCollectionItems(pointsAndQuotes, theTag);

   /* iterate through each item with that tag */
   for (eachItem = 1; eachItem <= numItems; ++eachItem) {

      /* find size of item data and obtain copy of data */
      GetTaggedCollectionItem(pointsAndQuotes, 
                              theTag, eachItem, 
                              &theSize, dontWantData);
      theData = (char *) NewPtr(theSize);
      GetTaggedCollectionItem(pointsAndQuotes, 
                              theTag, eachItem, 
                              dontWantSize, theData);
      .
      .
      .
      /* manipulate item data . . .*/
      .
      .
      .
      DisposePtr(theData);
   }
}

This sample code determines the total number of distinct tags in the pointsAndQuotes collection using the CountCollectionTags function. Then, it uses the GetIndexedCollectionTag function to step through each of the distinct collection tags in the collection.

With each collection tag, the sample code uses the GetTaggedCollectionItem function to retrieve the variable-length data from each item with the tag. In this manner, this sample code retrieves the data from every item in the collection.

For more information about the CollectionTagExists, CountCollectionTags, and GetIndexedCollectionTag functions, see "Getting Information About Collection Tags" beginning on page 5-85.