SoDragger - base class for nodekits that move in response to click-drag-release mouse events

SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit > SoDragger

#include <Inventor/draggers/SoDragger.h> c } c } SoDraggerCB(void *userData, SoDragger *dragger) Fields from class SoDragger: c } c } isActive Fields from class SoInteractionKit: c } c } renderCaching

c } c } boundingBoxCaching

c } c } renderCulling

c } c } pickCulling Parts from class SoBaseKit: c } c } callbackList Methods from class SoDragger: c } c } addStartCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeStartCallback(SoDraggerCB *f, void *userData = NULL)

c } c } addMotionCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeMotionCallback(SoDraggerCB *f, void *userData = NULL)

c } c } addFinishCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeFinishCallback(SoDraggerCB *f, void *userData = NULL)

c } c } addValueChangedCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeValueChangedCallback(SoDraggerCB *f, void *userData = NULL)

c } c } enableValueChangedCallbacks()

c } c } setMinGesture(int pixels)

c } c } getMinGesture() const

c } c } setMinScale(float newMinScale)

c } c } getMinScale()

c } c } getClassNodekitCatalog() const

c } c } getClassTypeId() Methods from class SoInteractionKit: c } c } setPartAsPath(const SbName &partName, SoPath *surrogatePath ) Methods from class SoBaseKit: c } c } getNodekitCatalog() const

c } c } getPart(const SbName &partName, SbBool makeIfNeeded)

c } c } getPartString(const SoBase *part)

c } c } createPathToPart(const SbName &partName, SbBool makeIfNeeded, const SoPath *pathToExtend = NULL)

c } c } setPart(const SbName &partName, SoNode *newPart)

c } c } set(char *partName, char *parameters)

c } c } set(char *nameValuePairs)

c } c } isSearchingChildren()

c } c } setSearchingChildren(SbBool newVal) Methods from class SoNode: c } c } setOverride(SbBool state)

c } c } isOverride() const

c } c } copy(SbBool copyConnections = FALSE) const

c } c } affectsState() const

c } c } getByName(const SbName &name)

c } c } getByName(const SbName &name, SoNodeList &list) Methods from class SoFieldContainer: c } c } setToDefaults()

c } c } hasDefaultValues() const

c } c } fieldsAreEqual(const SoFieldContainer *fc) const

c } c } copyFieldValues(const SoFieldContainer *fc, SbBool copyConnections = FALSE)

c } c } get(SbString &fieldDataString)

c } c } getFields(SoFieldList &resultList) const

c } c } getField(const SbName &fieldName) const

c } c } getFieldName(const SoField *field, SbName &fieldName) const

c } c } isNotifyEnabled() const

c } c } enableNotify(SbBool flag) Methods from class SoBase: c } c } ref()

c } c } unref() const

c } c } unrefNoDelete() const

c } c } touch()

c } c } getTypeId() const

c } c } isOfType(SoType type) const

c } c } setName(const SbName &name)

c } c } getName() const Macros from class SoBaseKit: SO_GET_PART(kit, partName, partClass)

SO_CHECK_PART(kit, partName, partClass)

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 setValue(), 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 addValueChangedCallback(). In this case, be sure to temporarily disable the other value-changed callbacks using enableValueChangedCallbacks(). 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 setPart(). 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.

c } c } isActive

TRUE when mouse is down and dragging, else FALSE.

c } c } addStartCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeStartCallback(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. c } c } addMotionCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeMotionCallback(SoDraggerCB *f, void *userData = NULL)

Motion callbacks are called after each movement of the mouse during dragging. c } c } addFinishCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeFinishCallback(SoDraggerCB *f, void *userData = NULL)

Finish callbacks are made after dragging ends and the dragger has stopped grabbing events. c } c } addValueChangedCallback(SoDraggerCB *f, void *userData = NULL)

c } c } removeValueChangedCallback(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 enableValueChangedCallbacks. c } c } enableValueChangedCallbacks()

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. c } c } setMinGesture(int pixels)

c } c } getMinGesture() const

Set and get the number of pixels of movement required to initiate a constraint gesture. Default is 8. c } c } setMinScale(float newMinScale)

c } c } getMinScale()

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 c } c } getClassNodekitCatalog() const

Returns an SoNodekitCatalog for this class. c } c } getClassTypeId()

Returns type identifier for this class.

box, tab(!); cb s s s lb lb lb lb lb lb lb lb l l l c. All parts !!!NULL by Part Name!Part Type!Default Type!Default

callbackList!NodeKitListPart!--!yes

box, tab(!); cb s s lb lb lbw(3) l l l. Extra information for list parts from above table Part Name!Container Type!Permissible Types

callbackList!Separator!T{ Callback, EventCallback T}

Dragger {
renderCaching	AUTO
boundingBoxCaching	AUTO
renderCulling	AUTO
pickCulling	AUTO
isActive	FALSE
callbackList	NULL
}

SoInteractionKit, SoCenterballDragger, SoDirectionalLightDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger, SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger, SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger, SoTranslate2Dragger