Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager

Summary of the Collection Manager

Data Types

Optional Return Value Constants

enum {
   dontWantTag          = 0L,  /* don't want collection tag returned */
   dontWantId           = 0L,  /* don't want collection ID returned */
   dontWantSize         = 0L,  /* don't want size of data returned */
   dontWantAttributes   = 0L,  /* don't want attributes returned */
   dontWantIndex        = 0L,  /* don't want collection index returned */
   dontWantData         = 0L   /* don't want variable-length data returned */
};

Attributes Masks

enum {
   noCollectionAttributes      = 0x00000000,  /* no attributes bits set */
   allCollectionAttributes     = 0xFFFFFFFF,  /* all attributes bits set */
   userCollectionAttributes    = 0x0000FFFF,  /* user attributes bits set */
   defaultCollectionAttributes = 0x40000000   /* unlocked, persistent */
};

Attribute Bit Numbers

enum {
   collectionUser0Bit   = 0,  /* for use by application */
   collectionUser1Bit   = 1,
   collectionUser2Bit   = 2,
   collectionUser3Bit   = 3,
   collectionUser4Bit   = 4,
   collectionUser5Bit   = 5,
   collectionUser6Bit   = 6,
   collectionUser7Bit   = 7,
   collectionUser8Bit   = 8,
   collectionUser9Bit   = 9,
   collectionUser10Bit  = 10,
   collectionUser11Bit  = 11,
   collectionUser12Bit  = 12,
   collectionUser13Bit  = 13,
   collectionUser14Bit  = 14,
   collectionUser15Bit  = 15,
   
   collectionReserved0Bit  = 16,  /* reserved for use by Apple */
   collectionReserved1Bit  = 17,
   collectionReserved2Bit  = 18,
   collectionReserved3Bit  = 19,
   collectionReserved4Bit  = 20,
   collectionReserved5Bit  = 21,
   collectionReserved6Bit  = 22,
   collectionReserved7Bit  = 23,
   collectionReserved8Bit  = 24,
   collectionReserved9Bit  = 25,
   collectionReserved10Bit = 26,
   collectionReserved11Bit = 27,
   collectionReserved12Bit = 28,
   collectionReserved13Bit = 29,
   
   collectionPersistenceBit = 30,  /* currently defined by Apple */
   collectionLockBit        = 31
};

Attribute Bit Masks

enum {
   collectionUser0Mask = 1L << collectionUser0Bit,
   collectionUser1Mask = 1L << collectionUser1Bit,
   collectionUser2Mask = 1L << collectionUser2Bit,
   collectionUser3Mask = 1L << collectionUser3Bit,
   collectionUser4Mask = 1L << collectionUser4Bit,
   collectionUser5Mask = 1L << collectionUser5Bit,
   collectionUser6Mask = 1L << collectionUser6Bit,
   collectionUser7Mask = 1L << collectionUser7Bit,
   collectionUser8Mask = 1L << collectionUser8Bit,
   collectionUser9Mask = 1L << collectionUser9Bit,
   collectionUser10Mask = 1L << collectionUser10Bit,
   collectionUser11Mask = 1L << collectionUser11Bit,
   collectionUser12Mask = 1L << collectionUser12Bit,
   collectionUser13Mask = 1L << collectionUser13Bit,
   collectionUser14Mask = 1L << collectionUser14Bit,
   collectionUser15Mask = 1L << collectionUser15Bit,

   collectionReserved0Mask = 1L << collectionReserved0Bit,
   collectionReserved1Mask = 1L << collectionReserved1Bit,
   collectionReserved2Mask = 1L << collectionReserved2Bit,
   collectionReserved3Mask = 1L << collectionReserved3Bit,
   collectionReserved4Mask = 1L << collectionReserved4Bit,
   collectionReserved5Mask = 1L << collectionReserved5Bit,
   collectionReserved6Mask = 1L << collectionReserved6Bit,
   collectionReserved7Mask = 1L << collectionReserved7Bit,
   collectionReserved8Mask = 1L << collectionReserved8Bit,
   collectionReserved9Mask = 1L << collectionReserved9Bit,
   collectionReserved10Mask = 1L << collectionReserved10Bit,
   collectionReserved11Mask = 1L << collectionReserved11Bit,
   collectionReserved12Mask = 1L << collectionReserved12Bit,
   collectionReserved13Mask = 1L << collectionReserved13Bit,

   collectionPersistenceMask = 1L << collectionPersistenceBit,
   collectionLockMask = 1L << collectionLockBit
};

Functions

Creating and Disposing of Collection Objects

Collection NewCollection	(void);
void DisposeCollection		(Collection target);

Cloning and Copying Collection Objects

