Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Using the Collection Manager

Getting and Setting the Attributes of an Item

The Collection Manager provides three functions that allow you to examine the attributes of a collection item:

• The GetCollectionItemInfo function requires that you specify the collection tag and ID of the desired item.
• The GetIndexedCollectionItemInfo function requires that you specify the collection index of the desired item.
• The GetTaggedCollectionItemInfo function requires that you specify the collection tag and tag list position of the desired item.

The Collection Manager provides two functions that allow you to edit the attributes of an item:

• The SetCollectionItemInfo function requires that you specify the collection tag and ID of the desired item.
• The SetIndexedCollectionItemInfo function requires that you specify the collection index of the desired item.

(There is no SetTaggedCollectionItemInfo function to correspond to the GetTaggedCollectionItemInfo function.)

The three information-retrieving functions allow you to determine a variety of information about the item--not just its attributes. You can find more information about the other values returned by these functions in "Determining the Collection Index of an Item" beginning on page 5-19, "Determining the Tag and ID of an Item" beginning on page 5-21, and "Determining the Size of an Item's Variable-Length Data" beginning on page 5-22.

The information-editing functions, however, allow you to edit the attributes of only the specified item. (You cannot, for instance, use these functions to change the index of an item, or the size of its variable-length data.)

Listing 5-8 shows how you can use the GetCollectionItemInfo function to examine the attributes of an item given the item's collection tag and collection ID. This listing uses the collection defined in "Adding Items to a Collection" beginning on page 5-17.

Listing 5-8 Examining the attributes of an item

long attributes;
.
.
.
anErr = GetCollectionItemInfo(pointsAndQuotes, /* collection */
                              'QUOT', 0,  /* tag and id */
                              dontWantIndex, 
                              dontWantSize,
                              &attributes); /* returned attr's */

After this call to the GetCollectionItemInfo function, the attributes variable contains a copy of the attributes of item from the pointsAndQuotes collection with the collection tag 'QUOT' and a collection ID of 0. You can examine specific attributes using the attribute bit masks, which are described in "Attribute Bit Masks" beginning on page 5-52. As an example, the expression

(attributes & collectionLockMask)

evaluates to false (0) if the lock attribute is not set and to true (not 0) if the lock attribute is set.

You can also use the GetIndexedCollectionItemInfo function to examine the attributes of an item, given its collection index rather than its collection tag and collection ID:

anErr = GetIndexedCollectionItemInfo(pointsAndQuotes, 
                                     index, /* index of item */
                                     dontWantTag,  
                                     dontWantId,
                                     dontWantSize, 
                                     &attributes); /* returned */

Similarly, you can use the GetTaggedCollectionItemInfo function to examine the attributes of an item, given its collection tag and tag list position:

anErr = GetTaggedCollectionItemInfo(pointsAndQuotes, 
                                    'QUOT',  /* tag of item */
                                    1,  /* tag list position */  
                                    dontWantId,
                                    dontWantIndex,
                                    dontWantSize, 
                                    &attributes);  /* returned */

You can edit the attributes of a collection item using the SetCollectionItemInfo and SetIndexedCollectionItemInfo functions. These functions require you to specify which attributes you want to edit and what the new values for those attributes should be.

You specify this information using two long parameters:

• The first is a mask. Each bit in this mask represents one of the item's attributes. A bit value of 0 in this mask signifies that you do not want to edit the corresponding attribute of the specified item. A bit value of 1 in this mask signifies that you do want to edit the corresponding attribute of the item.
• The second contains the new values. Each bit in this parameter represents the new value for the corresponding attribute of the item. Only the bits in this parameter that correspond to bits in the mask parameter that have a value of 1 are significant. The Collection Manager ignores the other bit values in this parameter.

Listing 5-9 shows how you can use the SetCollectionItemInfo to set the lock and persistence attributes of a collection item and clear all the other attributes.

Listing 5-9 Setting the lock and persistence bit attribute of an item

long newAttributes;
.
.
.
newAttributes = collectionLockMask
                | collectionPersistenceMask;

anErr = SetCollectionItemInfo(pointsAndQuotes,
                              'QUOT', 0, /* tag and id */
                              allCollectionAttributes, /* mask */
                              newAttributes); /* new values */

This example uses the allCollectionAttributes constant (which is defined in "Attributes Masks" beginning on page 5-49) to indicate that all the attributes of the specified collection item should be edited. As a result, the code in the example replaces the value of every attribute in the specified collection item with the corresponding value from the newAttributes parameter.

If you want to set the lock and persistence attributes of this collection item without affecting the values of the other attributes, you can use the newAttributes variable as both the mask and the values parameters:

anErr = SetCollectionItemInfo(pointsAndQuotes,
                              'QUOT', 0, /* tag and id */
                              newAttributes, /* mask */
                              newAttributes); /* new values */

In this case, the code uses the newAttributes parameter as the mask (which indicates that only the lock attribute and the persistence attribute should be affected) as well as the values (which indicate that both of these attributes should be set). The values of all the other attributes of the specified item remain as they were before the call.

You can also use the SetIndexedCollectionItemInfo function to set the attributes of an item, given the item's collection index rather than its collection tag and collection ID:

anErr = SetIndexedCollectionItemInfo(pointsAndQuotes,
                                     index,
                                     allCollectionAttributes,
                                     newAttributes);

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

For more information about the GetCollectionItemInfo, GetIndexedCollectionItemInfo, and GetTaggedCollectionItemInfo functions, see "Getting Information About a Collection Item" beginning on page 5-76.

For more information about the SetCollectionItemInfo and SetIndexedCollectionItemInfo functions, see "Editing Item Attributes" beginning on page 5-82.