GenClass: 5 Generic Trees

GEOS SDK TechDocs

4 Modifying GenClass Instance Data

6 Vardata

Generic trees are constructed in several ways. The most common is to add, remove, and move individual children. These children may be the top of a generic branch and will therefore add, remove, or move the entire branch below them. GenClass also provides other means of manipulating entire branches of generic trees. Each manner of generic tree construction and destruction has certain advantages and disadvantages. The various methods are detailed below:

• The object may be declared in the .goc file, attached to the generic tree. In this case, there is no need to add the child as this is taken care of by the compiler. You can remove the object and any of its children with MSG_GEN_REMOVE (or MSG_GEN_REMOVE_CHILD ). After removal, any single object may be destroyed with MSG_META_OBJ_FREE . You may also destroy a tree of generic objects with MSG_GEN_DESTROY . You may add the removed object (and its children) to a different location in the generic tree with MSG_GEN_ADD_CHILD .
• The object may exist in your .goc file but remain unattached to the generic tree. You may attach the object with MSG_GEN_ADD_CHILD . You can remove the object, and any children of this object, with MSG_GEN_REMOVE (or MSG_GEN_REMOVE_CHILD ). After removal, destroy any single object with MSG_META_OBJ_FREE . You can destroy a tree of generic objects with MSG_GEN_DESTROY .
• ObjInstantiate(), ObjInstantiateForThread()
These routines create a new instance of a single object. You can then add the object to your generic tree with MSG_GEN_ADD_CHILD . After a child is removed using MSG_GEN_REMOVE (or MSG_GEN_REMOVE_CHILD ), it can be destroyed using MSG_META_OBJ_FREE . The object destroyed in such a manner must not have any children attached to it at the time of destruction.
• ObjDuplicateResource()
This routine duplicates an instance of a previously defined object resource. That object block may contain one or more objects. In your .gp file, make sure the resource is marked discard-only . Only use this routine if you want to duplicate an instance of a predefined resource block. After a block duplicated in this manner is removed using MSG_GEN_REMOVE (or MSG_GEN_REMOVE_CHILD ), it can be destroyed using ObjFreeDuplicate() .
• MSG_GEN_COPY_TREE
  This message copies an entire generic branch headed by the recipient. The branch will be set usable and added automatically without need for a MSG_GEN_ADD_CHILD . A generic branch created in this manner can be removed with MSG_GEN_DESTROY . These messages are useful because they can duplicate and destroy generic trees across object blocks. (The copied branch will reside in one block, however.)

Objects created in these ways must be added using MSG_GEN_ADD_CHILD (except for those created with MSG_GEN_COPY_TREE ).

• MSG_GEN_ADD_CHILD
  This message adds a generic object that was previously created but not attached to the generic tree. The object may have been created in your .goc file but not attached as a child of any other object. The object may also have been created through ObjInstantiate() or ObjInstantiateForThread() or with ObjDuplicateResource() (see above). Use MSG_GEN_REMOVE (or MSG_GEN_REMOVE_CHILD ) to remove a child added in this manner.

Child/Parent Searches

Manipulating Children Directly

Branch Construction/Destruction

GEOS SDK TechDocs

4 Modifying GenClass Instance Data

6 Vardata