9

---

CDBA Parent-Child Relationship Functions

---

The parent-child relationship allows database objects in the same cellview to be tightly coupled together. The tight coupling lets the database support propagation of operations (such as move, copy, and delete) that, when acting on a parent, act on all the parent’s descendants (“children”) as well.

The MatchPointLists relationship can exist between a parent and its descendants. When this relationship exists, the parent’s graphical points are the same as all the points of its descendants. If the parent has its points modified, then the descendants’ points are modified too. Also, a matching child cannot be operated on (moved, copied, or deleted) by itself. The matching ancestor must be operated on instead.

• Limitations
• Retrieval and Traversal Operations
• Predicates
• Creation and Deletion Operations
• Other CDBA Functions Affected

Limitations

The following sections describe limitations to the parent-child relationship.

Allowed Database Objects

Currently, only figures (except mosaics) can be children. Parents are limited to figures (shapes, instances, and mosaics).

Uniqueness

A parent can have any number of children. However, a child can have only one parent.

Grandchildren/Descendants

Children can themselves be parents, allowing for n levels of hierarchy in the parent-child relationship. No cycles are allowed in the parent-child hierarchy.

Matching Points

The MatchPointLists constraint can be applied to two-point shapes (that is rectangles, implying that all descendants have to be rectangles) and multiple-point shapes such as path, line, and polygon. (Descendants can be any of path, line, or polygon to be compatible.)

Retrieval and Traversal Operations

The following functions traverse the hierarchy to retrieve and change information about parent-child relationships for a figure.

dbStartGenChild

dbGenStateId

dbStartGenChild(
dbId parentId
);

Starts the generator for all immediate children of a parent.

dbGenChild

Boolean

dbGenChild(
dbGenStateId stateId, dbId pChildId
);

Generates all immediate children of a parent. When no more children exist for the parent, the functions return FALSE.

dbGetParent

dbId

dbGetParent(
dbId childId
);

Returns the parent of the child object specified by childId. If the object specified by childId does not have a parent, the function returns dbcNullId.

Predicates

The following functions retrieve predicate (Boolean) information about parent-child relationships.

dbIsParent

Boolean

dbIsParent(
dbId parentId
);

Returns TRUE if the object specified by parentId is a parent of one or more children. Otherwise, it returns FALSE.

dbIsChild

Boolean

dbIsChild(
dbId childId
);

Returns TRUE if the object specified by childId is the child of some parent. Otherwise, it returns FALSE.

dbIsChildOfParent

Boolean

dbIsChildOfParent(
dbId childId, dbId parentId
);

Returns TRUE if the object specified by childId is a child of the object specified by parentId. Otherwise, the returns FALSE.

dbIsParentOfChild

Boolean

dbIsParentOfChild(
dbId parentId, dbId childId
);

Returns TRUE if the object specified by parentId is the parent of the object specified by childId. Otherwise, the function returns FALSE.

dbHasMatchPointLists

Boolean

dbHasMatchPointLists(
dbId parentId
);

Returns TRUE if the object specified by parentId has the MatchPointLists constraint. Otherwise, the function returns FALSE.

Creation and Deletion Operations

The following functions retrieve and change information about parent-child relationships a figure.

dbAddChildToParent

Boolean

dbAddChildToParent(
dbId childId, dbId parentId
);

Adds a parent-child relationship to a database object specified by childId, which is the child of the object specified by parentId. FALSE is returned if the relationship cannot be built.

dbSubChildFromParent

Boolean

dbSubChildFromParent(
dbId childId, dbId parentId
);

Removes a child relationship from the object specified by parentId to the object specified by childId. FALSE is returned if there are problems removing the relationship.

dbMatchPointLists

Boolean

dbMatchPointLists(
dbId parentId
);

Checks all the descendants of a parent. If all the points match, the function adds the MatchPointLists constraint to the parent and all its descendants. If successful, the function returns TRUE. Otherwise, the function returns FALSE. Any children added to any parent with the MatchPointLists constraint must match points before they can be added.

An application might require that all the points of a parent figure, specified by parentId, have the same points as all the descendants of that parent. This means that the number of points for the descendants must be the same as the parent, in addition to the coordinates themselves matching.

dbUnmatchPointLists

Boolean

dbUnmatchPointLists(
dbId parentId
);

Removes the MatchPointLists constraint (that is, all descendants of a parent specified by parentId must match the parent’s points). The routine returns TRUE if the constraint is removed properly. Otherwise, the function returns FALSE.

Other CDBA Functions Affected

See the descriptions of the following functions for more information regarding parent-child relationships:

• dbStartGenFig and dbGenFig
• dbStartGenNonChildFig and dbGenNonChildFig
• dbStartGenLPToShape
• dbGenLPToShape
• dbStartGenLPToNonChildShape
• dbGenLPToNonChildShape
• dbStartGenShape
• dbGenShape
• dbStartGenNonChildShape
• dbGenNonChildShape
• dbCopyFig
• dbCopyShape
• dbMoveFig
• dbMoveShape
• dbDeleteFig
• dbDeleteShape
• dbDeleteInst
• dbDeleteMosaic
• dbSetPolygonPoint
• dbSetPathPoint
• dbSetLinePoint
• dbSetRectBBox
• dbConvertRectToPolygon
• dbConvertPolygonToRect
• dbConvertPathToPolygon

Return to top