Provided by: inventor-doc_2.1.5-10-18_all bug


       SoField — base class for all fields




       #include <Inventor/fields/SoField.h>

          Methods from class SoField:

     void                setIgnored(SbBool ignore)
     SbBool              isIgnored() const
     SbBool              isDefault() const
     static SoType       getClassTypeId()
     virtual SoType      getTypeId() const
     virtual SbBool      isOfType(SoType type) const
     SbBool              set(const char *valueString)
     void                get(SbString &valueString)
     int                 operator ==(const SoField &f) const
     int                 operator !=(const SoField &f) const
     void                touch()
     SbBool              connectFrom(SoField *fromField)
     SbBool              connectFrom(SoEngineOutput *fromEngine)
     void                disconnect()
     SbBool              isConnected() const
     SbBool              isConnectedFromField() const
     SbBool              getConnectedField(SoField *&writingField) const
     SbBool              isConnectedFromEngine() const
     SbBool              getConnectedEngine(SoEngineOutput *&engineOutput) const
     void                enableConnection(SbBool flag)
     SbBool              isConnectionEnabled() const
     int                 getForwardConnections(SoFieldList &list) const
     SoFieldContainer *  getContainer() const


       SoField  is the abstract base class for all fields. Fields are the data elements contained
       within nodes and are the input values for engines. Each node or engine class  specifies  a
       set  of  fields  and  associates a name with each. These names define the semantics of the
       field (e.g., the SoCube node contains three float fields named width, height, and  depth).
       Field  classes  provide  the  access methods that indirectly allow editing and querying of
       data within nodes.

       There are two abstract subclasses of SoField: SoSField is the base class for  all  single-
       valued  field classes and SoMField is the base class for all multiple-valued fields, which
       contain dynamic arrays of  values.  Subclasses  of  SoSField  have  an  SoSF  prefix,  and
       subclasses  of  SoMField  have  an  SoMF  prefix. See the reference pages for SoSField and
       SoMField for additional methods.

       Fields are typically constructed only within node or engine instances; if you need a field
       that  is  not  part  of a node or engine, you can create a GlobalField; see the methods on
       SoDB for creating global fields.

       Fields can be connected either directly to another field,  or  can  be  connected  to  the
       output  of an engine. The value of a field with a connection will change when the thing it
       is connected to changes. For example, consider a field "A" that is connected from "B"  (by
       A->connectFrom(B)). When B's value is changed, A's value will also change. Note that A and
       B may have different values, even if they are connected: if A's value  is  set  after  B's
       value, A's value will be different from B's until B's value is set.

       A  field  can  be  connected  to  several other fields, but can be connected from only one

       It is possible (and often useful) to create loops of field  connections  (for  example,  A
       connected  from  B  and B connected from A). If there are loops, then the rule is that the
       last setValue() done overrides any connections in to that value. You can think of  setting
       the  value of a field as immediately propagating that value forward into all the fields it
       is connected to, with the propagation stopping at the place where the original  setValue()
       occurred if there is a connection loop. (Actually, a more efficient mechanism than this is
       used, but the semantics are the same.)

       If you try to connect two fields of differing types, Inventor will  automatically  try  to
       insert  a  field  converter  engine  between them to convert values from one type into the
       other. Inventor has most reasonable conversions built-in (multiple-valued field to single-
       valued    and   vice   versa,   anything   to   SoSFString,   anything   to   SoSFTrigger,
       float/short/unsigned short/int32_t/uint32_t/etc numeric conversions,  etc).  You  can  add
       field  converters  using SoDB's extender method addConverter(); see the SoDB.h header file
       for  details.  You  can  also  find  out  if   a   converter   is   available   with   the
       SoDB::getConverter() method.

       Fields  each  define their own file format for reading and being written to files, but all
       fields follow the same conventions:

       Fields in a node or engine are written as the name of the field followed  by  the  field's
       value;  fields  are not written if they have not been modified since they were created (if
       they have their default value).

       The ignored flag is written as a "~" character after the field's  value  (if  the  field's
       value is its default value, just the "~" is written).

       Field  connections  are written as an "=" followed by the container of the field or engine
       output that the field is connected to, followed by a "." and the  name  of  the  field  or
       engine output. For example:

          DEF node1 Transform { translation 1 1 1 }
          DEF node2 Scale { scaleFactor 1 1 1 = USE node1.translation }

     Global  fields are written as part of an internal SoFieldContainer class called GlobalField,
     which writes out an SoSFName field named type whose value is the type of the  global  field,
     followed  by a field of that type whose name is the name of the global field. For example, a
     global uint32_t field called "FrameCounter" whose value is 494 would be written as:

          GlobalField {
                              type SoSFUInt32
                              FrameCounter 494


     void                setIgnored(SbBool ignore)
     SbBool              isIgnored() const
          Sets/gets the ignore flag for this field. When a field's ignore flag is  set  to  TRUE,
          the  field  is  not  used during traversal for rendering and other actions. The default
          value for this flag is FALSE.

     SbBool              isDefault() const
          Gets the state of default flag of the field. This flag will be TRUE for any field whose
          value  is not modified after construction and will be FALSE for those that have changed
          (each node or engine determines what the default values for its fields are). Note:  the
          state of this flag should not be set explicitly from within applications.

     static SoType       getClassTypeId()
          Return the type identifier for this field class.

     virtual SoType      getTypeId() const
          Return the type identifier for this field instance (SoField *).

     virtual SbBool      isOfType(SoType type) const
          Returns  TRUE  if  this  field  is  the  given  type or derived from that type. This is
          typically used with the getClassTypeId() method to determine the type of an  SoField  *
          at run-time:

               SoField *field = ....;
               if (field->isOfType(SoSFFloat::getClassTypeId())) {
                   SoSFFloat *floatField = (SoSFFloat *)field);

     SbBool              set(const char *valueString)
          Sets  the  field  to  the  given  value,  which is an ASCII string in the Inventor file
          format. Each field subclass defines its own file format; see their reference pages  for
          information  on  their  file format.  The string should contain only the field's value,
          not the field's name (e.g., "1.0", not "width 1.0"). This method returns  TRUE  if  the
          string is valid, FALSE if it is not.

     void                get(SbString &valueString)
          Returns  the  value of the field in the Inventor file format, even if the field has its
          default value.

     int                 operator ==(const SoField &f) const
     int                 operator !=(const SoField &f) const
          Return TRUE (FALSE) if this field is of the same type and has the same value as f.

     void                touch()
          Simulates a change to the field, causing attached sensors to fire, connected fields and
          engines  to  be  marked  as  needing  evaluation,  and  so forth. Calling touch() on an
          instance of a derived field class is equivalent to calling  setValue(getValue())  using
          the  derived  class's  methods,  except  that  the  field's  isDefault() status remains

     SbBool              connectFrom(SoField *fromField)
     SbBool              connectFrom(SoEngineOutput *fromEngine)
          Connects this field to another field or  from  an  engine  output.  If  the  field  was
          connected  to something before, it will be automatically disconnected (a field may have
          only one connection writing into it at a time). Unless connections  to  the  field  are
          disabled  (see  enableConnection()),  the field's value will be set to the value of the
          thing it is connected to.

     void                disconnect()
          Disconnect the field from whatever it was connected to. This does nothing if the  field
          was not connected.

     SbBool              isConnected() const
          Returns TRUE if the field is connected to anything.

     SbBool              isConnectedFromField() const
          Returns TRUE if the field is connected to another field.

     SbBool              getConnectedField(SoField *&writingField) const
          Returns  TRUE  if  this  field  is being written into by another field, and returns the
          field  it  is  connected  to  in  writingField.  Returns  FALSE  and  does  not  modify
          writingField if it is not connected to a field.

     SbBool              isConnectedFromEngine() const
          Returns TRUE if the field is connected to an engine's output.

     SbBool              getConnectedEngine(SoEngineOutput *&engineOutput) const
          Returns  TRUE  if this field is being written into by an engine, and returns the engine
          output it  is  connected  to  in  engineOutput.  Returns  FALSE  and  does  not  modify
          engineOutput if it is not connected to an engine.

     void                enableConnection(SbBool flag)
          Field connections may be enabled and disabled. Disabling a field's connection is almost
          exactly like disconnecting it; the only difference is that you can later re-enable  the
          connection by calling enableConnection(TRUE).  Note that disconnecting an engine output
          can cause the engine's reference count to be decremented and the engine to be  deleted,
          but disabling the connection does not decrement its reference count.

          Re-enabling  a connection will cause the value of the field to be changed to the engine
          output or field to which it is connected.

          A field's connection-enabled status is maintained even if the field is disconnected  or
          reconnected. By default, connections are enabled.

     SbBool              isConnectionEnabled() const
          Returns  FALSE  if  connections  to  this field are disabled. Note that this may return
          FALSE even if the field is not connected to anything.

     int                 getForwardConnections(SoFieldList &list) const
          Adds pointers to all of the fields that this field is writing into  (either  fields  in
          nodes,  global fields or engine inputs) to the given field list, and returns the number
          of forward connections.

     SoFieldContainer *  getContainer() const
          Returns the object that contains this field. The type of  the  object  will  be  either
          SoNode,  SoEngine,  or  will  be  a  global field container (note that the global field
          container class is internal to Inventor; see the methods  for  creating  and  accessing
          global fields on SoDB). For example:

               SoFieldContainer *f = field->getContainer();
               if (f->isOfType(SoNode::getClassTypeId())) {
                    ... do something ...
               } else if (f->isOfType(SoEngine::getClassTypeId())) {
                    ... do someting else ...
               } else {
                    ... it must be a global field.  We can figure out its name, but
                                   that is about it:
                    const SbName &globalFieldName = f->getName();


       SoSField, SoMField, SoNode, SoDB