NAME

DgAddObjToGroup − Add an object to a specified group

SYNOPSIS

C:

void DgAddObjToGroup(group,object)
DtObject group;
DtObject object;

FORTRAN:

CALL DGAOG(GROUP,OBJECT)
INTEGER∗4 GROUP
INTEGER∗4 OBJECT

DESCRIPTION

DgAddObjToGroup adds an object, object, to the specified group, group.  The object is inserted into the group at the position indicated by the element pointer, and the element pointer moves forward one position so that it points after the object just inserted.  Any objects that follow the element pointer also move forward. 

The most common way to call the DgAddObjToGroup function is:

 DgAddObjToGroup(group,DoXXXX());
 

where the DoXXXX() call creates and returns an object of type XXXX.  The object is added to the designated group through the DgAddObjToGroup call.  One can also create an object through a separate call to a DoXXXX routine and then call the DgAddObjToGroup routine with the object directly:

 object = DoXXXX();
DsHoldObj(object);
DgAddObjToGroup(group,object);
 

One may also call this function in the following manner:

 DgAddObjToGroup(group,DsHoldObj(object=DoXXXX()));
 

This causes object to take the value of the newly created object and places the object in the specified group. 

The call to DsHoldObj is needed only if the user also wants to use the created object for other purposes.  Any object held with DsHoldObj will not be deleted. The application program is always responsible for reclaiming storage from held objects that become obsolete. 

ERRORS

DgAddObjToGroup will fail if called with an invalid group. 

[WARNING - invalid group handle]

DgAddObjToGroup will fail if called with an invalid object. 

[WARNING - invalid or deleted object]

SEE ALSO

DgAddObj(3D), DgInqOpen(3D), DgOpen(3D), DoGroup(3D), DoInLineGroup(3D), DsHoldObj(3D)

September 02, 1992