SoField Class Reference

Base class for all fields. More...

#include <Inventor/fields/SoField.h>

Inheritance diagram for SoField:

List of all members.

Public Member Functions
virtual	~SoField ()
	Destructor.
void	setIgnored (SbBool ig)
	Sets the ignore flag for this field.
SbBool	isIgnored () const
	Gets the ignore flag for this field.
SbBool	isDefault () const
	Gets the state of default flag of the field.
virtual SoType	getTypeId () const =0
	Return the type identifier for this field instance (SoField *).
SbBool	isOfType (SoType type) const
	Returns TRUE if this field is the given type or derived from that type.
void	enableConnection (SbBool flag)
	Field connections may be enabled and disabled.
SbBool	isConnectionEnabled () const
	Returns FALSE if connections to this field are disabled.
SbBool	connectFrom (SoEngineOutput *engineOutput)
	Connects the field to the given output of an engine or to another field.
SbBool	connectFrom (SoField *field)
void	disconnect ()
	Disconnect the field from whatever it was connected to.
SbBool	isConnected () const
	Returns TRUE if the field is connected to anything.
SbBool	isConnectedFromEngine () const
	Returns TRUE if the field is connected to an engine's output.
SbBool	isConnectedFromField () const
	Returns TRUE if the field is connected to another field.
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.
SbBool	getConnectedField (SoField *&field) const
	Returns TRUE if this field is being written into by another field, and returns the field it is connected to in writingField.
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 containing node or engine.
SbBool	set (const char *valueString)
	Sets the field to the given value, which is an ASCII string in the Inventor file format.
void	get (SbString &valueString)
	Returns the value of the field in the Inventor file format, even if the field has its default value.
virtual 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.
int	operator== (const SoField &f) const
	Return TRUE (FALSE) if this field is of the same type and has the same value as f.
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	setDefault (SbBool def)
	Sets default flag.
virtual void	startNotify ()
	Initiates or propagates notification through container.
virtual void	notify (SoNotList *list)
void	setContainer (SoFieldContainer *cont)
	Sets the containing node.
SbBool	shouldWrite () const
	Returns TRUE if the field really needs to be written out.
void	addAuditor (void *auditor, SoNotRec::Type type)
	Adds/removes an auditor to/from list.
void	removeAuditor (void *auditor, SoNotRec::Type type)
SbBool	enableNotify (SbBool flag)
	Indicates whether notification will propagate as the result of setting the field value.
SbBool	isNotifyEnabled () const
SbBool	enableContainerNotify (SbBool flag)
	Indicates whether notification will propagate to the SoFieldContainer that owns the field.
SbBool	isContainerNotifyEnabled () const
virtual void	connectionStatusChanged (int numConnections)
	Indicates to a field that a change has been made involving a connection from it (as source) to another field.
SbBool	isReadOnly () const
	If this returns TRUE, it means we're in the middle of doing a setValue()+valueChanged() and values from an upstream connection shouldn't write into this field.
virtual SbBool	isSame (const SoField &f) const =0
	Returns TRUE if the given field is of the same type and has the same value(s) as this.
virtual void	copyFrom (const SoField &f)=0
	Copies the value from one field to another, assuming same subclass.
virtual void	fixCopy (SbBool copyConnections)
	After a field value has been copied using copyFrom(), this is called to allow fields to update the copy.
virtual SbBool	referencesCopy () const
	This returns TRUE if this field contains a reference to a node or engine that is copied during a copy operation (i.e., it is "inside").
void	copyConnection (const SoField *fromField)
	Copies connection from one field to another.
virtual SbBool	read (SoInput *in, const SbName &name)
	Reads value of field (with given name) from file as defined by SoInput.
virtual void	write (SoOutput *out, const SbName &name) const
	Writes field (with given name) to file as defined by SoOutput.
virtual void	countWriteRefs (SoOutput *out) const
	Counts write-references on field to prepare for writing.
void	evaluate () const
	Evaluates the field from whatever it's connected to.
Static Public Member Functions
static SoType	getClassTypeId ()
	Return the type identifier for this field class.
static void	initClass ()
static void	initClasses ()
	Initialize ALL Inventor node classes.
Protected Member Functions
	SoField ()
	Constuctor:
void	valueChanged (SbBool resetDefault=TRUE)
	Called by an instance to indicate that a value has changed.
virtual void	evaluateConnection () const
	Evaluates the field or engine the field is connected to, storing the result in the field.
virtual SbBool	readValue (SoInput *in)=0
	Reads value(s) of field.
virtual SbBool	readConnection (SoInput *in)
	Reads connection.
virtual void	writeValue (SoOutput *out) const =0
	Writes value(s) of field.
virtual void	writeConnection (SoOutput *out) const
	Writes field connection.
