Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Determining the Collection Index of an Item

Once you have added an item to a collection, you can identify that item in three ways:

• You can specify its collection tag and ID.
• You can specify its collection tag and its tag list position.
• You can specify its collection index.

A collection index is a unique value that the Collection Manager assigns to each item in a collection. You can use an item's collection index to identify the item without specifying the item's collection tag or collection ID. In fact, once you've determined the collection index of an item, specifying that item using its collection index results in faster operations than specifying the item using its collection tag and collection ID.

There are two ways to determine the collection index that the Collection Manager has assigned to an item:

• You can use the GetCollectionItemInfo function. With this function, you specify the collection tag and collection ID of the item, and the function returns the item's collection index.
• You can use the GetTaggedCollectionItemInfo function. With this function, you specify the collection tag and the tag list position of the item, and the function returns the item's collection index.

Both of these functions optionally return other information about the specified item, as shown in the next two sections.

Listing 5-5 shows how to use the the GetCollectionItemInfo function to determine the collection index of an item from the sample collection created in "Adding Items to a Collection" beginning on page 5-17. This listing uses the dontWantSize and dontWantAttributes constants, which are equal to nil and specify that you don't want to determine certain information about the item. These constants are described in "Optional Return Value Constants" on page 5-49.

Listing 5-5 Determining the index of an item

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

After this call to GetCollectionItemInfo function, the index variable contains the collection index of the item in the pointsAndQuotes collection with the 'GXPT' collection tag and a collection ID of 15. You can use this value to identify this item when using certain Collection Manager functions, such as RemoveIndexedCollectionItem and GetIndexedCollectionItem.

You can also use the GetTaggedCollectionItemInfo function to determine the collection index of a collection item. This function allows you to specify the item using the item's collection tag and tag list position. For example, in Listing 5-5, the item is specified using the 'GXPT' collection tag and collection ID 15. Assuming the Collection Manager has assigned this item a tag list position of 11, you could also use the call

anErr = GetTaggedCollectionItemInfo(pointsAndQuotes, 
                                    'GXPT', /* collection tag */
                                    11, /* tag list position */
                                    dontWantId, 
                                    &index, /* returned index */
                                    dontWantSize, 
                                    dontWantAttributes);

to determine the collection index for that item.

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

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