NAME

DgReplaceObjInGroup − Replace an object in a specified group

SYNOPSIS

C:

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

FORTRAN:

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

DESCRIPTION

DgReplaceObjInGroup places the object, object, in the specified group, group.  If the group’s element pointer is not at the end of the group, the object replaces the object immediately following the group’s element pointer.  If the group’s element pointer is after the last element in the group, the object is appended to the end of the group. In both cases the element pointer remains pointing at the element just replaced or inserted; i.e., the element pointer never moves. 

The most common way to call the DgReplaceObjInGroup function is:

 DgReplaceObjInGroup(group, DoXXXX());
 

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

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

One may also call this function in the following manner:

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

object would then contain a handle to the newly created object and the object would be a member of group. 

The call to DsHoldObj is needed only if the user also wants to use the object created for other purposes.  Note that any object held with DsHoldObj <DSHO> will not be deleted.  The application program is always responsible for reclaiming storage from held objects that are no longer needed. 

ERRORS

DgReplaceObjInGroup will fail if the group handle is invalid. 

[WARNING - invalid group handle]

DgReplaceObjInGroup will fail if passed an invalid object. 

[WARNING - invalid or deleted object]

SEE ALSO

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

September 02, 1992