NAME

DsInqValuatorGroup − Return the handle for an input slot’s valuator group

SYNOPSIS

C:

DtObject DsInqValuatorGroup(slot)
DtObject slot;

FORTRAN:

INTEGER∗4 DSQVG(SLOT)
INTEGER∗4 SLOT

DESCRIPTION

DsInqValuatorGroup returns the handle for an input slot’s valuator group.  A valuator group is part of every input slot.  The valuator group contains the object handles of all the valuator callback objects associated with the input slot. 

When a value arrives at an input slot, all callback objects in its valuator group are triggered in order.  Users are free to edit that group, with the group editing functions, to arrange their valuator callbacks in the order that they want them triggered. 

When an input slot is triggered, all non-callback objects found in its valuator group are ignored and the callback functions that it refers to are called.  Those functions must have the following C format:

 void UserValuatorFunction(data, slot, value)
DtPtr data;/∗ if data is a pointer ∗/
Dt32Bits data;/∗ if data is a value ∗/
DtObject slot;
DtReal   value;
 FORTRAN format:
 SUBROUTINE VALUATORFCN(DATA, SLOT, VALUE)
INTEGER∗4 DATA
INTEGER∗4 SLOT
REAL∗8 VALUE

The parameter data is the same data with which the valuator function was installed, the parameter slot is the slot at which the new value arrived, and the parameter value is the actual input value. 

Valuators are usually used to achieve dynamic displays.  There are two major ways to achieve dynamic displays.  The most straightforward method is for the user valuator function to use the group editing routines to make lasting changes to the database.  If the desired result is to redefine a primitive, the valuator function only needs to create the new primitive and overwrite the old one using DgReplaceObj <DGRO> or DgReplaceObjInGroup <DRGOG>.  The same technique can be used to modify an attribute.  This can also be accomplished by creating an inline group that contains only the element to be affected.  This inline group would be instanced at appropriate places in the database allowing several subtrees to inherit that attribute. 

Another way to achieve dynamics is for the user valuator functions to modify some private data that will also be made known to user-supplied callback functions installed as group elements.  When executed, these callback group elements can then perform DsExecuteObj <DSEO> calls on "DoXXXX" functions with arguments that depend on the private data being maintained by user valuator functions.  Hence, immediate execution of those functions is achieved without storing them in the data base. 

After an input value has arrived at an input slot and all valuators dependent upon it have been triggered, the views containing the affected objects need to be updated in order to efficiently achieve dynamics. 

A C example of creating a valuator is :

       DgAddObjToGroup(DsInqValuatorGroup(slot),
callbackobj);

ERRORS

DsInqValuatorGroup will fail if the input slot handle is invalid. 

[WARNING - invalid slot handle]

SEE ALSO

DgReplaceObj(3D), DgReplaceObjInGroup(3D), DoCallback(3D), DoInLineGroup(3D), DoInputSlot(3D), DsInputValue(3D), DsUpdateAllViews(3D), DsValuatorSwitch(3D)

September 02, 1992