CFTree Reference

Overview

You use CFTree to create tree structures that represent hierarchical organizations of information. In such structures, each tree node has exactly one parent tree (except for the root tree, which has no parent) and can have multiple children. Each CFTree object in the structure has a context associated with it; this context includes some program-defined data as well as callbacks that operate on that data. The program-defined data is often used as the basis for determining where CFTree objects fit within the structure. All CFTree objects are mutable.

You create a CFTree object using the CFTreeCreate function. This function takes an allocator and pointer to a CFTreeGetContext structure as parameters. The CFTreeContext structure contains the program-defined data and callbacks needed to describe, retain, and release that data. If you do not implement these callbacks, your program-defined data will not be retained or released when trees are added and removed from a parent.

Each CFTree object has a parent and list of children, all of which may be NULL. CFTree provides functions for adding and removing tree objects from the tree structure. Use the CFTreeAppendChild, CFTreeInsertSibling, or CFTreePrependChild functions to add trees to a tree structure, and the CFTreeRemove or CFTreeRemoveAllChildren functions to remove trees.

For the purposes of memory management, CFTree can be thought of as a collection. Typically the only object that retains a child tree is its parent. Usually, therefore, when you remove a child tree from a tree, the child tree is destroyed. If you want to use a child tree after you remove it from its parent, you should retain the child tree first, prior to removing it.

Releasing a tree releases its child trees, and all of their child trees (recursively). Note also that the final release of a tree (when its retain count decreases to zero) causes all of its child trees, and all of their child trees (recursively), to be destroyed, regardless of their retain counts. Releasing a child that is still in a tree is therefore a programming error, and may cause your application to crash.

You can use any of the get functions (functions containing the word “Get”) to obtain the parent, children, or attributes of a tree. For example, use CFTreeGetChildAtIndex to obtain a child of a tree at a specified location. In common with other Core Foundation “Get” functions, these functions do not retain the tree that is returned. If you are making other modifications to the tree, you should either retain or make a deep copy of the child tree returned.

You can apply a function to all children of a tree using the CFTreeApplyFunctionToChildren function, and sort children of a tree using the CFTreeSortChildren function.

Functions by Task

Creating Trees

• CFTreeCreate

Modifying a Tree

• CFTreeAppendChild
• CFTreeInsertSibling
• CFTreeRemoveAllChildren
• CFTreePrependChild
• CFTreeRemove
• CFTreeSetContext

Sorting a Tree

• CFTreeSortChildren

Examining a Tree

• CFTreeFindRoot
• CFTreeGetChildAtIndex
• CFTreeGetChildCount
• CFTreeGetChildren
• CFTreeGetContext
• CFTreeGetFirstChild
• CFTreeGetNextSibling
• CFTreeGetParent

Performing an Operation on Tree Elements

• CFTreeApplyFunctionToChildren

Getting the Tree Type ID

• CFTreeGetTypeID

Functions

CFTreeAppendChild

Adds a new child to a tree as the last in its list of children.

void CFTreeAppendChild (
   CFTreeRef tree,
   CFTreeRef newChild
);

CFTreeApplyFunctionToChildren

Calls a function once for each immediate child of a tree.

void CFTreeApplyFunctionToChildren (
   CFTreeRef tree,
   CFTreeApplierFunction applier,
   void *context
);

CFTreeCreate

Creates a new CFTree object.

CFTreeRef CFTreeCreate (
   CFAllocatorRef allocator,
   const CFTreeContext *context
);

CFTreeFindRoot

Returns the root tree of a given tree.

CFTreeRef CFTreeFindRoot (
   CFTreeRef tree
);

CFTreeGetChildAtIndex

Returns the child of a tree at the specified index.

CFTreeRef CFTreeGetChildAtIndex (
   CFTreeRef tree,
   CFIndex idx
);

CFTreeGetChildCount

Returns the number of children in a tree.

CFIndex CFTreeGetChildCount (
   CFTreeRef tree
);

CFTreeGetChildren

Fills a buffer with children from the tree.

void CFTreeGetChildren (
   CFTreeRef tree,
   CFTreeRef *children
);

CFTreeGetContext

Returns the context of the specified tree.

void CFTreeGetContext (
   CFTreeRef tree,
   CFTreeContext *context
);

CFTreeGetFirstChild

Returns the first child of a tree.

CFTreeRef CFTreeGetFirstChild (
   CFTreeRef tree
);

CFTreeGetNextSibling

Returns the next sibling, adjacent to a given tree, in the parent's children list.

CFTreeRef CFTreeGetNextSibling (
   CFTreeRef tree
);

CFTreeGetParent

Returns the parent of a given tree.

CFTreeRef CFTreeGetParent (
   CFTreeRef tree
);

CFTreeGetTypeID

Returns the type identifier of the CFTree opaque type.

CFTypeID CFTreeGetTypeID (
   void
);

CFTreeInsertSibling

Inserts a new sibling after a given tree.

void CFTreeInsertSibling (
   CFTreeRef tree,
   CFTreeRef newSibling
);

CFTreePrependChild

Adds a new child to the specified tree as the first in its list of children.

void CFTreePrependChild (
   CFTreeRef tree,
   CFTreeRef newChild
);

CFTreeRemove

Removes a tree from its parent.

void CFTreeRemove (
   CFTreeRef tree
);

CFTreeRemoveAllChildren

Removes all the children of a tree.

void CFTreeRemoveAllChildren (
   CFTreeRef tree
);

CFTreeSetContext

Replaces the context of a tree by releasing the old information pointer and retaining the new one.

void CFTreeSetContext (
   CFTreeRef tree,
   const CFTreeContext *context
);

CFTreeSortChildren

Sorts the immediate children of a tree using a specified comparator function.

void CFTreeSortChildren (
   CFTreeRef tree,
   CFComparatorFunction comparator,
   void *context
);

Callbacks

CFTreeApplierFunction

Type of the callback function used by the CFTree apply function.

typedef void (*CFTreeApplierFunction) (
   const void *value,
   void *context
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   const void *value,
   void *context
);

CFTreeCopyDescriptionCallBack

Callback function used to provide a description of the program-defined information pointer.

typedef CFStringRef (*CFTreeCopyDescriptionCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

CFStringRef MyCallBack (
   const void *info
);

CFTreeReleaseCallBack

Callback function used to release a previously retained program-defined information pointer.

typedef void (*CFTreeReleaseCallBack) (
   const void *info
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   const void *info
);

CFTreeRetainCallBack

Callback function used to retain a program-defined information pointer.

typedef const void *(*CFTreeRetainCallBack) (
const void *info
);

If you name your function MyCallBack, you would declare it like this:

const void *MyCallBack (
   const void *info
);

Data Types

CFTreeContext

Structure containing program-defined data and callbacks for a CFTree object.

struct CFTreeContext {
   CFIndex version;
   void *info;
   CFTreeRetainCallBack retain;
   CFTreeReleaseCallBack release;
   CFTreeCopyDescriptionCallBack copyDescription;
};
typedef struct CFTreeContext CFTreeContext;

Fields

version

The version number of the structure type being passed in as a parameter to a CFTree creation function. This structure is version 0.

info

A C pointer to a program-defined block of data, referred to as the information pointer.

retain

The callback used to retain the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. This value may be NULL.

release

The callback used to release a previously retained info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. This value may be NULL.

copyDescription

The callback used to provide a description of the info field.

CFTreeRef

A reference to a CFTree object.

typedef struct __CFTree *CFTreeRef;