Base class for all fields. More...

#include <Inventor/fields/SoField.h>

Inheritance diagram for SoField:

Public Member Functions
virtual	~SoField ()
	Destructor. More...

void	setIgnored (bool ig)
	Sets the ignore flag for this field. More...

bool	isIgnored () const
	Gets the ignore flag for this field. More...

bool	isDefault () const
	Gets the state of default flag of the field. More...

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

bool	isOfType (SoType type) const
	Returns TRUE if this field is the given type or derived from that type. More...

void	enableConnection (bool flag)
	Field connections may be enabled and disabled. More...

bool	isConnectionEnabled () const
	Returns FALSE if connections to this field are disabled. More...

bool	connectFrom (SoEngineOutput *engineOutput)
	Connects the field to the given output of an engine or to another field. More...

bool	connectFrom (SoField *field)

void	disconnect ()
	Disconnect the field from whatever it was connected to. More...

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

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

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

bool	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`. More...

bool	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`. More...

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. More...

SoFieldContainer *	getContainer () const
	Returns the containing node or engine. More...

bool	set (const char *valueString)
	Sets the field to the given value, which is an ASCII string in the Inventor file format. More...

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

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. More...

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

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

void	setDefault (bool def)
	Sets default flag. More...

virtual void	startNotify ()
	Initiates or propagates notification through container. More...

virtual void	notify (SoNotList *list)

void	setContainer (SoFieldContainer *cont)
	Sets the containing node. More...

bool	shouldWrite () const
	Returns TRUE if the field really needs to be written out. More...

void	addAuditor (void *auditor, SoNotRec::Type type)
	Adds/removes an auditor to/from list. More...

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

bool	enableNotify (bool flag)
	Indicates whether notification will propagate as the result of setting the field value. More...

bool	isNotifyEnabled () const

bool	enableContainerNotify (bool flag)
	Indicates whether notification will propagate to the SoFieldContainer that owns the field. More...

bool	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. More...

bool	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. More...

virtual bool	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. More...

virtual void	copyFrom (const SoField &f)=0
	Copies the value from one field to another, assuming same subclass. More...

virtual void	fixCopy (bool copyConnections)
	After a field value has been copied using copyFrom(), this is called to allow fields to update the copy. More...

virtual bool	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"). More...

void	copyConnection (const SoField *fromField)
	Copies connection from one field to another. More...

virtual bool	read (SoInput *in, const SbName &name)
	Reads value of field (with given name) from file as defined by SoInput. More...

virtual void	write (SoOutput *out, const SbName &name) const
	Writes field (with given name) to file as defined by SoOutput. More...

virtual void	countWriteRefs (SoOutput *out) const
	Counts write-references on field to prepare for writing. More...

void	evaluate () const
	Evaluates the field from whatever it's connected to. More...

Static Public Member Functions
static SoType	getClassTypeId ()
	Return the type identifier for this field class. More...

static void	initClass ()

static void	initClasses ()
	Initialize ALL Inventor node classes. More...

Protected Member Functions
	SoField ()
	Constuctor: More...

void	valueChanged (bool resetDefault=TRUE)
	Called by an instance to indicate that a value has changed. More...

virtual void	evaluateConnection () const
	Evaluates the field or engine the field is connected to, storing the result in the field. More...

virtual bool	readValue (SoInput *in)=0
	Reads value(s) of field. More...

virtual bool	readConnection (SoInput *in)
	Reads connection. More...

virtual void	writeValue (SoOutput *out) const =0
	Writes value(s) of field. More...

virtual void	writeConnection (SoOutput *out) const
	Writes field connection. More...

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

◆ ~SoField()

virtual SoField::~SoField ( )

virtual

◆ SoField()

SoField::SoField ( )

protected

Member Function Documentation

◆ addAuditor()

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

◆ connectFrom() [1/2]

bool SoField::connectFrom ( SoEngineOutput * engineOutput )

Returns FALSE if the connection could not be made.

◆ connectFrom() [2/2]

bool SoField::connectFrom ( SoField * field )

◆ connectionStatusChanged()

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.

◆ copyConnection()

void SoField::copyConnection ( const SoField * fromField )

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

