Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Replacing Items in a Collection

The Collection Manager provides two methods for replacing items in a collection:

• You can use the AddCollectionItem function, specifying the collection tag and collection ID of an existing item.
• You can use the ReplaceIndexedCollectionItem function, specifying the collection index of an existing item.

Note

The Collection Manager also provides the utility functions, AddCollectionItemHdl and ReplaceCollectionItemHdl, which allow you to specify a handle, rather than a pointer, to the item's data. See "Working With Macintosh Memory Manager Handles" beginning on page 5-92 for more information about these functions.

The new item does not have to be the same size as the replaced item. For example, Listing 5-10 shows how you can use the AddCollectionItem function to replace the data in a collection item with a new data of a different length. (This example uses the collection created in "Adding Items to a Collection" beginning on page 5-17, in which the item identified by the collection tag 'QUOT' and the collection ID 1 contains the 29-character string "Fourscore and seven years ago")

Listing 5-10 Replacing an item in a collection

anErr = AddCollectionItem(pointsAndQuotes, 
                          'QUOT', 1, 
                          22, "Eighty-seven years ago");

You cannot replace a collection item if its lock attribute is set. For example, the previous section shows how to set the lock attribute of the item with the collection tag 'QUOT' and the collection ID 0. If you try to replace this item using

anErr = AddCollectionItem(pointsAndQuotes, 
                          'QUOT', 0, 
                          24, "Plus c'est la meme chose");

the code sets the anErr variable to the collectionItemLockedErr value and the Collection Manager does not replace the item.

If you know the collection index of an item, you can use the ReplaceIndexedCollectionItem function to replace the item. This function finds the specified item more efficiently than the AddCollectionItem function. Listing 5-11 shows an example of this function.

Listing 5-11 Replacing an item using the item's index

long index;
.
.
.
/* find the index. */
anErr = GetCollectionItemInfo(pointsAndQuotes, 
                              'QUOT', 1,
                              &index,
                              dontWantSize,
                              dontWantAttributes);
.
.
.
/* replace the item. */
anErr = ReplaceIndexedCollectionItem(pointsAndQuotes, 
                                     index,
                                     22, 
                                     "Eighty-seven years ago");

The example in Listing 5-11 uses the GetCollectionItemInfo function to find the collection index that the Collection Manager has assigned to the item with a collection tag of 'QUOT' and a collection ID of 1. Finding this collection index requires some processing time. However, once you've found the item's collection index, you can use it to find information about the item quickly, because functions that search for a collection item using the item's collection index operate more efficiently than functions that search using the item's collection tag and collection ID. Typically, if you want to search for an item only once, you use the item's collection tag and collection ID. If you know that you have to search for the same item repeatedly, you find the item's collection index and use the collection index when examining or editing the item.

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

For more information about the AddCollectionItem function and the ReplaceIndexedCollectionItem function, see "Adding and Replacing Items in a Collection" beginning on page 5-62.