6.1.1 csObject

The csObject class can be used to build object hierarchies. It supports building a simple tree structure. To use this functionality, you should derive your classes from csObject. csObject implements the iObject interface and can store any number of iObject children. Furthermore, every csObject has a name.

All child objects are IncRef'ed when added and DecRef'ed when removed. An object also stores a pointer to its parent (which is not reference-counted to avoid circular references). Note that this pointer will always point to the last parent if the object is added to more than one parent. When the object is removed from a parent, the pointer is set to 0, even if the object is still a child of another parent!

Although the children of an object are only available as iObject's, you can use SCF_QUERY_INTERFACE to query other interfaces from them. Some convenience macros are also available:

CS_GET_CHILD_OBJECT(object,Interface)

Get the first child object that implements the given interface.

CS_GET_NAMED_CHILD_OBJECT(object,Interface,name)

Get the first child object with the given name that implements the given interface. This will continue to search through the objects if an object with the right name but not the right interface was found, i.e. it handles multiple objects with the same name correctly.

CS_GET_FIRST_NAMED_CHILD_OBJECT(object,Interface,name)

Same as the above but stops at the first object with the given name, even if it does not implement the requested interface (in that case, 0 is returned). This is slightly faster.

Note that there are a few HOWTO's describing possible uses for the csObject system (see section 5.8.13 Attaching User Objects to CS Objects and see section 5.8.14 Attaching User Objects to CS Objects in a map file).