Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 5 - Collection Manager / Collection Manager Reference

Functions / Flattening and Unflattening a Collection

FlattenCollection

You can use the FlattenCollection function to convert a collection object into a stream format suitable for storing and unflattening. For example, you could use this function to copy a collection onto the Clipboard so that it could be pasted into another application.

OSErr FlattenCollection(Collection source,
                        CollectionFlattenProc flattenProc,
                        void *refCon);

source

A reference to the collection that you want to flatten.

flattenProc

A pointer to a callback function you provide to process the flattened stream of bytes.

refCon

A reference constant that you want the Collection Manager to pass repeatedly to the callback function.

DESCRIPTION

The FlattenCollection function flattens into a stream of bytes the collection you specify with the source parameter. As this function flattens the collection, it repeatedly calls the callback function you specify using the flattenProc parameter. Each time it calls this function, it provides the callback function with a pointer to a block of memory containing flattened data. It continues to call this function until it has flattened the entire collection. Your callback function can process the flattened data in a number of ways: it could copy the flattened data into a handle-based block of memory, it could write the flattened data to disk, and so on.

In the refCon parameter, you specify a value that the Collection Manager passes on to your callback function each time it calls your callback function. You can use this parameter as a pointer to a structure containing information your callback function needs to process the blocks of flattened data.

When flattening the source collection, this function includes only the collection items whose persistence attribute is set.

This function can return any error returned by the callback function.

SEE ALSO

For information about the persistence attribute, see "Collection Items" beginning on page 5-8.

For information about the callback function that you provide, see page 5-100.

For examples of this function, see "Flattening and Unflattening a Collection" beginning on page 5-37 and "Reading Collections From and Writing Collections to Disk" beginning on page 5-41.

To create a flattened collection that includes only those collection items whose attributes match a specified pattern, use the FlattenPartialCollection function, described in the next section.

To unflatten a flattened collection, use the UnflattenCollection function, described on page 5-90.