SoField(3IV)NAMESoField (SoField) - base class for all fields
INHERITS FROMSoFieldSYNOPSIS
#include <Inventor_c/fields/SoField.h>
Functions from class SoField:
void SoFieldSetIgnored(SoField *this, SbBool ignore)
SbBool SoFieldIsIgnored(const SoField *this)
SbBool SoFieldIsDflt(const SoField *this)
SoType SoFieldGetClassTypeId()
SoType SoFieldGetTypeId(const SoField *this)
SbBool SoFieldIsOfType(const SoField *this, SoType type)
SbBool SoFieldSetFromStr(SoField *this, const char
*valueString)
void SoFieldGetIntoStr(SoField *this, SbString
*valueString)
int SoFieldIsEq(const SoField *this, const SoField *f)
int SoFieldIsNEq(const SoField *this, const SoField *f)
void SoFieldTouch(SoField *this)
SbBool SoFieldConnFromField(SoField *this, SoField
*fromField)
SbBool SoFieldConnFrom(SoField *this, SoEngineOutput
*fromEngine)
void SoFieldDisconn(SoField *this)
SbBool SoFieldIsConn(const SoField *this)
SbBool SoFieldIsConnFromField(const SoField *this)
SbBool SoFieldGetConnField(const SoField *this, SoField
**writingField)
SbBool SoFieldIsConnFromEngine(const SoField *this)
SbBool SoFieldGetConnEngine(const SoField *this,
SoEngineOutput **engineOutput)
void SoFieldEnableConn(SoField *this, SbBool flag)
SbBool SoFieldIsConnEnabled(const SoField *this)
int SoFieldGetForwardConn(const SoField *this,
SoFieldList *list)
SoFieldContainer * SoFieldGetContainer(const SoField *this)
DESCRIPTIONSoField 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.
Page 1SoField(3IV)
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
SoFieldConnectFrom((SoField *)A, (SoField *)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 source.
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).
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
Page 2SoField(3IV)
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
}
FUNCTIONS
void SoFieldSetIgnored(SoField *this, SbBool ignore)
SbBool SoFieldIsIgnored(const SoField *this)
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 SoFieldIsDflt(const SoField *this)
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.
SoType SoFieldGetClassTypeId()
Return the type identifier for this field class.
SoType SoFieldGetTypeId(const SoField *this)
Return the type identifier for this field instance (SoField *).
SbBool SoFieldIsOfType(const SoField *this, SoType type)
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 (SoFieldIsOfType(field, SoSFFloatGetClassTypeId())) {
SoSFFloat *floatField = (SoSFFloat *)field);
SoSFFloatSetValue(floatField, 4.5);
}
Page 3SoField(3IV)
SbBool SoFieldSetFromStr(SoField *this, 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 SoFieldGetIntoStr(SoField *this, SbString
*valueString)
Returns the value of the field in the Inventor file format, even if
the field has its default value.
int SoFieldIsEq(const SoField *this, const SoField *f)
int SoFieldIsNEq(const SoField *this, const SoField *f)
Return TRUE (FALSE) if this field is of the same type and has the
same value as f.
void SoFieldTouch(SoField *this)
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
unchanged.
SbBool SoFieldConnFromField(SoField *this, SoField
*fromField)
SbBool SoFieldConnFrom(SoField *this, 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 EnableConn()), the field's value will be set to the
value of the thing it is connected to.
void SoFieldDisconn(SoField *this)
Disconnect the field from whatever it was connected to. This does
nothing if the field was not connected.
SbBool SoFieldIsConn(const SoField *this)
Returns TRUE if the field is connected to anything.
SbBool SoFieldIsConnFromField(const SoField *this)
Returns TRUE if the field is connected to another field.
SbBool SoFieldGetConnField(const SoField *this, SoField
**writingField)
Returns TRUE if this field is being written into by another field,
and returns the field it is connected to in writingField. Returns
Page 4SoField(3IV)
FALSE and does not modify writingField if it is not connected to a
field.
SbBool SoFieldIsConnFromEngine(const SoField *this)
Returns TRUE if the field is connected to an engine's output.
SbBool SoFieldGetConnEngine(const SoField *this,
SoEngineOutput **engineOutput)
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 SoFieldEnableConn(SoField *this, 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 SoFieldIsConnEnabled(const SoField *this)
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 SoFieldGetForwardConn(const SoField *this,
SoFieldList *list)
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 * SoFieldGetContainer(const SoField *this)
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 = SoFieldGetContainer(field);
if (SoFieldContIsOfType(f, SoNodeGetClassTypeId())) {
... do something ...
} else if (SoFieldContIsOfType(f, SoEngineGetClassTypeId())) {
... do someting else ...
} else {
Page 5SoField(3IV)
... it must be a global field. We can figure out its name, but
that is about it:
const char *globalFieldName = SoFieldContGetName(f);
}
SEE ALSO
SoSField, SoMField, SoNode, SoDB
Page 6
