Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Adding Items to a Collection

Once you've created a collection object, you can add new items to the collection using the AddCollectionItem function. With this function, you specify the collection tag and collection ID that you want associated with the new item, the size of the new item's variable-length data, and a pointer to the data.

Note

The Collection Manager also provides a utility function, AddCollectionItemHdl, which allows you to specify a handle, rather than a pointer, to the data. See page 5-92 for more information about this function.

Listing 5-3 creates a new collection object and adds ten items to it. Each item has the collection tag 'GXPT', the items have collection IDs 0 through 9, and each item contains two coordinates that make up a QuickDraw GX point.

Listing 5-3 Adding items to a collection

OSErr anErr;
Collection pointsAndQuotes;
gxPoint location;
long count;
.
.
.
pointsAndQuotes = NewCollection();

location.x = ff(10);
location.y = ff(10);
   
for (count = 0; count < 10; count++) {
   anErr = AddCollectionItem(pointsAndQuotes,  
                             'GXPT',  /* tag */
                             count,   /* id */
                             sizeof(gxPoint),     /* size */
                             &location); /* data */
                          
   location.x += ff(1);  /* change data for next item */
   location.y += ff(1);
}

The collection resulting from the code in Listing 5-3 is very similar to an array: the items are numbered sequentially starting with 0, and all items are of the same size. Unlike arrays, however, collections are not limited to these properties. For example, you can add items to a collection dynamically, increasing the total number of collection items during run time. That is, you do not have to specify the capacity of the collection at compile time. Also, collection IDs do not have to be sequential. To demonstrate, the code

location.x = ff(100);
location.y = ff(100);
anErr = AddCollectionItem(pointsAndQuotes, 
                          'GXPT', 20, /* tag and id */
                          sizeof(gxPoint),     /* size */
                          &location); /* data */

adds an eleventh item to the collection from Listing 5-3. The collection tag of the new item is 'GXPT', but the new item has a collection ID of 20.

When you add this item to the collection, the Collection Manager assigns it a tag list position, reflecting its position in the list of items with the same collection tag. This tag list position can change if you add a new item with the same collection tag. For example, the call

anErr = AddCollectionItem(pointsAndQuotes, 
                          'GXPT', 15, /* tag and id */
                          sizeof(gxPoint),     /* size */
                          &location); /* data */

adds a new item with the 'GXPT' collection tag and a collection ID of 15. Adding this item can change the tag list position of any other item with the 'GXPT' collection tag.

So far, the example collection contains items of the same size. You can also use the AddCollectionItem function to add items with variable-length data, as shown in Listing 5-4.

Listing 5-4 Adding items with variable-length data to a collection

anErr = AddCollectionItem(pointsAndQuotes, 
                          'QUOT', 0,  /* tag and id */
                          17,  /* size */
                          "Le plus ca change");  /* data */

anErr = AddCollectionItem(pointsAndQuotes, 
                          'QUOT', 1, 
                          29, "Fourscore and seven years ago");

anErr = AddCollectionItem(pointsAndQuotes, 
                          'QUOT', 2,
                          18, "It's not the heat.");

The sample code from Listing 5-4 adds three new items to the example collection. Each of these items, which have collection tag 'QUOT', contains a string of characters as its variable-length data; however, each item contains a string of different length.

Note that the AddCollectionItem function copies the information from the block of memory pointed to by its final parameter into the specified collection item. After adding the item, you can change your copy of the information (the copy that the last parameter points to) without affecting the value of the item's variable-length data.

You can use the CountCollectionItems function to count the number of items in a collection. For example, after the call

totalItems = CountCollectionItems(pointsAndQuotes);

the totalItems variable contains the value 15 (12 items with points and 3 items with quotes).

You can use the CountTaggedCollectionItems function to count the number of items in a collection that have a specified collection tag. For example, after the call

quotedItems = CountTaggedCollectionItems(pointsAndQuotes, 'QUOT');

the quotedItems variable contains the value 3.

For more information about the AddCollectionItem function, see page 5-62.

For more information about the CountCollectionItems and CountTaggedCollectionItems functions, see "Counting Items in a Collection" beginning on page 5-69.