Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Removing Items From a Collection

PurgeCollection

You use the PurgeCollection function to remove all items in a collection whose attributes match a specified pattern.

void PurgeCollection(Collection target,
                     long whichAttributes,
                     long matchingAttributes);

target

A reference to the collection object containing the items you want to remove.

whichAttributes

A mask indicating which attributes you want to test.

matchingAttributes

A long word containing the values of the attributes you want to match.

DESCRIPTION

The PurgeCollection function removes from the target collection any items whose attributes match the criteria you specify in the whichAttributes and matchingAttributes parameters.

The whichAttributes parameter allows you to specify which attributes this function examines. You should set the bits of the whichAttributes parameter that correspond to the attributes you want to test.

This function compares the specified attributes of each item in the target collection with the corresponding attributes in the matchingAttributes parameter. If the values of all the specified attributes match, the function removes the item. To avoid purging locked items, you should clear the lock attribute in the whichAttributes and matchingAttributes parameters.

SEE ALSO

For information about collection items, see "Collection Items" beginning on page 5-8.

For examples using this function, see "Removing Items From a Collection" beginning on page 5-30.

To remove all of the items in a collection with a specified collection tag, use the PurgeCollectionTag function, described in the next section.

To remove every item in a collection, use the EmptyCollection function, described on page 5-68.