1SoDragger(3IV)()                                              SoDragger(3IV)()
2
3
4

NAME

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

INHERITS FROM

10       SoBase > SoFieldContainer > SoNode >  SoBaseKit  >  SoInteractionKit  >
11       SoDragger
12

SYNOPSIS

14       #include <Inventor/draggers/SoDragger.h>
15
16     typedef void        SoDraggerCB(void *userData, SoDragger *dragger)
17
18          Fields from class SoDragger:
19
20     SoSFBool            isActive
21
22          Fields from class SoInteractionKit:
23
24     SoSFEnum            renderCaching
25     SoSFEnum            boundingBoxCaching
26     SoSFEnum            renderCulling
27     SoSFEnum            pickCulling
28
29          Parts from class SoBaseKit:
30
31     (SoNodeKitListPart)  callbackList
32
33          Methods from class SoDragger:
34
35     void                addStartCallback(SoDraggerCB  *f,  void  *userData  =
36                              NULL)
37     void                removeStartCallback(SoDraggerCB *f, void *userData  =
38                              NULL)
39     void                addMotionCallback(SoDraggerCB  *f,  void  *userData =
40                              NULL)
41     void                removeMotionCallback(SoDraggerCB *f, void *userData =
42                              NULL)
43     void                addFinishCallback(SoDraggerCB  *f,  void  *userData =
44                              NULL)
45     void                removeFinishCallback(SoDraggerCB *f, void *userData =
46                              NULL)
47     void                addValueChangedCallback(SoDraggerCB  *f,  void *user‐
48                              Data = NULL)
49     void                removeValueChangedCallback(SoDraggerCB    *f,    void
50                              *userData = NULL)
51     SbBool              enableValueChangedCallbacks()
52     void                setMinGesture(int pixels)
53     int                 getMinGesture() const
54     static void         setMinScale(float newMinScale)
55     static float        getMinScale()
56     static const SoNodekitCatalog *
57                         getClassNodekitCatalog() const
58     static SoType       getClassTypeId()
59
60          Methods from class SoInteractionKit:
61
62     virtual  SbBool      setPartAsPath(const SbName &partName, SoPath *surro‐
63                              gatePath )
64
65          Methods from class SoBaseKit:
66
67     virtual const SoNodekitCatalog *
68                              getNodekitCatalog() const
69     virtual   SoNode   *         getPart(const   SbName   &partName,   SbBool
70                                   makeIfNeeded)
71     SbString                 getPartString(const SoBase *part)
72     virtual  SoNodeKitPath *  createPathToPart(const SbName &partName, SbBool
73                                   makeIfNeeded, const SoPath *pathToExtend  =
74                                   NULL)
75     virtual SbBool           setPart(const SbName &partName, SoNode *newPart)
76     SbBool                   set(char *partName, char *parameters)
77     SbBool                   set(char *nameValuePairs)
78     static SbBool            isSearchingChildren()
79     static void              setSearchingChildren(SbBool newVal)
80
81          Methods from class SoNode:
82
83     void                setOverride(SbBool state)
84     SbBool              isOverride() const
85     SoNode *            copy(SbBool copyConnections = FALSE) const
86     virtual SbBool      affectsState() const
87     static SoNode *     getByName(const SbName &name)
88     static int          getByName(const SbName &name, SoNodeList &list)
89
90          Methods from class SoFieldContainer:
91
92     void                setToDefaults()
93     SbBool              hasDefaultValues() const
94     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
95     void                copyFieldValues(const  SoFieldContainer  *fc,  SbBool
96                              copyConnections = FALSE)
97     void                get(SbString &fieldDataString)
98     virtual int         getFields(SoFieldList &resultList) const
99     virtual SoField *   getField(const SbName &fieldName) const
100     SbBool              getFieldName(const SoField *field, SbName &fieldName)
101                              const
102     SbBool              isNotifyEnabled() const
103     SbBool              enableNotify(SbBool flag)
104
105          Methods from class SoBase:
106
107     void                ref()
108     void                unref() const
109     void                unrefNoDelete() const
110     void                touch()
111     virtual SoType      getTypeId() const
112     SbBool              isOfType(SoType type) const
113     virtual void        setName(const SbName &name)
114     virtual SbName      getName() const
115
116          Macros from class SoBaseKit:
117
118     SO_GET_PART(kit, partName, partClass)
119     SO_CHECK_PART(kit, partName, partClass)
120
121

DESCRIPTION

