1SoSelection(3IV)() SoSelection(3IV)()
2
6 SoSelection — manages a list of selected objects
7
9 SoBase > SoFieldContainer > SoNode > SoGroup > SoSeparator > SoSelec‐
10 tion
11
13 #include <Inventor/nodes/SoSelection.h>
14 typedef void SoSelectionPathCB(void *userData, SoPath *path)
16 typedef void SoSelectionClassCB(void *userData, SoSelection *sel)
17 typedef SoPath * SoSelectionPickCB(void *userData, const SoPickedPoint
18 *pick)
19 enum Policy {
21 SoSelection::SINGLE Left mouse pick on object clears selection,
22 then selects object. Left mouse pick on
23 nothing clears selection. Only one object
24 may be selected at a time.
25 SoSelection::TOGGLE Left mouse pick on object toggles its selection
26 status. Left mouse pick on nothing does
27 nothing. Multiple objects may be selected.
28 SoSelection::SHIFT When shift key is down, selection policy is
29 TOGGLE. When shift key is up, selection
30 policy is SINGLE. Multiple objects may be
31 selected.
32 }
33 Fields from class SoSelection:
35 SoSFEnum policy
37 Fields from class SoSeparator:
39 SoSFEnum renderCaching
41 SoSFEnum boundingBoxCaching
42 SoSFEnum renderCulling
43 SoSFEnum pickCulling
44 Methods from class SoSelection:
46 SoSelection()
48 SoSelection(int nChildren)
49 static SoType getClassTypeId()
50 void select(const SoPath *path)
51 void select(SoNode *node)
52 void deselect(const SoPath *path)
53 void deselect(int which)
54 void deselect(SoNode *node)
55 void toggle(const SoPath *path)
56 void toggle(SoNode *node)
57 SbBool isSelected(const SoPath *path) const
58 SbBool isSelected(SoNode *node) const
59 void deselectAll()
60 int getNumSelected() const
61 const SoPathList * getList() const
62 SoPath * getPath(int index) const
63 SoPath * operator [](int i) const
64 void addSelectionCallback(SoSelectionPathCB *f, void
65 *userData = NULL)
66 void removeSelectionCallback(SoSelectionPathCB *f, void
67 *userData = NULL)
68 void addDeselectionCallback(SoSelectionPathCB *f, void
69 *userData = NULL)
70 void removeDeselectionCallback(SoSelectionPathCB *f, void
71 *userData = NULL)
72 void addStartCallback(SoSelectionClassCB *f, void *user‐
73 Data = NULL)
74 void removeStartCallback(SoSelectionClassCB *f, void
75 *userData = NULL)
76 void addFinishCallback(SoSelectionClassCB *f, void *user‐
77 Data = NULL)
78 void removeFinishCallback(SoSelectionClassCB *f, void
79 *userData = NULL)
80 void setPickFilterCallback(SoSelectionPickCB *f, void
81 *userData = NULL, SbBool callOnlyIfSelectable =
82 TRUE)
83 void setPickMatching(SbBool pickTwice)
84 SbBool getPickMatching() const
85 Methods from class SoSeparator:
87 static void setNumRenderCaches(int howMany)
89 static int getNumRenderCaches()
90 Methods from class SoGroup:
92 void addChild(SoNode *child)
94 void insertChild(SoNode *child, int newChildIndex)
95 SoNode * getChild(int index) const
96 int findChild(const SoNode *child) const
97 int getNumChildren() const
98 void removeChild(int index)
99 void removeChild(SoNode *child)
100 void removeAllChildren()
101 void replaceChild(int index, SoNode *newChild)
102 void replaceChild(SoNode *oldChild, SoNode *newChild)
103 Methods from class SoNode:
105 void setOverride(SbBool state)
107 SbBool isOverride() const
108 SoNode * copy(SbBool copyConnections = FALSE) const
109 virtual SbBool affectsState() const
110 static SoNode * getByName(const SbName &name)
111 static int getByName(const SbName &name, SoNodeList &list)
112 Methods from class SoFieldContainer:
114 void setToDefaults()
116 SbBool hasDefaultValues() const
117 SbBool fieldsAreEqual(const SoFieldContainer *fc) const
118 void copyFieldValues(const SoFieldContainer *fc, SbBool
119 copyConnections = FALSE)
120 SbBool set(const char *fieldDataString)
121 void get(SbString &fieldDataString)
122 virtual int getFields(SoFieldList &resultList) const
123 virtual SoField * getField(const SbName &fieldName) const
124 SbBool getFieldName(const SoField *field, SbName &fieldName)
125 const
126 SbBool isNotifyEnabled() const
127 SbBool enableNotify(SbBool flag)
128 Methods from class SoBase:
130 void ref()
132 void unref() const
133 void unrefNoDelete() const
134 void touch()
135 virtual SoType getTypeId() const
136 SbBool isOfType(SoType type) const
137 virtual void setName(const SbName &name)
138 virtual SbName getName() const
139
142 SoSelection defines a node which can be inserted into a scene graph and
143 will generate and manage a selection list from picks on any node in the
144 subgraph below it. Nodes are selected based on a current selection pol‐
145 icy. Callback functions report back to the application when a path has
146 been selected or deselected. The selection list can also be managed
147 programmatically.
148 When handling events, SoSelection makes sure that the mouse release
150 event was over the same object as the mouse press event before changing
151 the list of selected objects. This allows users to mouse down on an
152 object, change their mind and move the cursor off the object, then
153 release the mouse button without altering the selection.
154 The selection can be highlighted automatically through the SoXtRender‐
156 Area, or the application can provide custom highlights. Please see the
157 chapter "Creating a Selection Highlight Style" in the Inventor Tool‐
158 maker.
159
161 SoSFEnum policy
162 Selection policy that is followed in response to user interaction.
163 This can be set to SoSelection::SINGLE, SoSelection::TOGGLE, or SoS‐
164 election::SHIFT.
165
168 SoSelection()
169 Creates a selection node with the default settings.
170 SoSelection(int nChildren)
172 Constructor that specifies the approximate number of children.
173 static SoType getClassTypeId()
175 Return the type id for the SoSelection class.
176 void select(const SoPath *path)
178 Select the passed path by adding it to the selection list. The
179 selection node must lie in the path. The path is copied and trun‐
180 cated such that the selection node is the head of the path. If the
181 selection node does not lie in the path, the selection list remains
182 unchanged. This method ignores the current selection policy.
183 void select(SoNode *node)
185 Select the passed node by creating a path to it, and adding the path
186 to the selection list by calling select(path). If there is more than
187 one instance of node beneath the selection node, the created path
188 will be the first instance found.
189 void deselect(const SoPath *path)
191 Deselect the passed path by removing it from the selection list.
192 void deselect(int which)
194 Deselect a path by removing it from the selection list. The argument
195 which specifies which path in the list to be removed.
196 void deselect(SoNode *node)
198 Deselect the passed node by creating a path to it, and removing the
199 node from the selection list by calling deselect(path). If there is
200 more than one instance of node beneath the selection node, the cre‐
201 ated path will be the first instance found.
202 void toggle(const SoPath *path)
204 Toggle the selection status of the passed path — if the path is in
205 the selection list, it is removed; if not in the list, it is added.
206 void toggle(SoNode *node)
208 Toggle the selection status of the passed node by creating a path to
209 it, then calling toggle(path). If there is more than one instance of
210 node beneath the selection node, the created path will be the first
211 instance found.
212 SbBool isSelected(const SoPath *path) const
214 Returns TRUE if the passed path is selected, that is, if it is in
215 the selection list.
216 SbBool isSelected(SoNode *node) const
218 Returns TRUE if the passed node is selected by creating a path to
219 it, then calling isSelected(). If there is more than one instance of
220 node beneath the selection node, the created path will be the first
221 instance found.
222 void deselectAll()
224 Deselect all paths in the selection list, that is, clear the list.
225 int getNumSelected() const
227 Return the number of paths in the selection list.
228 const SoPathList * getList() const
230 Return the list of selected paths.
231 SoPath * getPath(int index) const
233 SoPath * operator [](int i) const
234 Return the ith path in the selection list.
235 void addSelectionCallback(SoSelectionPathCB *f, void
237 *userData = NULL)
238 void removeSelectionCallback(SoSelectionPathCB *f, void
239 *userData = NULL)
240 The selection callbacks are invoked every time an object is
241 selected, whether it be from user interaction or from method call.
242 The callbacks are invoked after the object has been added to the
243 selection list.
244 void addDeselectionCallback(SoSelectionPathCB *f, void
246 *userData = NULL)
247 void removeDeselectionCallback(SoSelectionPathCB *f, void
248 *userData = NULL)
249 The deselection callbacks are invoked every time an object is dese‐
250 lected, whether it be from user interaction or from method call.
251 This is invoked after the object has been removed from the selection
252 list.
253 void addStartCallback(SoSelectionClassCB *f, void *user‐
255 Data = NULL)
256 void removeStartCallback(SoSelectionClassCB *f, void
257 *userData = NULL)
258 The start callbacks are invoked when the user has initiated an
259 interactive change to the selection list (by picking objects). This
260 will be followed by invocations of the select and/or deselect call‐
261 backs, finally followed by each finish callback. A start callback
262 can be used, for instance, to save the current selection for later
263 restoration (e.g. undo/redo). The start callbacks are not called
264 when the selection list is changed programmatically.
265 void addFinishCallback(SoSelectionClassCB *f, void *user‐
267 Data = NULL)
268 void removeFinishCallback(SoSelectionClassCB *f, void
269 *userData = NULL)
270 The finish callbacks are invoked when the user has finished interac‐
271 tively changing the selection list (by picking objects). This was
272 preceded by an invocation of each start callback, and invocations of
273 the select and/or deselect callbacks. The finish callbacks are not
274 called when the selection list is changed programmatically.
275 void setPickFilterCallback(SoSelectionPickCB *f, void
277 *userData = NULL, SbBool callOnlyIfSelectable =
278 TRUE)
279 The pick filter callback is invoked when a pick has occurred and the
280 selection node is about to change the selection list. The callback
281 function returns the path that the selection node should use when
282 selecting and deselecting. If no pick callback is registered (the
283 default), the selection node will use the path returned by SoPicked‐
284 Point::getPath() on the picked point associated with the event being
285 processed. The returned path should not be ref'd - selection will
286 ref() and unref() it. (See SoPath::unrefNoDelete().)
287 Note that a picked object may or may not be a child of the selection
289 node. A selection node will only select paths that pass through it.
290 Possible return values from the callback:
291 [a] NULL — selection behaves as if nothing was picked (i.e. for SIN‐
293 GLE and SHIFT policies, this clears the selection list). Handle
294 event action traversal halts.
295 [b] Path — this path will be selected/deselected according to the
297 selection policy (it must lie under the selection node). Handle
298 event action traversal halts.
299 [c] Path containing only the selection node — apply the selection
301 policy as if nothing was picked. Handle event action traversal con‐
302 tinues.
303 [d] Path not passing through the selection node — selection ignores
305 this pick event and no change is made to the selection list. Handle
306 event action traversal continues.
307 A simple way to tell selection to ignore the pick is to return an
309 SoPath with no nodes in it. (i.e. return new SoPath;) Selection will
310 always ref the path returned by the callback, make a copy of the
311 path, then unref the path.
312 The callOnlyIfSelectable argument, when set to TRUE, means the pick
314 callback function will only be invoked on picks which pass through
315 the selection node. When FALSE, all picks will be passed to the
316 callback whether they pass through the selection or not.
317 void setPickMatching(SbBool pickTwice)
319 SbBool getPickMatching() const
320 SoSelection will pick once on mouse down and once on mouse up, and
321 make sure the picks match before changing the selection list. This
322 allows the user to pick down on an object, change their mind and
323 drag off the object, release the mouse button and not affect the
324 selection. Pass TRUE to enable this behavior. Pass FALSE to disable
325 this, meaning whatever is picked on a mouse release is added
326 to/removed from the selection list. Default is pick-matching on.
327
330 Selection {
331 renderCaching AUTO
332 boundingBoxCaching AUTO
333 renderCulling AUTO
334 pickCulling AUTO
335 policy SHIFT
336 }
337
339 SoEventCallback, SoXtRenderArea, SoBoxHighlightRenderAction, SoLine‐
340 HighlightRenderAction
341 SoSelection(3IV)()