1SoDragger(3IV)() SoDragger(3IV)()
2
6 SoDragger — base class for nodekits that move in response to click-
7 drag-release mouse events
8
10 SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit >
11 SoDragger
12
14 #include <Inventor/draggers/SoDragger.h>
15 typedef void SoDraggerCB(void *userData, SoDragger *dragger)
17 Fields from class SoDragger:
19 SoSFBool isActive
21 Fields from class SoInteractionKit:
23 SoSFEnum renderCaching
25 SoSFEnum boundingBoxCaching
26 SoSFEnum renderCulling
27 SoSFEnum pickCulling
28 Parts from class SoBaseKit:
30 (SoNodeKitListPart) callbackList
32 Methods from class SoDragger:
34 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 Methods from class SoInteractionKit:
61 virtual SbBool setPartAsPath(const SbName &partName, SoPath *surro‐
63 gatePath )
64 Methods from class SoBaseKit:
66 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 Methods from class SoNode:
82 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 Methods from class SoFieldContainer:
91 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 Methods from class SoBase:
106 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 Macros from class SoBaseKit:
117 SO_GET_PART(kit, partName, partClass)
119 SO_CHECK_PART(kit, partName, partClass)
120
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 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 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 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 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 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 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 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 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 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 Since draggers are nodekits, you can set the parts in any instance of a
210 dragger using setPart().
211 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
224 SoSFBool isActive
225 TRUE when mouse is down and dragging, else FALSE.
226
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 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 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 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 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 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 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 static const SoNodekitCatalog *
282 getClassNodekitCatalog() const
283 Returns an SoNodekitCatalog for this class.
284 static SoType getClassTypeId()
286 Returns type identifier for this class.
287
290 ┌────────────────────────────────────────────────────────┐
291 │ All parts │
292 │ NULL by │
293 │Part Name Part Type Default Type Default │
294 │ │
295 │callbackList NodeKitListPart -- yes │
296 │ │
297 └────────────────────────────────────────────────────────┘
298 ┌───────────────────────────────────────────────────────────────┐
299 │ Extra information for list parts from above table │
300 │ │
301 │Part Name Container Type Permissible Types │
302 │ │
303 │callbackList Separator Callback, EventCallback │
304 │ │
305 └───────────────────────────────────────────────────────────────┘
307 Dragger {
308 renderCaching AUTO
309 boundingBoxCaching AUTO
310 renderCulling AUTO
311 pickCulling AUTO
312 isActive FALSE
313 callbackList NULL
314 }
315
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 SoDragger(3IV)()