123       SoDragger  is  the  base  class  for all nodekits you move by using the
124       mouse to click-drag-and-release. More specifically, they  are  operated
125       by  a  start (mouse button 1 pressed over dragger to pick it), followed
126       by dragging (mouse motion events are interpreted  by  the  dragger  and
127       result  in  some  form of motion and/or change to a field), followed by
128       finish (mouse up).
129
130       Each dragger has a different paradigm for interpreting mouse motion and
131       changing  its  fields  as  a  result. Draggers map 2D mouse motion into
132       motion of a point on 3D lines, planes, spheres or cylinders.  (See  the
133       SbProjector reference pages.) Then they react to this motion of a point
134       through 3-space by scaling,  translating,  or  rotating.  For  example,
135       SoTranslate2Dragger  maps mouse motion onto a 3D plane, then translates
136       to follow the cursor as it moves within that plane.
137
138       Every dragger has fields that describe its current state. Scaling drag‐
139       gers  have  a  scaleFactor  field,  rotational draggers have a rotation
140       field, etc. All draggers have  the  isActive  field,  defined  in  this
141       class. It is TRUE while the dragger is being dragged, FALSE otherwise.
142
143       Draggers  that  have  only  one  part  to pick and one motion field are
144       called  simple  draggers.   Examples   are   the   SoRotateDiscDragger,
145       SoScale1Dragger, and SoTranslate2Dragger.
146
147       Draggers  that create assemblies out of other draggers and then orches‐
148       trate the motion of the whole assembly  are  call  composite  draggers.
149       SoTransformBoxDragger  is  a  composite dragger made entirely of simple
150       draggers. SoDirectionalLightDragger  contains  both  a  simple  dragger
151       (SoRotateSphericalDragger) and a composite dragger (SoDragPointDragger)
152       When using a composite dragger, the fields of the composite dragger are
153       the  ones  you  should work with. Draggers lower down in the assemblage
154       usually have zeroed out values. For example, when you drag the face  of
155       a  transformBox,  an SoTranslate2Dragger, the transformBox "steals" the
156       translation from the child dragger and transfers it up to  the  top  of
157       the composite dragger, where it effects all pieces of the assemblage.
158
159       Draggers  always keep their fields up to date, including while they are
160       being dragged. So you can use field-to-field connections and engines to
161       connect  dragger values to other parts of your scene graph. Hence drag‐
162       gers can be easily utilized as input devices for mouse-driven 3D inter‐
163       face elements. You can also register value-changed callbacks, which are
164       called whenever any of the fields is changed.
165
166       Also, if you set the field of a dragger through some method other  than
167       dragging,  (by calling setValue(), for example), the dragger's internal
168       SoFieldSensor will sense this and the dragger will move to satisfy that
169       new value.
170
171       This  makes  it  easy to constrain draggers to keep their fields within
172       certain limits: if the limit is exceeded,  just  set  it  back  to  the
173       exceeded  maximum or minimum. You can do this even as the dragger is in
174       use, by constraining the field value within  a  value-changed  callback
175       that  you  add with addValueChangedCallback(). In this case, be sure to
176       temporarily disable the other value-changed callbacks using  enableVal‐
177       ueChangedCallbacks().  Doing this will prevent infinite-looping; chang‐
178       ing the value followed by calling the callbacks which change the  value
179       ad infinitum.
180
181       When you drag a dragger, the dragger only moves itself. Draggers do not
182       change the state or affect objects that follow in the scene graph.  For
183       example  a  dragger does not ever behave like an SoTransform and change
184       the current transformation matrix. Draggers are not transforms, even if
185       they  have  field  names  like translation, rotation, scaleFactor. Many
186       draggers, such as SoTrackballDragger, have a corresponding SoTransform‐
187       Manip,  in this case SoTrackballManip. The manipulator is a subclass of
188       SoTransform, and affects other objects in the scene; it uses  a  track‐
189       ball  dragger  to provide its user interface. In this way, draggers are
190       employed extensively by manipulators. Callback functions on the dragger
191       allow  its  employer to be notified of start, motion, finish, and value
192       changes. In all cases, the callback function is passed a pointer to the
193       dragger  which  initiated  the callback. (See the various man pages for
194       more details on specific draggers and manipulators).
195
196       All draggers are nodekits. However, draggers do not list their parts in
197       the  Parts  section  of the reference page. Instead, there is a section
198       called Dragger Resources, more suited to describe the parts made avail‐
199       able  to  the  programmer.  Because  of  space limitations, the Dragger
200       Resources section only appears in the online versions of the  reference
201       pages.  Each  dragger  has  some parts you can pick on, and other parts
202       that replace them when they are active or moving.  These  active  parts
203       are  often  just the same geometry in another color. Draggers also have
204       pieces for displaying feedback. Each of  these  pieces  has  a  default
205       scene  graph,  as  well as a special function within the dragger.  Each
206       part also has a resource name. All this information is contained in the
207       DRAGGER RESOURCES section.
208
209       Since draggers are nodekits, you can set the parts in any instance of a
210       dragger using setPart().
211
212       But draggers also give each part a resource name. When a dragger builds
213       a  part,  it  looks  in  the  global  dictionary for the node with that
214       resourceName. By putting a new entry in the dictionary, you  can  over‐
215       ride that default. The default part geometries are defined as resources
216       for each class, and each class has a file you can change to  alter  the
217       defaults. The files are listed in each dragger's man page. You can make
218       your program use different default resources for the parts  by  copying
219       the listed file from the directory /usr/share/data/draggerDefaults into
220       your own directory, editing the file, and then setting the  environment
221       variable SO_DRAGGER_DIR to be a path to that directory.
222

