Provided by: inventor-doc_2.1.5-10-18_all bug


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


       SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit > SoDragger


       #include <Inventor/draggers/SoDragger.h>

     typedef void        SoDraggerCB(void *userData, SoDragger *dragger)

          Fields from class SoDragger:

     SoSFBool            isActive

          Fields from class SoInteractionKit:

     SoSFEnum            renderCaching
     SoSFEnum            boundingBoxCaching
     SoSFEnum            renderCulling
     SoSFEnum            pickCulling

          Parts from class SoBaseKit:

     (SoNodeKitListPart)  callbackList

          Methods from class SoDragger:

     void                addStartCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeStartCallback(SoDraggerCB *f, void *userData = NULL)
     void                addMotionCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeMotionCallback(SoDraggerCB *f, void *userData = NULL)
     void                addFinishCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeFinishCallback(SoDraggerCB *f, void *userData = NULL)
     void                addValueChangedCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeValueChangedCallback(SoDraggerCB *f, void *userData = NULL)
     SbBool              enableValueChangedCallbacks()
     void                setMinGesture(int pixels)
     int                 getMinGesture() const
     static void         setMinScale(float newMinScale)
     static float        getMinScale()
     static const SoNodekitCatalog *
                         getClassNodekitCatalog() const
     static SoType       getClassTypeId()

          Methods from class SoInteractionKit:

     virtual SbBool      setPartAsPath(const SbName &partName, SoPath *surrogatePath )

          Methods from class SoBaseKit:

     virtual const SoNodekitCatalog *
                              getNodekitCatalog() const
     virtual SoNode *         getPart(const SbName &partName, SbBool makeIfNeeded)
     SbString                 getPartString(const SoBase *part)
     virtual SoNodeKitPath *  createPathToPart(const SbName &partName, SbBool makeIfNeeded, const
                                   SoPath *pathToExtend = NULL)
     virtual SbBool           setPart(const SbName &partName, SoNode *newPart)
     SbBool                   set(char *partName, char *parameters)
     SbBool                   set(char *nameValuePairs)
     static SbBool            isSearchingChildren()
     static void              setSearchingChildren(SbBool newVal)

          Methods from class SoNode:

     void                setOverride(SbBool state)
     SbBool              isOverride() const
     SoNode *            copy(SbBool copyConnections = FALSE) const
     virtual SbBool      affectsState() const
     static SoNode *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoNodeList &list)

          Methods from class SoFieldContainer:

     void                setToDefaults()
     SbBool              hasDefaultValues() const
     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
     void                copyFieldValues(const  SoFieldContainer  *fc,  SbBool  copyConnections =
     void                get(SbString &fieldDataString)
     virtual int         getFields(SoFieldList &resultList) const
     virtual SoField *   getField(const SbName &fieldName) const
     SbBool              getFieldName(const SoField *field, SbName &fieldName) const
     SbBool              isNotifyEnabled() const
     SbBool              enableNotify(SbBool flag)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      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

       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.


     SoSFBool            isActive
          TRUE when mouse is down and dragging, else FALSE.


     void                addStartCallback(SoDraggerCB *f, void *userData = NULL)
     void                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.

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

     void                addFinishCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeFinishCallback(SoDraggerCB *f, void *userData = NULL)
          Finish  callbacks  are  made  after  dragging ends and the dragger has stopped grabbing

     void                addValueChangedCallback(SoDraggerCB *f, void *userData = NULL)
     void                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.

     SbBool              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.

     void                setMinGesture(int pixels)
     int                 getMinGesture() const
          Set and get the number of pixels of movement required to initiate a constraint gesture.
          Default is 8.

     static void         setMinScale(float newMinScale)
     static float        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

     static const SoNodekitCatalog *
                         getClassNodekitCatalog() const
          Returns an SoNodekitCatalog for this class.

     static SoType       getClassTypeId()
          Returns type identifier for this class.


       │                       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              │
       │                                                               │
       │callbackList   Separator        Callback, EventCallback        │
       │                                                               │


       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