SoDragger(3IV)NAMESoDragger (SoDrag) - base class for nodekits that move in response to
click-drag-release mouse events
INHERITS FROM
SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit >
SoDraggerSYNOPSIS
#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)
Page 1SoDragger(3IV)
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)
Page 2SoDragger(3IV)
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)
DESCRIPTIONSoDragger 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
Page 3SoDragger(3IV)
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.
Page 4SoDragger(3IV)
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
Page 5SoDragger(3IV)
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
}
Page 6SoDragger(3IV)SEE ALSO
SoInteractionKit, SoCenterballDragger, SoDirectionalLightDragger,
SoDragPointDragger, SoHandleBoxDragger, SoJackDragger,
SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger,
SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger,
SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger,
SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger,
SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger,
SoTranslate2Dragger
Page 7