Collection CloneCollection	(Collection target);
long CountCollectionOwners	(Collection source);
Collection CopyCollection	(Collection source,
				Collection target);

Getting and Setting the Exception Procedure for a Collection

CollectionExceptionProc GetCollectionExceptionProc
		(Collection source);
void SetCollectionExceptionProc
		(Collection target,
		CollectionExceptionProc newExceptionProc);

Getting and Setting the Default Attributes for a Collection

long GetCollectionDefaultAttributes
		(Collection source);
void SetCollectionDefaultAttributes
		(Collection target,
		long whichAttributes, 
		long newAttributes);

Adding and Replacing Items in a Collection

OSErr AddCollectionItem	(Collection target,
			CollectionTag tag, long id,
			long itemSize, void *itemData);
			OSErr ReplaceIndexedCollectionItem 
			(Collection target, long index,
			long itemSize, void *itemData);

Removing Items From a Collection

OSErr RemoveCollectionItem	(Collection target, 
				CollectionTag tag, long id);
OSErr RemoveIndexedCollectionItem
			(Collection target, long index);
void PurgeCollection	(Collection target,
			long whichAttributes,
			long matchingAttributes);
			void PurgeCollectionTag(Collection target, CollectionTag tag);
			void EmptyCollection (Collection target);

Counting Items in a Collection

long CountCollectionItems	(Collection source);
long CountTaggedCollectionItems
				(Collection source, CollectionTag tag);

Retrieving the Variable-Length Data From an Item

OSErr GetCollectionItem	(Collection source,
			CollectionTag tag, long id,
			long *itemSize, void *itemData);
OSErr GetIndexedCollectionItem
			(Collection source, long index,
			long *itemSize, void *itemData);
OSErr GetTaggedCollectionItem
			(Collection source,
			CollectionTag tag, long position,
			long *itemSize, void *itemData);

Getting Information About a Collection Item

OSErr GetCollectionItemInfo(Collection source,
			CollectionTag tag, long id,
			long *index, long *itemSize,
			long *attributes);
OSErr GetIndexedCollectionItemInfo
			(Collection source, long index,
			CollectionTag *tag, long *id,
			long *itemSize, long *attributes);
OSErr GetTaggedCollectionItemInfo
			(Collection source,
			CollectionTag tag, long position,
			long *id, long *index,
			long *itemSize, void *attributes);

Editing Item Attributes

OSErr SetCollectionItemInfo
			(Collection target,
			CollectionTag tag, long id,
			long whichAttributes, long newAttributes);
OSErr SetIndexedCollectionItemInfo
			(Collection target, long index,
			long whichAttributes, long newAttributes);

Getting Information About Collection Tags

Boolean CollectionTagExists
			(Collection source, CollectionTag tag);
			long CountCollectionTags(Collection source);
OSErr GetIndexedCollectionTag
			(Collection source, long whichTag,
			CollectionTag *tag);

Flattening and Unflattening a Collection

OSErr FlattenCollection	(Collection source,
			CollectionFlattenProc flattenProc,
			void *refCon);
OSErr FlattenPartialCollection
			(Collection source,
			CollectionFlattenProc flattenProc,
			void *refCon,
			long whichAttributes, 
			long matchingAttributes);
OSErr UnflattenCollection	(Collection target,
				CollectionFlattenProc flattenProc,
				void *refCon);

Working With Macintosh Memory Manager Handles

OSErr AddCollectionItemHdl	(Collection target,
				CollectionTag tag, long id,
				Handle itemData);
OSErr ReplaceIndexedCollectionItemHdl
				(Collection target, long index,
				Handle itemData);
OSErr GetCollectionItemHdl	(Collection source,
				CollectionTag tag, long id,
				Handle itemData);
OSErr GetIndexedCollectionItemHdl
				(Collection source, long index,
				Handle itemData);
OSErr FlattenCollectionToHdl
				(Collection source, Handle flattened);
OSErr UnflattenCollectionFromHdl 
				(Collection target, Handle flattened);

Reading Collections From Resource Files

Collection GetNewCollection	(short collectionID);

Application-Defined Functions

OSErr MyFlattenProc	(long size, void *data, void *refCon);
OSErr MyExceptionProc	(Collection target, OSErr whichErr);

Resources

The Collection Resource

type 'cltn' {
	longint = $$CountOf(ItemArray);
	array ItemArray
		{
		longint		; /* tag */
		longint		; /* id */
			boolean			itemUnlocked			 =	 false,	 /* defined attributes */
						itemLocked			 =	 true;
			boolean			itemNonPersistent		 =	 false,
						itemPersistent 			= true;
			unsigned bitstring[14] = 0;						 /* reserved attributes */
			unsigned bitstring[16] userBits; 				/* user attributes */
		wstring;
		align word;
	};
};