Important: The information in this document is obsolete and should not be used for new development.
Determining the Collection Index of an ItemOnce you have added an item to a collection, you can identify that item in three ways:
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.
- 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.
There are two ways to determine the collection index that the Collection Manager has assigned to an item:
Both of these functions optionally return other information about the specified item, as shown in the next two sections.
- You can use the
GetCollectionItemInfofunction. 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
GetTaggedCollectionItemInfofunction. 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.
Listing 5-5 shows how to use the the
GetCollectionItemInfofunction 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
dontWantAttributesconstants, which are equal to
niland 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
indexvariable contains the collection index of the item in the
pointsAndQuotescollection 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
You can also use the
GetTaggedCollectionItemInfofunction 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
GetTaggedCollectionItemInfofunctions, see "Getting Information About a Collection Item" beginning on page 5-76.