1SoField(3IV)() SoField(3IV)()
2
3
4
6 SoField — base class for all fields
7
9 SoField
10
12 #include <Inventor/fields/SoField.h>
13
14 Methods from class SoField:
15
16 void setIgnored(SbBool ignore)
17 SbBool isIgnored() const
18 SbBool isDefault() const
19 static SoType getClassTypeId()
20 virtual SoType getTypeId() const
21 virtual SbBool isOfType(SoType type) const
22 SbBool set(const char *valueString)
23 void get(SbString &valueString)
24 int operator ==(const SoField &f) const
25 int operator !=(const SoField &f) const
26 void touch()
27 SbBool connectFrom(SoField *fromField)
28 SbBool connectFrom(SoEngineOutput *fromEngine)
29 void disconnect()
30 SbBool isConnected() const
31 SbBool isConnectedFromField() const
32 SbBool getConnectedField(SoField *&writingField) const
33 SbBool isConnectedFromEngine() const
34 SbBool getConnectedEngine(SoEngineOutput *&engineOutput)
35 const
36 void enableConnection(SbBool flag)
37 SbBool isConnectionEnabled() const
38 int getForwardConnections(SoFieldList &list) const
39 SoFieldContainer * getContainer() const
40
41
43 SoField is the abstract base class for all fields. Fields are the data
44 elements contained within nodes and are the input values for engines.
45 Each node or engine class specifies a set of fields and associates a
46 name with each. These names define the semantics of the field (e.g.,
47 the SoCube node contains three float fields named width, height, and
48 depth). Field classes provide the access methods that indirectly allow
49 editing and querying of data within nodes.
50
51 There are two abstract subclasses of SoField: SoSField is the base
52 class for all single-valued field classes and SoMField is the base
53 class for all multiple-valued fields, which contain dynamic arrays of
54 values. Subclasses of SoSField have an SoSF prefix, and subclasses of
55 SoMField have an SoMF prefix. See the reference pages for SoSField and
56 SoMField for additional methods.
57
58 Fields are typically constructed only within node or engine instances;
59 if you need a field that is not part of a node or engine, you can cre‐
60 ate a GlobalField; see the methods on SoDB for creating global fields.
61
62 Fields can be connected either directly to another field, or can be
63 connected to the output of an engine. The value of a field with a con‐
64 nection will change when the thing it is connected to changes. For
65 example, consider a field "A" that is connected from "B" (by A->con‐
66 nectFrom(B)). When B's value is changed, A's value will also change.
67 Note that A and B may have different values, even if they are con‐
68 nected: if A's value is set after B's value, A's value will be differ‐
69 ent from B's until B's value is set.
70
71 A field can be connected to several other fields, but can be connected
72 from only one source.
73
74 It is possible (and often useful) to create loops of field connections
75 (for example, A connected from B and B connected from A). If there are
76 loops, then the rule is that the last setValue() done overrides any
77 connections in to that value. You can think of setting the value of a
78 field as immediately propagating that value forward into all the fields
79 it is connected to, with the propagation stopping at the place where
80 the original setValue() occurred if there is a connection loop. (Actu‐
81 ally, a more efficient mechanism than this is used, but the semantics
82 are the same.)
83
84 If you try to connect two fields of differing types, Inventor will
85 automatically try to insert a field converter engine between them to
86 convert values from one type into the other. Inventor has most reason‐
87 able conversions built-in (multiple-valued field to single-valued and
88 vice versa, anything to SoSFString, anything to SoSFTrigger,
89 float/short/unsigned short/int32_t/uint32_t/etc numeric conversions,
90 etc). You can add field converters using SoDB's extender method addCon‐
91 verter(); see the SoDB.h header file for details. You can also find out
92 if a converter is available with the SoDB::getConverter() method.
93
94 Fields each define their own file format for reading and being written
95 to files, but all fields follow the same conventions:
96
97 Fields in a node or engine are written as the name of the field fol‐
98 lowed by the field's value; fields are not written if they have not
99 been modified since they were created (if they have their default
100 value).
101
102 The ignored flag is written as a "~" character after the field's value
103 (if the field's value is its default value, just the "~" is written).
104
105 Field connections are written as an "=" followed by the container of
106 the field or engine output that the field is connected to, followed by
107 a "." and the name of the field or engine output. For example:
108
109 DEF node1 Transform { translation 1 1 1 }
110 DEF node2 Scale { scaleFactor 1 1 1 = USE node1.translation }
111
112
113
114 Global fields are written as part of an internal SoFieldContainer class
115 called GlobalField, which writes out an SoSFName field named type whose
116 value is the type of the global field, followed by a field of that type
117 whose name is the name of the global field. For example, a global
118 uint32_t field called "FrameCounter" whose value is 494 would be written
119 as:
120
121 GlobalField {
122 type SoSFUInt32
123 FrameCounter 494
124 }
125
126
127
129 void setIgnored(SbBool ignore)
130 SbBool isIgnored() const
131 Sets/gets the ignore flag for this field. When a field's ignore flag
132 is set to TRUE, the field is not used during traversal for rendering
133 and other actions. The default value for this flag is FALSE.
134
135 SbBool isDefault() const
136 Gets the state of default flag of the field. This flag will be TRUE
137 for any field whose value is not modified after construction and
138 will be FALSE for those that have changed (each node or engine
139 determines what the default values for its fields are). Note: the
140 state of this flag should not be set explicitly from within applica‐
141 tions.
142
143 static SoType getClassTypeId()
144 Return the type identifier for this field class.
145
146 virtual SoType getTypeId() const
147 Return the type identifier for this field instance (SoField *).
148
149 virtual SbBool isOfType(SoType type) const
150 Returns TRUE if this field is the given type or derived from that
151 type. This is typically used with the getClassTypeId() method to
152 determine the type of an SoField * at run-time:
153
154 SoField *field = ....;
155 if (field->isOfType(SoSFFloat::getClassTypeId())) {
156 SoSFFloat *floatField = (SoSFFloat *)field);
157 floatField->setValue(4.5);
158 }
159
160
161
162 SbBool set(const char *valueString)
163 Sets the field to the given value, which is an ASCII string in the
164 Inventor file format. Each field subclass defines its own file for‐
165 mat; see their reference pages for information on their file format.
166 The string should contain only the field's value, not the field's
167 name (e.g., "1.0", not "width 1.0"). This method returns TRUE if the
168 string is valid, FALSE if it is not.
169
170 void get(SbString &valueString)
171 Returns the value of the field in the Inventor file format, even if
172 the field has its default value.
173
174 int operator ==(const SoField &f) const
175 int operator !=(const SoField &f) const
176 Return TRUE (FALSE) if this field is of the same type and has the
177 same value as f.
178
179 void touch()
180 Simulates a change to the field, causing attached sensors to fire,
181 connected fields and engines to be marked as needing evaluation, and
182 so forth. Calling touch() on an instance of a derived field class is
183 equivalent to calling setValue(getValue()) using the derived class's
184 methods, except that the field's isDefault() status remains
185 unchanged.
186
187 SbBool connectFrom(SoField *fromField)
188 SbBool connectFrom(SoEngineOutput *fromEngine)
189 Connects this field to another field or from an engine output. If
190 the field was connected to something before, it will be automati‐
191 cally disconnected (a field may have only one connection writing
192 into it at a time). Unless connections to the field are disabled
193 (see enableConnection()), the field's value will be set to the value
194 of the thing it is connected to.
195
196 void disconnect()
197 Disconnect the field from whatever it was connected to. This does
198 nothing if the field was not connected.
199
200 SbBool isConnected() const
201 Returns TRUE if the field is connected to anything.
202
203 SbBool isConnectedFromField() const
204 Returns TRUE if the field is connected to another field.
205
206 SbBool getConnectedField(SoField *&writingField) const
207 Returns TRUE if this field is being written into by another field,
208 and returns the field it is connected to in writingField. Returns
209 FALSE and does not modify writingField if it is not connected to a
210 field.
211
212 SbBool isConnectedFromEngine() const
213 Returns TRUE if the field is connected to an engine's output.
214
215 SbBool getConnectedEngine(SoEngineOutput *&engineOutput)
216 const
217 Returns TRUE if this field is being written into by an engine, and
218 returns the engine output it is connected to in engineOutput.
219 Returns FALSE and does not modify engineOutput if it is not con‐
220 nected to an engine.
221
222 void enableConnection(SbBool flag)
223 Field connections may be enabled and disabled. Disabling a field's
224 connection is almost exactly like disconnecting it; the only differ‐
225 ence is that you can later re-enable the connection by calling
226 enableConnection(TRUE). Note that disconnecting an engine output
227 can cause the engine's reference count to be decremented and the
228 engine to be deleted, but disabling the connection does not decre‐
229 ment its reference count.
230
231 Re-enabling a connection will cause the value of the field to be
232 changed to the engine output or field to which it is connected.
233
234 A field's connection-enabled status is maintained even if the field
235 is disconnected or reconnected. By default, connections are enabled.
236
237 SbBool isConnectionEnabled() const
238 Returns FALSE if connections to this field are disabled. Note that
239 this may return FALSE even if the field is not connected to any‐
240 thing.
241
242 int getForwardConnections(SoFieldList &list) const
243 Adds pointers to all of the fields that this field is writing into
244 (either fields in nodes, global fields or engine inputs) to the
245 given field list, and returns the number of forward connections.
246
247 SoFieldContainer * getContainer() const
248 Returns the object that contains this field. The type of the object
249 will be either SoNode, SoEngine, or will be a global field container
250 (note that the global field container class is internal to Inventor;
251 see the methods for creating and accessing global fields on SoDB).
252 For example:
253
254 SoFieldContainer *f = field->getContainer();
255 if (f->isOfType(SoNode::getClassTypeId())) {
256 ... do something ...
257 } else if (f->isOfType(SoEngine::getClassTypeId())) {
258 ... do someting else ...
259 } else {
260 ... it must be a global field. We can figure out its name, but
261 that is about it:
262 const SbName &globalFieldName = f->getName();
263 }
264
265
266
267
269 SoSField, SoMField, SoNode, SoDB
270
271
272
273
274 SoField(3IV)()