Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Removing Items From a Collection

The Collection Manager provides two methods for removing individual items from a collection:

• You can use the RemoveCollectionItem function, specifying the collection tag and collection ID of the item you want to remove.
• You can use the RemoveIndexedCollectionItem function, specifying the collection index of the item you want to remove.

The Collection Manager provides three methods for removing multiple items from a collection:

• You can use the PurgeCollection function to remove all the items in a collection whose attributes match criteria you specify.
• You can use the PurgeCollectionTag function to remove all the items in a collection that have a specified collection tag.
• You can use the EmptyCollection function to remove every item from a collection.

Listing 5-12 shows how you can use the RemoveCollectionItem function to remove an item from a collection. (This example uses the collection created in "Adding Items to a Collection" beginning on page 5-17.)

Listing 5-12 Removing an item in a collection

anErr = RemoveCollectionItem(pointsAndQuotes, 
                             'QUOT', 1); /* tag and id */

You can remove a collection item even if its lock attribute is set--the lock attribute only affects replacing. For example, if you have set the lock attribute of the collection item with the collection tag 'QUOT' and the collection ID 0, you can remove this item using

anErr = RemoveCollectionItem(pointsAndQuotes, 
                             'QUOT', 0); /* tag and id */

You can also remove the item using

anErr = RemoveCollectionItem(pointsAndQuotes, 
                             'QUOT', 0); /* tag and id */

If you know the index of an item, you can use the RemoveIndexedCollectionItem function to remove the item. This function finds the specified item more efficiently than the RemoveCollectionItem function. Listing 5-13 shows an example of this function.

Listing 5-13 Removing an item using the item's index

long index;
.
.
.
/* get the index */
anErr = GetCollectionItemInfo(pointsAndQuotes, 
                              'QUOT', 1,
                              &index, 
                              dontWantSize, 
                              dontWantAttributes);
.
.
.
/* remove the item */
anErr = RemoveIndexedCollectionItem(pointsAndQuotes, index);

The example in Listing 5-13 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.

The PurgeCollection function allows you to remove multiple items from a collection. You provide this function with a collection and a set of attribute values, and it removes any items in the collection whose attributes match these values. You specify which attributes to examine in the second parameter of this function, and you specify the values to compare those attributes against in the third parameter, as shown in
Listing 5-14.

Listing 5-14 Removing multiple items with specific attributes

long whichAttributes, attributeValues;
.
.
.
/* specify which attributes to examine: user 0 and user 1 */
whichAttributes = collectionUser0Mask 
                  | collectionUser1Mask;
/* specify the values to test for: user 0 set and user 1 clear */
attributeValues = collectionUser0Mask 
                  & ~collectionUser1Mask; 

/* purge all items with user 0 attribute set and user 1 clear */
PurgeCollection(pointsAndQuotes,
                whichAttributes, 
                attributeValues); 

This example sets two bits in the whichAttributes variable--the user 0 attribute and the user 1 attribute--and clears every other bit in this variable, which signifies that the function should test only the user 0 attribute and the user 1 attribute. The attributeValues variable sets the user attribute 0 flag and clears the user attribute 1 flag. Therefore, this call to PurgeCollection removes every item in the collection that has the user 0 attribute set and the user 1 attribute clear. It ignores the values of all the other attributes.

You can use the PurgeCollectionTag function to remove all of the items in a collection that share a collection tag--even the locked items. To remove all the items with the collection tag 'GXPT' from the pointsAndQuotes collection (which is defined in "Adding Items to a Collection" beginning on page 5-17), you could use this line of code:

PurgeCollectionTag(pointsAndQuotes, 'GXPT'); 

Finally, you can remove all of the items in a collection--even the locked items--using the EmptyCollection function:

EmptyCollection(pointsAndQuotes); 

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

For more information about the RemoveCollectionItem, RemoveIndexedCollectionItem, PurgeCollection, PurgeCollectionTag, and EmptyCollection functions, see "Removing Items From a Collection" beginning on page 5-65.