Friends
class	SoEngineOutput

---

Detailed Description

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 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). 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
}

See Also

SoSField, SoMField, SoNode, SoDB

Definition at line 185 of file SoField.h.

---

Constructor & Destructor Documentation

virtual SoField::~SoField

(

)

[virtual]

SoField::SoField

(

)

[protected]

---

Member Function Documentation

void SoField::addAuditor	(	void *	auditor,
		SoNotRec::Type	type
	)

SbBool SoField::connectFrom

(

SoField *

field

)

SbBool SoField::connectFrom

(

SoEngineOutput *

engineOutput

)

Returns FALSE if the connection could not be made.

virtual void SoField::connectionStatusChanged

(

int

numConnections

)

[virtual]

Passed the number of things being connected to the field; the number will be negative when things are disconnected. The default method does nothing.

void SoField::copyConnection

(

const SoField *

fromField

)

Assumes fields are the same subclass and that this field is connected.

virtual void SoField::copyFrom

(

const SoField &

f

)

[pure virtual]

virtual void SoField::countWriteRefs

(

SoOutput *

out

)

const [virtual]

void SoField::disconnect

(

)

This does nothing if the field was not connected.

void SoField::enableConnection

(

SbBool

flag

)

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 SoField::enableContainerNotify

(

SbBool

flag

)

The default is TRUE, so that a field will notify its container. If disabled, only the direct auditors (connected fields and field sensors) will be notified and the field container does not get a notification. This will prevent unwanted scene repaints (for pure "output fields" that are changed while scene traversal) but has the side effect that the owning field container does not get a new node id and thus one can not detect the field change from the container except by attaching a SoFieldSensor directly to the field. If notification is disabled via enableNotify(FALSE), this flag has no effect. (MeVis Only)

SbBool SoField::enableNotify

(

SbBool

flag

)

Engines turn this off when writing results into fields, since notification has already propagated.

void SoField::evaluate

(

)

const [inline]

If there's no connection or we don't need to evaluate, this does nothing. This has to be const because it's used by getValue methods.

Definition at line 418 of file SoField.h.

Referenced by SoMField::getNum(), and SoSFRotation::getValue().

virtual void SoField::evaluateConnection

(

)

const [protected, virtual]

This is const because it is called by evaluate().

virtual void SoField::fixCopy

(

SbBool

copyConnections

)

[virtual]

This is used by node, engine, and path fields to make sure instances are handled properly. The default implementation does nothing.

Reimplemented in SoMFEngine, SoMFNode, SoMFPath, SoSFEngine, SoSFNode, and SoSFPath.

void SoField::get

(

SbString &

valueString

)

Referenced by SoEngineOutput::operator[]().

static SoType SoField::getClassTypeId

(

)

[inline, static]

Reimplemented in SoSField, and SoMField.

Definition at line 206 of file SoField.h.

SbBool SoField::getConnectedEngine

(

SoEngineOutput *&

engineOutput

)

const

Returns FALSE and does not modify engineOutput if it is not connected to an engine.

SbBool SoField::getConnectedField

(

SoField *&

field

)

const

Returns FALSE and does not modify writingField if it is not connected to a field.

SoFieldContainer* SoField::getContainer

(

)

const

int SoField::getForwardConnections

(

SoFieldList &

list

)

const

virtual SoType SoField::getTypeId

(

)

const [pure virtual]

static void SoField::initClass

(

)

[static]

Reimplemented in SoSField, SoMField, SoMFBitMask, SoMFBool, SoMFColor, SoMFEngine, SoMFEnum, SoMFFloat, SoMFInt32, SoMFMatrix, SoMFName, SoMFNode, SoMFPath, SoMFPlane, SoMFRotation, SoMFShort, SoMFString, SoMFTime, SoMFUInt32, SoMFUShort, SoMFVec2f, SoMFVec3f, SoMFVec4f, SoSFBitMask, SoSFBool, SoSFColor, SoSFEngine, SoSFEnum, SoSFFloat, SoSFImage, SoSFInt32, SoSFMatrix, SoSFName, SoSFNode, SoSFPath, SoSFPlane, SoSFRotation, SoSFShort, SoSFString, SoSFTime, SoSFTrigger, SoSFUInt32, SoSFUShort, SoSFVec2f, SoSFVec3f, SoSFVec4f, SoSFVec2s, and SoSFVec3s.

static void SoField::initClasses

(

)

[static]

SbBool SoField::isConnected

(

)

const [inline]

Definition at line 256 of file SoField.h.

SbBool SoField::isConnectedFromEngine

(

)

const [inline]

Definition at line 258 of file SoField.h.

SbBool SoField::isConnectedFromField

(

)

const [inline]

Definition at line 261 of file SoField.h.

SbBool SoField::isConnectionEnabled

(

)

