SoDragger(3IV)
SoDragger (SoDrag) - base class for nodekits that move in response to click-drag-release mouse events
As shipped in IRIX 6.5.30. Added in IRIX 6.5.22.
NAME SoDragger (SoDrag) - base class for nodekits that move in response to click-drag-release mouse events INHERITS FROM SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit > SoDragger SYNOPSIS #include <Inventor_c/draggers/SoDragger.h> typedef void SoDraggerCB(void *userData, SoDragger *dragger) typedef SoDragger SoDrag Fields from class SoDragger: SoSFBool isActive Fields from class SoInteractionKit: SoSFEnum renderCaching SoSFEnum boundingBoxCaching SoSFEnum renderCulling SoSFEnum pickCulling Parts from class SoBaseKit: (SoNodeKitListPart) callbackList Functions from class SoDragger: void SoDragAddStartCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveStartCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragAddMotionCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveMotionCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragAddFinishCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveFinishCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragAddValueChangedCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveValueChangedCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) SbBool SoDragEnableValueChangedCBs(SoDrag *this) void SoDragSetMinGesture(SoDrag *this, int pixels) int SoDragGetMinGesture(const SoDrag *this) void SoDragSetMinScale(float newMinScale) float SoDragGetMinScale() const SoNodekitCatalog * SoDragGetClassNkitCat() SoType SoDragGetClassTypeId() Functions from class SoInteractionKit: SbBool SoDragSetPartAsPath(SoDrag *this, const char *partName, SoPath *surrogatePath ) Functions from class SoBaseKit: const SoNodekitCatalog * SoDragGetCat(const SoDrag *this) SoNode * SoDragGetPart(SoDrag *this, const char *partName, SbBool makeIfNeeded) SbString SoDragGetPartString(SoDrag *this, const SoBase *part) SoNodeKitPath * SoDragCreatePathToPart(SoDrag *this, const char *partName, SbBool makeIfNeeded, const SoPath *pathToExtend = NULL) SbBool SoDragSetPart(SoDrag *this, const char *partName, SoNode *newPart) SbBool SoDragSet(SoDrag *this, char *partName, char *parameters) SbBool SoDragSet2(SoDrag *this, char *nameValuePairs) SbBool SoDragIsSearchingChildren() void SoDragSetSearchingChildren(SbBool newVal) Functions from class SoNode: void SoDragSetOverride(SoDrag *this, SbBool state) SbBool SoDragIsOverride(const SoDrag *this) SoNode * SoDragCopy(const SoDrag *this, SbBool copyConnections = FALSE) SbBool SoDragAffectsState(const SoDrag *this) SoNode * SoDragGetByName(const char *name) int SoDragGetByNameList(const char *name, SoNodeList *list) Functions from class SoFieldContainer: void SoDragSetToDflts(SoDrag *this) SbBool SoDragHasDfltVals(const SoDrag *this) SbBool SoDragFldsAreEq(const SoDrag *this, const SoFieldContainer *fc) void SoDragCopyFieldVals(SoDrag *this, const SoFieldContainer *fc, SbBool copyConnections = FALSE) void SoDragGet(SoDrag *this, SbString *fieldDataString) int SoDragGetFields(const SoDrag *this, SoFieldList *resultList) SoField * SoDragGetField(const SoDrag *this, const char *fieldName) SbBool SoDragGetFieldName(const SoDrag *this, const SoField *field, SbName *fieldName) SbBool SoDragIsNotifyEnabled(const SoDrag *this) SbBool SoDragEnableNotify(SoDrag *this, SbBool flag) Functions from class SoBase: void SoDragRef(SoDrag *this) void SoDragUnref(const SoDrag *this) void SoDragUnrefNoDelete(const SoDrag *this) void SoDragTouch(SoDrag *this) SoType SoDragGetTypeId(const SoDrag *this) SbBool SoDragIsOfType(const SoDrag *this, SoType type) void SoDragSetName(SoDrag *this, const char *name) SbName SoDragGetName(const SoDrag *this) DESCRIPTION SoDragger is the base class for all nodekits you move by using the mouse to click-drag-and-release. More specifically, they are operated by a start (mouse button 1 pressed over dragger to pick it), followed by dragging (mouse motion events are interpreted by the dragger and result in some form of motion and/or change to a field), followed by finish (mouse up). Each dragger has a different paradigm for interpreting mouse motion and changing its fields as a result. Draggers map 2D mouse motion into motion of a point on 3D lines, planes, spheres or cylinders. (See the SbProjector reference pages.) Then they react to this motion of a point through 3-space by scaling, translating, or rotating. For example, SoTranslate2Dragger maps mouse motion onto a 3D plane, then translates to follow the cursor as it moves within that plane. Every dragger has fields that describe its current state. Scaling draggers have a scaleFactor field, rotational draggers have a rotation field, etc. All draggers have the isActive field, defined in this class. It is TRUE while the dragger is being dragged, FALSE otherwise. Draggers that have only one part to pick and one motion field are called simple draggers. Examples are the SoRotateDiscDragger, SoScale1Dragger, and SoTranslate2Dragger. Draggers that create assemblies out of other draggers and then orchestrate the motion of the whole assembly are call composite draggers. SoTransformBoxDragger is a composite dragger made entirely of simple draggers. SoDirectionalLightDragger contains both a simple dragger (SoRotateSphericalDragger) and a composite dragger (SoDragPointDragger) When using a composite dragger, the fields of the composite dragger are the ones you should work with. Draggers lower down in the assemblage usually have zeroed out values. For example, when you drag the face of a transformBox, an SoTranslate2Dragger, the transformBox "steals" the translation from the child dragger and transfers it up to the top of the composite dragger, where it effects all pieces of the assemblage. Draggers always keep their fields up to date, including while they are being dragged. So you can use field-to-field connections and engines to connect dragger values to other parts of your scene graph. Hence draggers can be easily utilized as input devices for mouse-driven 3D interface elements. You can also register value-changed callbacks, which are called whenever any of the fields is changed. Also, if you set the field of a dragger through some method other than dragging, (by calling SoFieldSetValue(), for example), the dragger's internal SoFieldSensor will sense this and the dragger will move to satisfy that new value. This makes it easy to constrain draggers to keep their fields within certain limits: if the limit is exceeded, just set it back to the exceeded maximum or minimum. You can do this even as the dragger is in use, by constraining the field value within a value-changed callback that you add with SoDraggerAddValueChangedCB. In this case, be sure to temporarily disable the other value-changed callbacks using SoDraggerEnableValueChangedCBs. Doing this will prevent infinite-looping; changing the value followed by calling the callbacks which change the value ad infinitum. When you drag a dragger, the dragger only moves itself. Draggers do not change the state or affect objects that follow in the scene graph. For example a dragger does not ever behave like an SoTransform and change the current transformation matrix. Draggers are not transforms, even if they have field names like translation, rotation, scaleFactor. Many draggers, such as SoTrackballDragger, have a corresponding SoTransformManip, in this case SoTrackballManip. The manipulator is a subclass of SoTransform, and affects other objects in the scene; it uses a trackball dragger to provide its user interface. In this way, draggers are employed extensively by manipulators. Callback functions on the dragger allow its employer to be notified of start, motion, finish, and value changes. In all cases, the callback function is passed a pointer to the dragger which initiated the callback. (See the various man pages for more details on specific draggers and manipulators). All draggers are nodekits. However, draggers do not list their parts in the Parts section of the reference page. Instead, there is a section called Dragger Resources, more suited to describe the parts made available to the programmer. Because of space limitations, the Dragger Resources section only appears in the online versions of the reference pages. Each dragger has some parts you can pick on, and other parts that replace them when they are active or moving. These active parts are often just the same geometry in another color. Draggers also have pieces for displaying feedback. Each of these pieces has a default scene graph, as well as a special function within the dragger. Each part also has a resource name. All this information is contained in the DRAGGER RESOURCES section. Since draggers are nodekits, you can set the parts in any instance of a dragger using SoDraggerSetPart(). But draggers also give each part a resource name. When a dragger builds a part, it looks in the global dictionary for the node with that resourceName. By putting a new entry in the dictionary, you can override that default. The default part geometries are defined as resources for each class, and each class has a file you can change to alter the defaults. The files are listed in each dragger's man page. You can make your program use different default resources for the parts by copying the listed file from the directory /usr/share/data/draggerDefaults into your own directory, editing the file, and then setting the environment variable SO_DRAGGER_DIR to be a path to that directory. FIELDS SoSFBool isActive TRUE when mouse is down and dragging, else FALSE. FUNCTIONS void SoDragAddStartCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveStartCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) Start callbacks are made after the mouse button 1 goes down and the dragger determines that it has been picked. If it is going to begin dragging, it grabs events and invokes the startCallbacks. void SoDragAddMotionCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveMotionCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) Motion callbacks are called after each movement of the mouse during dragging. void SoDragAddFinishCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveFinishCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) Finish callbacks are made after dragging ends and the dragger has stopped grabbing events. void SoDragAddValueChangedCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) void SoDragRemoveValueChangedCB(SoDrag *this, SoDraggerCB *f, void *userData = NULL) Value-changed callbacks are made after a dragger changes any of its fields. This does not include changes to the isActive field. See also SoDraggerEnableValueChangedCBs. SbBool SoDragEnableValueChangedCBs(SoDrag *this) You can temporarily disable a dragger's valueChangedCallbacks. The method returns a value that tells you if callbacks were already enabled. Use this method if you write a valueChanged callback of your own and you change one of the dragger's fields within the callback. (For example, when writing a callback to constrain your dragger). Disable first, then change the field, then re-enable the callbacks (if they were enabled to start with). All this prevents you from entering an infinite loop of changing values, calling callbacks which change values, etc. void SoDragSetMinGesture(SoDrag *this, int pixels) int SoDragGetMinGesture(const SoDrag *this) Set and get the number of pixels of movement required to initiate a constraint gesture. Default is 8. void SoDragSetMinScale(float newMinScale) float SoDragGetMinScale() The smallest scale that any dragger will write. If the user attempts to go below this amount, the dragger will set it to this minimum. Default is .001 const SoNodekitCatalog * SoDragGetClassNkitCat() Returns an SoNodekitCatalog for this class. SoType SoDragGetClassTypeId() Returns type identifier for this class. CATALOG PARTS _________________________________________________________ All parts NULL by Part Name Part Type Default Type Default callbackList NodeKitListPart -- yes _________________________________________________________ | | ________________________________________________________________ Extra information for list parts from above table Part Name Container Type Permissible Types Callback, EventCallback callbackList Separator ________________________________________________________________ | | FILE FORMAT/DEFAULTS Dragger { renderCaching AUTO boundingBoxCaching AUTO renderCulling AUTO pickCulling AUTO isActive FALSE callbackList NULL } SEE ALSO SoInteractionKit, SoCenterballDragger, SoDirectionalLightDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger, SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger, SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger, SoTranslate2Dragger