GenClass: 3.2 GenClass Basics: Composite Links

| Up: GEOS SDK TechDocs | Up | Prev: 3.1 Visual Monikers | Next: 3.3 Keyboard Accelerators

Composite links form the connections between parent objects and child objects within a generic tree (see the UI Overview). These links are set up using the GI_comp and GI_link instance fields. The GI_comp field points to an object's first child. The GI_link field points to an object's next sibling or to its parent if no next sibling exists. In Goc, however, this usage is greatly simplified. The developer only needs to set the GI_comp field equal to its complete list of children for the parent object. The Goc preprocessor will then create and reassign all necessary links.

Code Display 2-13 Using GI_comp to Add Children

/* The GenInteraction (MyInteraction) acts as the parent object for the three
 * child GenTriggers. All three GenTrigger children will be placed within the
 * GenInteraction object. */
@object GenInteractionClass MyInteraction = {
    GI_visMoniker = "Menu";						 /* Text Moniker */
    GII_visibility = GIV_POPUP;						 /* Creates a Menu */
    GI_comp = @MyFirstChild, @MySecondChild, @MyThirdChild;
						/* list of children */
}
@object GenTriggerClass MyFirstChild= {
    GI_visMoniker = "Child 1";					/* Text Moniker */
}
@object GenTriggerClass MySecondChild = {
    GI_visMoniker = "Child 2";					/* Text Moniker */
}
@object GenTriggerClass MyThirdChild = {
    GI_visMoniker = "Child 3";					/* Text Moniker */
}

This simple functionality is all you need to know to add children to your generic objects (and thus to create generic trees). However, it is somewhat helpful in certain cases (as in debugging) to understand what takes place underneath the surface. When an object in GEOS is assigned children, the preprocessor actually only assigns one composite link ( GI_comp ) to the first child. Each additional child acquires a link from its previous sibling using the internal instance field GI_link . Therefore, the parent will have a GI_comp to its first child, the first child will have a GI_link to the next sibling (the parent's second child) and so forth. The last sibling (the parent's last child) will have a GI_link back to the parent. This GI_link will have the LF_IS_PARENT bit set to indicate that the child points to a parent and not to a sibling. This forms what amounts to a circular linked list rather than a branching tree structure. (See the figure below.)

This structure provides a simple and convenient usage. Any object will always have at most two links to other children or parent objects. Therefore the two instance fields GI_comp and GI_link provide the entire means of constructing a generic tree.

You can travel anywhere in the generic tree through these two links. For example, for MyInteraction to communicate with MyThirdChild, it follows the path of the GI_comp to the first child, MyFirstChild, and then continues through the two GI_link s to the third child. Conversely, a child can reach a parent by travelling along the GI_link s of siblings until it reaches the last sibling, whose GI_link points to its parent object.

GenClass message handlers provide several means of pointing to the proper parent/child object without needing to explicitly state the proper GI_comp and GI_link paths. In practice, you will never need to, and in fact should not, manipulate the GI_link field at all. This information is provided merely for your use in debugging your applications. In fact, you can usually assume that a conventional branching tree structure exists rather than the linked-list tree structure shown here.

For information on manipulating these links dynamically using GenClass messages, see Generic Trees .

| Up: GEOS SDK TechDocs | Up | Prev: 3.1 Visual Monikers | Next: 3.3 Keyboard Accelerators