NAME

DoGroup − Create a group organizational object

SYNOPSIS

C:

DtObject DoGroup(open)
DtFlag open;

FORTRAN:

INTEGER∗4 DOG(OPEN)
INTEGER∗4 OPEN

DESCRIPTION

DoGroup creates a new group organizational object.  A group is an organizational object that contains other objects called the elements of the group.  A group can be thought of as a simple list.  The parameter open determines whether the group is created open, i.e., whether the group is available for edit.  Groups are edited using the following functions: DgAddObj <DGAO>, DgAddObjToGroup <DGAOG>, DgReplaceObj <DGRO>, DgReplaceObjInGroup <DGROG>, DgDelEleBetweenLabels <DGDEL>, DgDelEle <DGDE>, and DgDelEleRange <DGDER>.  An existing group can be opened with DgOpen <DGO>. 

An element pointer is used by many of the editing functions to designate the element(s) to be edited.  There is one element pointer per group, and it remembers its last location.  Label objects also may be used within the group to identify key objects for some editing functions  (see DoLabel).  The application should close a group when it has finished editing the group (see DgClose). 

Groups can contain other groups, allowing an application to construct hierarchies of groups to match the hierarchical structure of the application model.  A single group may be a child group of more than one group; i.e., the same group may be instanced in several places.  Each time the group is instanced, it inherits the current attributes wherever it is instanced. 

When one group references another group, the referenced group starts with a complete set of the current appearance and geometric attributes of the referencing group.  The referenced group may add its own geometric transformations or appearance attributes for its own primitive objects and then pass the new set of attributes on to any groups it references. 

There are two kinds of groups, regular groups and inline groups; these differ only in the way they inherit attributes. 

In a regular group, a copy of all attributes is saved upon entering the group and restored when execution of the group terminates.  This pushing and popping of attributes directs inheritance in one direction only; attributes changed within a referenced group do not affect the attributes of the referencing group. 

Inline groups, created with DoInLineGroup <DOILG>, are slightly different. They do not push and pop the current attributes upon entry and exit.  Changes made to attributes by an inline group have the same effect as if they had been placed directly in the calling group.  The inline group thus provides a mechanism for defining a commonly used set of attributes once and

A group network consists of a group and all the groups referenced, either directly or indirectly, by that group.  Group networks can be very complex; nothing prevents them from including arbitrary cyclic or recursive references.  These recursive references are not supported and should be avoided by the application because they cause unpredictable and often fatal results (see DgCheck).  then using the set multiple times. 

SEE ALSO

DgAddObj(3D), DgAddObjToGroup(3D), DgCheck(3D), DgClose(3D), DgDelEle(3D), DgDelEleBetweenLabels(3D), DgDelEleRange(3D), DgEmpty(3D), DgInqElePtr(3D), DgInqSize(3D), DgInqObjAtPos(3D), DgInqOpen(3D), DgOpen(3D), DgReplaceObj(3D), DgSetElePtr(3D), DgSetElePtrRelLabel(3D), DoInLineGroup(3D), DoLabel(3D)

September 02, 1992