◆ copyFrom()

virtual void SoField::copyFrom ( const SoField & f )

pure virtual

◆ countWriteRefs()

virtual void SoField::countWriteRefs ( SoOutput * out ) const

virtual

◆ disconnect()

void SoField::disconnect ( )

This does nothing if the field was not connected.

◆ enableConnection()

void SoField::enableConnection ( bool 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.

◆ enableContainerNotify()

bool SoField::enableContainerNotify ( bool 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)

◆ enableNotify()

bool SoField::enableNotify ( bool flag )

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

◆ evaluate()

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 SoSFRotationd::getValue(), and SoSFRotation::getValue().

◆ evaluateConnection()

virtual void SoField::evaluateConnection ( ) const

protectedvirtual

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

◆ fixCopy()

virtual void SoField::fixCopy ( bool 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 SoSFPath, SoSFNode, SoSFEngine, SoMFPath, SoMFNode, and SoMFEngine.

◆ get()

void SoField::get ( SbString & valueString )

Referenced by SoEngineOutput::operator[]().

◆ getClassTypeId()

static SoType SoField::getClassTypeId ( )

inlinestatic

Definition at line 206 of file SoField.h.

◆ getConnectedEngine()

bool SoField::getConnectedEngine ( SoEngineOutput *& engineOutput ) const

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

◆ getConnectedField()

bool SoField::getConnectedField ( SoField *& field ) const

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

◆ getContainer()

SoFieldContainer* SoField::getContainer ( ) const

◆ getForwardConnections()

int SoField::getForwardConnections ( SoFieldList & list ) const

◆ getTypeId()

virtual SoType SoField::getTypeId ( ) const

pure virtual

◆ initClass()

static void SoField::initClass ( )

static

◆ initClasses()

static void SoField::initClasses ( )

static

◆ isConnected()

bool SoField::isConnected ( ) const

inline

Definition at line 256 of file SoField.h.

◆ isConnectedFromEngine()

bool SoField::isConnectedFromEngine ( ) const

inline

Definition at line 258 of file SoField.h.

◆ isConnectedFromField()

bool SoField::isConnectedFromField ( ) const

inline

Definition at line 261 of file SoField.h.

◆ isConnectionEnabled()

bool 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.

◆ isContainerNotifyEnabled()

bool SoField::isContainerNotifyEnabled ( ) const

inline

Definition at line 362 of file SoField.h.

◆ isDefault()

bool 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.

◆ isIgnored()

bool SoField::isIgnored ( ) const

inline

See also: setIgnored

Definition at line 196 of file SoField.h.

◆ isNotifyEnabled()

bool SoField::isNotifyEnabled ( ) const

inline

Definition at line 346 of file SoField.h.

◆ isOfType()

bool 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);
}
{}

◆ isReadOnly()

bool SoField::isReadOnly ( ) const

inline

Definition at line 375 of file SoField.h.

◆ isSame()

virtual bool SoField::isSame ( const SoField & f ) const

pure virtual

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

◆ notify()

virtual void SoField::notify ( SoNotList * list )

virtual

Reimplemented in SoSFTrigger, SoSFPath, and SoMFPath.

◆ operator!=()

bool SoField::operator!= ( const SoField & f ) const

inline

Definition at line 309 of file SoField.h.

◆ operator==()

bool SoField::operator== ( const SoField & f ) const

inline

Definition at line 305 of file SoField.h.

◆ read()

virtual bool 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.

◆ readConnection()

virtual bool SoField::readConnection ( SoInput * in )

protectedvirtual

◆ readValue()

virtual bool SoField::readValue ( SoInput * in )

protectedpure virtual

◆ referencesCopy()

virtual bool 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 SoSFPath, SoSFNode, SoSFEngine, SoMFPath, SoMFNode, and SoMFEngine.

◆ removeAuditor()

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

◆ set()

bool 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.

◆ setContainer()

void SoField::setContainer ( SoFieldContainer * cont )

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

◆ setDefault()

void SoField::setDefault ( bool def )

inline

Definition at line 323 of file SoField.h.

◆ setIgnored()

