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

Provided by: inventor-doc_2.1.5-10+dfsg-2.1build2_all

NAME

       SoDragger — 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/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 = FALSE)
     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)

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

FIELDS

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

METHODS

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

     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.

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

FILE FORMAT/DEFAULTS

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