FIELDS

224     SoSFBool            isActive
225          TRUE when mouse is down and dragging, else FALSE.
226
227

METHODS

229     void                addStartCallback(SoDraggerCB  *f,  void  *userData  =
230                              NULL)
231     void                removeStartCallback(SoDraggerCB *f, void *userData  =
232                              NULL)
233          Start  callbacks are made after the mouse button 1 goes down and the
234          dragger determines that it has been picked. If it is going to  begin
235          dragging, it grabs events and invokes the startCallbacks.
236
237     void                addMotionCallback(SoDraggerCB  *f,  void  *userData =
238                              NULL)
239     void                removeMotionCallback(SoDraggerCB *f, void *userData =
240                              NULL)
241          Motion  callbacks are called after each movement of the mouse during
242          dragging.
243
244     void                addFinishCallback(SoDraggerCB *f,  void  *userData  =
245                              NULL)
246     void                removeFinishCallback(SoDraggerCB *f, void *userData =
247                              NULL)
248          Finish callbacks are made after dragging ends and  the  dragger  has
249          stopped grabbing events.
250
251     void                addValueChangedCallback(SoDraggerCB  *f,  void *user‐
252                              Data = NULL)
253     void                removeValueChangedCallback(SoDraggerCB    *f,    void
254                              *userData = NULL)
255          Value-changed  callbacks are made after a dragger changes any of its
256          fields. This does not include changes to  the  isActive  field.  See
257          also enableValueChangedCallbacks.
258
259     SbBool              enableValueChangedCallbacks()
260          You  can  temporarily disable a dragger's valueChangedCallbacks. The
261          method returns a value that tells  you  if  callbacks  were  already
262          enabled.  Use  this  method  if you write a valueChanged callback of
263          your own and you change one of the dragger's fields within the call‐
264          back.  (For example, when writing a callback to constrain your drag‐
265          ger). Disable first, then change the field, then re-enable the call‐
266          backs  (if  they  were enabled to start with). All this prevents you
267          from entering an infinite loop of changing values, calling callbacks
268          which change values, etc.
269
270     void                setMinGesture(int pixels)
271     int                 getMinGesture() const
272          Set  and get the number of pixels of movement required to initiate a
273          constraint gesture. Default is 8.
274
275     static void         setMinScale(float newMinScale)
276     static float        getMinScale()
277          The smallest scale that any dragger will write. If the user attempts
278          to  go  below  this amount, the dragger will set it to this minimum.
279          Default is .001
280
281     static const SoNodekitCatalog *
282                         getClassNodekitCatalog() const
283          Returns an SoNodekitCatalog for this class.
284
285     static SoType       getClassTypeId()
286          Returns type identifier for this class.
287
288

CATALOG PARTS

290       ┌────────────────────────────────────────────────────────┐
291All parts                        
292NULL by 
293Part Name      Part Type         Default Type   Default 
294       │                                                        │
295       │callbackList   NodeKitListPart   --               yes   │
296       │                                                        │
297       └────────────────────────────────────────────────────────┘
298       ┌───────────────────────────────────────────────────────────────┐
299Extra information for list parts from above table        
300       │                                                               │
301Part Name      Container Type   Permissible Types              
302       │                                                               │
303       │callbackList   Separator        Callback, EventCallback        │
304       │                                                               │
305       └───────────────────────────────────────────────────────────────┘

FILE FORMAT/DEFAULTS

307       Dragger {
308          renderCaching       AUTO
309          boundingBoxCaching  AUTO
310          renderCulling       AUTO
311          pickCulling         AUTO
312          isActive            FALSE
313          callbackList        NULL
314     }
315

SEE ALSO

317       SoInteractionKit,    SoCenterballDragger,    SoDirectionalLightDragger,
318       SoDragPointDragger,  SoHandleBoxDragger,  SoJackDragger,  SoPointLight‐
319       Dragger,  SoRotateCylindricalDragger,  SoRotateDiscDragger,   SoRotate‐
320       SphericalDragger,  SoScale1Dragger,  SoScale2Dragger,  SoScale2Uniform‐
321       Dragger,  SoScaleUniformDragger,  SoSpotLightDragger,  SoTabBoxDragger,
322       SoTabPlaneDragger,  SoTrackballDragger, SoTransformBoxDragger, SoTrans‐
323       formerDragger, SoTranslate1Dragger, SoTranslate2Dragger
324
325
326
327
328                                                              SoDragger(3IV)()
Impressum