const [inline]

Note that this may return FALSE even if the field is not connected to anything.

Definition at line 243 of file SoField.h.

SbBool SoField::isContainerNotifyEnabled

(

)

const [inline]

Definition at line 362 of file SoField.h.

SbBool SoField::isDefault

(

)

const [inline]

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.

Definition at line 203 of file SoField.h.

SbBool SoField::isIgnored

(

)

const [inline]

See also:

setIgnored

Definition at line 196 of file SoField.h.

SbBool SoField::isNotifyEnabled

(

)

const [inline]

Definition at line 346 of file SoField.h.

SbBool SoField::isOfType

(

SoType

type

)

const

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);
     floatField->setValue(4.5);
 }
 {}

SbBool SoField::isReadOnly

(

)

const [inline]

Definition at line 375 of file SoField.h.

virtual SbBool SoField::isSame

(

const SoField &

f

)

const [pure virtual]

Subclasses must define this as well as an == operator.

virtual void SoField::notify

(

SoNotList *

list

)

[virtual]

Reimplemented in SoMFPath, SoSFPath, and SoSFTrigger.

int SoField::operator!=

(

const SoField &

f

)

const [inline]

Definition at line 309 of file SoField.h.

int SoField::operator==

(

const SoField &

f

)

const [inline]

Definition at line 305 of file SoField.h.

virtual SbBool SoField::read	(	SoInput *	in,
		const SbName &	name
	)		[virtual]

This does the work common to all fields, then calls other read methods to do the rest.

virtual SbBool SoField::readConnection

(

SoInput *

in

)

[protected, virtual]

virtual SbBool SoField::readValue

(

SoInput *

in

)

[protected, pure virtual]

virtual SbBool SoField::referencesCopy

(

)

const [virtual]

The default method just checks if the field is connected to such a node or engine. Subclasses may contain other tests, such as those that contain pointers to nodes or engines.

Reimplemented in SoMFEngine, SoMFNode, SoMFPath, SoSFEngine, SoSFNode, and SoSFPath.

void SoField::removeAuditor	(	void *	auditor,
		SoNotRec::Type	type
	)

SbBool SoField::set

(

const char *

valueString

)

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 SoField::setContainer

(

SoFieldContainer *

cont

)

This also calls enableNotify(TRUE) and setDefault(TRUE).

void SoField::setDefault

(

SbBool

def

)

[inline]

Definition at line 323 of file SoField.h.

void SoField::setIgnored

(

SbBool

ig

)

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 SoField::shouldWrite

(

)

const

Fields with default values that aren't ignored and aren't connected to anything will return FALSE.

virtual void SoField::startNotify

(

)

[virtual]

Reimplemented in SoSFTrigger.

virtual void SoField::touch

(

)

[virtual]

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.

Reimplemented in SoSFTrigger.

Referenced by SoSFTrigger::setValue().

void SoField::valueChanged

(

SbBool

resetDefault = TRUE

)

[protected]

If resetDefault is TRUE, this turns off default flag. Initiates notification, if necessary.

virtual void SoField::write	(	SoOutput *	out,
		const SbName &	name
	)		const [virtual]

virtual void SoField::writeConnection

(

SoOutput *

out

)

const [protected, virtual]

virtual void SoField::writeValue

(

SoOutput *

out

)

const [protected, pure virtual]

---

Friends And Related Function Documentation

friend class SoEngineOutput [friend]

Definition at line 500 of file SoField.h.

---

Member Data Documentation

SoFieldAuditorInfo* SoField::auditorInfo

Definition at line 476 of file SoField.h.

unsigned int SoField::connected

Definition at line 455 of file SoField.h.

unsigned int SoField::connectionEnabled

Definition at line 458 of file SoField.h.

SoFieldContainer* SoField::container

Definition at line 475 of file SoField.h.

unsigned int SoField::converted

Definition at line 456 of file SoField.h.

unsigned int SoField::dirty

Definition at line 464 of file SoField.h.

unsigned int SoField::fromEngine

Definition at line 457 of file SoField.h.

unsigned int SoField::hasAuditors

Definition at line 460 of file SoField.h.

unsigned int SoField::hasDefault

Definition at line 453 of file SoField.h.

unsigned int SoField::ignored

Definition at line 454 of file SoField.h.

unsigned int SoField::isEngineModifying

Definition at line 461 of file SoField.h.

unsigned int SoField::notifyContainerEnabled

Definition at line 466 of file SoField.h.

unsigned int SoField::notifyEnabled

Definition at line 459 of file SoField.h.

unsigned int SoField::readOnly

Definition at line 462 of file SoField.h.

---

The documentation for this class was generated from the following file:

• MeVis/ThirdParty/Sources/Inventor/inventor/lib/database/include/Inventor/fields/SoField.h