1SoField(3IV)()                                                  SoField(3IV)()
2
3
4

NAME

6       SoField — base class for all fields
7

INHERITS FROM

9       SoField
10

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

SEE ALSO

269       SoSField, SoMField, SoNode, SoDB
270
271
272
273
274                                                                SoField(3IV)()
Impressum