void SoField::setIgnored ( bool 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.

◆ shouldWrite()

bool SoField::shouldWrite ( ) const

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

◆ startNotify()

virtual void SoField::startNotify ( )

virtual

Reimplemented in SoSFTrigger.

◆ touch()

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

◆ valueChanged()

void SoField::valueChanged ( bool resetDefault = TRUE )

protected

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

◆ write()

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

virtual

◆ writeConnection()

virtual void SoField::writeConnection ( SoOutput * out ) const

protectedvirtual

◆ writeValue()

virtual void SoField::writeValue ( SoOutput * out ) const

protectedpure virtual

Friends And Related Function Documentation

◆ SoEngineOutput

friend class SoEngineOutput

friend

Definition at line 500 of file SoField.h.

Member Data Documentation

◆ auditorInfo

SoFieldAuditorInfo* SoField::auditorInfo

Definition at line 476 of file SoField.h.

◆ connected

unsigned int SoField::connected

Definition at line 455 of file SoField.h.

◆ connectionEnabled

unsigned int SoField::connectionEnabled

Definition at line 458 of file SoField.h.

◆ container

SoFieldContainer* SoField::container

Definition at line 475 of file SoField.h.

◆ converted

unsigned int SoField::converted

Definition at line 456 of file SoField.h.

◆ dirty

unsigned int SoField::dirty

Definition at line 464 of file SoField.h.

◆ fromEngine

unsigned int SoField::fromEngine

Definition at line 457 of file SoField.h.

◆ hasAuditors

unsigned int SoField::hasAuditors

Definition at line 460 of file SoField.h.

◆ hasDefault

unsigned int SoField::hasDefault

Definition at line 453 of file SoField.h.

◆ ignored

unsigned int SoField::ignored

Definition at line 454 of file SoField.h.

◆ isEngineModifying

unsigned int SoField::isEngineModifying

Definition at line 461 of file SoField.h.

◆ notifyContainerEnabled

unsigned int SoField::notifyContainerEnabled

Definition at line 466 of file SoField.h.

◆ notifyEnabled

unsigned int SoField::notifyEnabled

Definition at line 459 of file SoField.h.

◆ readOnly

unsigned int SoField::readOnly

Definition at line 462 of file SoField.h.

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

/home/jenkins/workspaces/mevislab/4.1.1_0/build/MeVis/ThirdParty/Sources/Inventor/include/Inventor/fields/SoField.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~SoField()

◆ SoField()

Member Function Documentation

◆ addAuditor()

◆ connectFrom() [1/2]

◆ connectFrom() [2/2]

◆ connectionStatusChanged()

◆ copyConnection()

◆ copyFrom()

◆ countWriteRefs()

◆ disconnect()

◆ enableConnection()

◆ enableContainerNotify()

◆ enableNotify()

◆ evaluate()

◆ evaluateConnection()

◆ fixCopy()

◆ get()

◆ getClassTypeId()

◆ getConnectedEngine()

◆ getConnectedField()

◆ getContainer()

◆ getForwardConnections()

◆ getTypeId()

◆ initClass()

◆ initClasses()

◆ isConnected()

◆ isConnectedFromEngine()

◆ isConnectedFromField()

◆ isConnectionEnabled()

◆ isContainerNotifyEnabled()

◆ isDefault()

◆ isIgnored()

◆ isNotifyEnabled()

◆ isOfType()

◆ isReadOnly()

◆ isSame()

◆ notify()

◆ operator!=()

◆ operator==()

◆ read()

◆ readConnection()

◆ readValue()

◆ referencesCopy()

◆ removeAuditor()

◆ set()

◆ setContainer()

◆ setDefault()

◆ setIgnored()

◆ shouldWrite()

◆ startNotify()

◆ touch()

◆ valueChanged()

◆ write()

◆ writeConnection()

◆ writeValue()

Friends And Related Function Documentation

◆ SoEngineOutput

Member Data Documentation

◆ auditorInfo

◆ connected

◆ connectionEnabled

◆ container

◆ converted

◆ dirty

◆ fromEngine

◆ hasAuditors

◆ hasDefault

◆ ignored

◆ isEngineModifying

◆ notifyContainerEnabled

◆ notifyEnabled

◆ readOnly