Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Determining the Size of an Item's Variable-Length Data

The Collection Manager provides three functions that provide information about an item in a collection. These three functions differ in how they allow you to specify which item you want information about:

• The GetCollectionItemInfo function requires that you specify the collection tag and ID of the desired item.
• The GetIndexedCollectionItemInfo function requires that you specify the collection index of the desired item.
• The GetTaggedCollectionItemInfo function requires that you specify the collection tag and tag list position of the desired item.

These functions each return a variety of information about the specified item--for example, the item's attributes, the size of the item's variable length data, and so on. These functions return each piece of information in a separate parameter. You can specify that you do not want certain pieces of information returned by providing nil for the corresponding parameter. The Collection Manager provides the optional return value constants, each of which is equal to nil, to make your code easier to read.

Listing 5-7 shows how to use the GetCollectionItemInfo function to determine the size of an item's variable-length data, given that item's collection tag and ID.

Listing 5-7 Determining the size of an item's variable-length data

long theSize;
.
.
.
anErr = GetCollectionItemInfo(pointsAndQuotes,  /* collection */
                              'GXPT', 15,  /* tag and id */
                              dontWantIndex,
                              &theSize,  /* returned size */
                              dontWantAttributes); 

(You can also use the GetCollectionItemInfo function to determine an item's collection index, as described in "Determining the Collection Index of an Item" beginning on page 5-19, or to examine an item's attributes, as described in "Getting and Setting the Attributes of an Item" beginning on page 5-24.)

Similarly, you can use the GetIndexedCollectionItemInfo function to determine the size of the item's variable-length data given the item's collection index:

anErr = GetIndexedCollectionItemInfo(pointsAndQuotes, 
                                     index,  /* index of item */
                                     dontWantTag,
                                     dontWantId,
                                     &theSize, /* returned size */
                                     dontWantAttibutes); 

(You can also use the GetIndexedCollectionItemInfo function to determine an item's collection tag and collection ID, as described in "Determining the Tag and ID of an Item" beginning on page 5-21, or to examine an item's attributes, as described in the next section, "Getting and Setting the Attributes of an Item.".)

Finally, you can use the GetTaggedCollectionItemInfo function to determine the size of the item's variable-length data given its collection tag and tag list position.

anErr = GetTaggedCollectionItemInfo(pointsAndQuotes, 
                                    'GXPT',  /* tag of item */
                                    11,  /* tag list position */
                                    dontWantId,
                                    dontWantIndex,
                                    &theSize, /* returned size */
                                    dontWantAttributes);

(You can also use the GetTaggedCollectionItemInfo function to determine an item's collection index, as described in "Determining the Collection Index of an Item" beginning on page 5-19, to determine an item's collection ID, as described in "Determining the Tag and ID of an Item" beginning on page 5-21, or to examine an item's attributes, as described in the next section, "Getting and Setting the Attributes of an Item.")

For more information about identifying collection items, see "Methods of Identifying Collection Items" on page 5-11.

For more information about the GetCollectionItemInfo, GetIndexedCollectionItemInfo, and GetTaggedCollectionItemInfo functions, see "Getting Information About a Collection Item" beginning on page 5-76.