Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members  

SoField Class Reference

The SoField class is the top-level abstract base class for fields. More...

#include <Inventor/fields/SoField.h>

Inheritance diagram for SoField::

SoMField SoSField SoMFBool SoMFColor SoMFEngine SoMFEnum SoMFFloat SoMFInt32 SoMFMatrix SoMFName SoMFNode SoMFPath SoMFPlane SoMFRotation SoMFShort SoMFString SoMFTime SoMFUInt32 SoMFUShort SoMFVec2f SoMFVec3f SoMFVec4f SoSFBool SoSFColor SoSFEngine SoSFEnum SoSFFloat SoSFImage SoSFInt32 SoSFMatrix SoSFName SoSFNode SoSFPath SoSFPlane SoSFRotation SoSFShort SoSFString SoSFTime SoSFTrigger SoSFUInt32 SoSFUShort SoSFVec2f SoSFVec3f SoSFVec4f List of all members.

Public Methods

virtual ~SoField ()
void setIgnored (SbBool ignore)
SbBool isIgnored (void) const
void setDefault (SbBool def)
SbBool isDefault (void) const
virtual SoType getTypeId (void) const=0
SbBool isOfType (const SoType type) const
void enableConnection (SbBool flag)
SbBool isConnectionEnabled (void) const
SbBool connectFrom (SoEngineOutput *master, SbBool notnotify=FALSE, SbBool append=FALSE)
SbBool appendConnection (SoEngineOutput *master, SbBool notnotify=FALSE)
void disconnect (SoEngineOutput *engineoutput)
SbBool isConnectedFromEngine (void) const
SbBool getConnectedEngine (SoEngineOutput *&master) const
SbBool connectFrom (SoField *master, SbBool notnotify=FALSE, SbBool append=FALSE)
SbBool appendConnection (SoField *master, SbBool notnotify=FALSE)
void disconnect (SoField *field)
SbBool isConnectedFromField (void) const
SbBool getConnectedField (SoField *&master) const
int getNumConnections (void) const
int getForwardConnections (SoFieldList &slavelist) const
int getConnections (SoFieldList &masterlist) const
SbBool connectFrom (SoVRMLInterpOutput *master, SbBool notnotify=FALSE, SbBool append=FALSE)
SbBool appendConnection (SoVRMLInterpOutput *master, SbBool notnotify=FALSE)
void disconnect (SoVRMLInterpOutput *interpoutput)
SbBool isConnectedFromVRMLInterp (void) const
SbBool getConnectedVRMLInterp (SoVRMLInterpOutput *&master) const
void disconnect (void)
SbBool isConnected (void) const
void setContainer (SoFieldContainer *cont)
SoFieldContainergetContainer (void) const
SbBool set (const char *valuestring)
void get (SbString &valuestring)
SbBool shouldWrite (void) const
virtual void touch (void)
virtual void startNotify (void)
virtual void notify (SoNotList *nlist)
SbBool enableNotify (SbBool on)
SbBool isNotifyEnabled (void) const
void addAuditor (void *f, SoNotRec::Type type)
void removeAuditor (void *f, SoNotRec::Type type)
int operator== (const SoField &f) const
int operator!= (const SoField &f) const
virtual void connectionStatusChanged (int numconnections)
SbBool isReadOnly (void) const
virtual SbBool isSame (const SoField &f) const=0
virtual void copyFrom (const SoField &f)=0
virtual void fixCopy (SbBool copyconnections)
virtual SbBool referencesCopy (void) const
void copyConnection (const SoField *fromfield)
virtual SbBool read (SoInput *in, const SbName &name)
virtual void write (SoOutput *out, const SbName &name) const
virtual void countWriteRefs (SoOutput *out) const
void evaluate (void) const
void setFieldType (int type)
int getFieldType (void) const
SbBool getDirty (void) const
void setDirty (SbBool dirty)

Static Public Methods

void initClass (void)
void initClasses (void)
SoType getClassTypeId (void)

Protected Methods

 SoField (void)
void valueChanged (SbBool resetdefault=TRUE)
virtual void evaluateConnection (void) const
virtual SbBool readValue (SoInput *in)=0
virtual void writeValue (SoOutput *out) const=0
virtual SbBool readConnection (SoInput *in)
virtual void writeConnection (SoOutput *out) const
SbBool isDestructing (void) const

Detailed Description

The SoField class is the top-level abstract base class for fields.

Fields is the mechanism used throughout Coin for encapsulating basic data types to detect changes made to them, and to provide conversion, import and export facilities.

Almost all public properties in nodes are stored in fields, and so are the inputs and outputs of engines. So fields can be viewed as the major mechanism for scenegraph nodes and engines to expose their public API.

Forcing data modification to go through a public function interface while hiding the data members makes it possible to automatically detect and react upon changes in the data structures set up by the application programmer.

E.g. the default behavior when changing the value of a field in a scenegraph node is that there'll automatically be a chain of notifications -- from the field to the owner node, from that node to it's parent node, etc all the way through to the top-most root node, where the need for a rendering update will be signalled to the application.

(This notification mechanism is the underlying feature that makes the Coin library classify as a so-called data-driven scenegraph API.

The practical consequences of this is that rendering and many other processing actions is default scheduled to only happen when something has changed in the retained data structures, making the Coin library under normal circumstances much less CPU intensive than so-called "application-driven" scenegraph API, like for instance SGI IRIS Performer, which are continuously re-rendering even when nothing has changed in the data structures or with the camera viewport.)

Note: there are some field classes which has been obsoleted from the Open Inventor API. They are: SoSFLong, SoSFULong, SoMFLong and SoMFULong. You should use these classes instead (respectively): SoSFInt32, SoSFUInt32, SoMFInt32 and SoMFUInt32.

See also:
SoFieldContainer, SoFieldData


Constructor & Destructor Documentation

SoField::~SoField [virtual]
 

Destructor. Disconnects ourself from any connected field, engine or VRML interpolator, before we disconnect all auditors on the field.

SoField::SoField void [protected]
 

This is the base constructor for field classes. It takes care of doing the common parts of data initialization in fields.


Member Function Documentation

void SoField::initClass void [static]
 

Internal method called upon initialization of the library (from SoDB::init()) to set up the type system.

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

void SoField::initClasses void [static]
 

Initialize all the field classes.

void SoField::setIgnored SbBool ignore
 

Sets the flag which indicates whether or not the field should be ignored during certain operations.

The effect of this flag depends on what type of field it is used on, and the type of the node which includes the field.

See also:
isIgnored()

SbBool SoField::isIgnored void const
 

Returns the ignore flag.

See also:
setIgnored()

void SoField::setDefault SbBool def
 

Set whether or not this field should be marked as containing a default value.

See also:
isDefault()

SbBool SoField::isDefault void const
 

Check if the field contains its default value. Fields which has their default value intact will normally not be included in the output when writing scene graphs out to a file, for instance.

See also:
setDefault()

SoType SoField::getTypeId void const [pure virtual]
 

Returns the type identification instance which uniquely identifies the Coin field class the object belongs to.

See also:
getClassTypeId(), SoType

SoType SoField::getClassTypeId void [static]
 

Returns a unique type identifier for this field class.

See also:
getTypeId(), SoType

Reimplemented in SoSField, and SoMField.

SbBool SoField::isOfType const SoType type const
 

Check if this instance is of a derived type or is the same type as the one given with the type parameter.

void SoField::enableConnection SbBool flag
 

This sets a flag value which indicates whether or not the set up connection should be considered active. For as long as the "enable connection" flag is FALSE, no value propagation will be done from any connected source field, engine or interpolator into this field.

If the connection is first disabled and then enabled again, the field will automatically be synchronized with any master field, engine or interpolator.

See also:
isConnectionEnabled()

SbBool SoField::isConnectionEnabled void const
 

Return the current status of the connection enabled flag.

See also:
enableConnection()

SbBool SoField::connectFrom SoEngineOutput * master,
SbBool notnotify = FALSE,
SbBool append = FALSE
 

Connects this field as a slave to master. This means that the value of this field will be automatically updated when master is changed (as long as the connection also is enabled).

If the field output connected from is of a different type from the field connected to, a field converter is inserted. For some combinations of fields no such conversion is possible, and we'll return FALSE.

If this field had any master-relationships beforehand, these are all broken up if append is FALSE.

Call with notnotify if you want to avoid the initial notification of connected auditors (a.k.a. slaves).

See also:
enableConnection(), isConnectionEnabled(), isConnectedFromField() , getConnectedField(), appendConnection(SoEngineOutput *)

SbBool SoField::appendConnection SoEngineOutput * master,
SbBool notnotify = FALSE
 

Connect ourself as slave to another object, while still keeping the other connections currently in place.

See also:
connectFrom()

void SoField::disconnect SoEngineOutput * master
 

Disconnect this field as a slave from master.

SbBool SoField::isConnectedFromEngine void const
 

Returns TRUE if we're connected from an engine.

See also:
isConnected(), isConnectedFromVRMLInterp(), isConnectedFromField() , connectFrom(SoEngineOutput *)

SbBool SoField::getConnectedEngine SoEngineOutput *& master const
 

Returns TRUE if we are connected as a slave to at least one engine. master will be set to the source of the last engine connection made.

See also:
isConnectedFromEngine(), connectFrom(SoEngineOutput *) , appendConnection(SoEngineOutput *)

SbBool SoField::connectFrom SoField * master,
SbBool notnotify = FALSE,
SbBool append = FALSE
 

Connects this field as a slave to master. This means that the value of this field will be automatically updated when master is changed (as long as the connection also is enabled).

If the field connected from has a different type from the field connected to, a field converter is inserted. For some combinations of fields no such conversion is possible, and we'll return FALSE.

If this field had any connections to master fields beforehand, these are all broken up if append is FALSE.

Call with notnotify if you want to avoid the initial notification of connected auditors (a.k.a. slaves).

See also:
enableConnection(), isConnectionEnabled(), isConnectedFromField() , getConnectedField(), appendConnection(SoField *)

SbBool SoField::appendConnection SoField * master,
SbBool notnotify = FALSE
 

Connect ourself as slave to another object, while still keeping the other connections currently in place.

See also:
connectFrom()

void SoField::disconnect SoField * master
 

Disconnect this field as a slave from master.

SbBool SoField::isConnectedFromField void const
 

Returns TRUE if we're a slave of at least one field.

See also:
isConnected(), isConnectedFromEngine(), isConnectedFromVRMLInterp() , connectFrom(SoField *)

SbBool SoField::getConnectedField SoField *& master const
 

Returns TRUE if we are connected as a slave to at least one other field. master will be set to the source field in the last field connection made.

See also:
isConnectedFromField(), connectFrom(SoField *), , appendConnection(SoField *)

int SoField::getNumConnections void const
 

Returns number of fields this field is a slave of.

See also:
getConnections()

int SoField::getForwardConnections SoFieldList & slavelist const
 

Appends all the fields which are auditing this field in slavelist, and returns the number of fields which are our slaves.

int SoField::getConnections SoFieldList & masterlist const
 

Returns number of masters this field is connected to, and places pointers to all of them into masterlist.

Note that we replace the contents of masterlist, i.e. we're not appending new data.

See also:
getNumConnections()

SbBool SoField::connectFrom SoVRMLInterpOutput * master,
SbBool notnotify = FALSE,
SbBool append = FALSE
 

Connects this field as a slave to master. This means that the value of this field will be automatically updated when master is changed (as long as the connection also is enabled).

If the field output connected from is of a different type from the field connected to, a field converter is inserted. For some combinations of fields no such conversion is possible, and we'll return FALSE.

If this field had any master-relationships beforehand, these are all broken up if append is FALSE.

Call with notnotify if you want to avoid the initial notification of connected auditors (a.k.a. slaves).

See also:
enableConnection(), isConnectionEnabled(), isConnectedFromField() , getConnectedField(), appendConnection(SoVRMLInterpOutput *)

SbBool SoField::appendConnection SoVRMLInterpOutput * master,
SbBool notnotify = FALSE
 

Connect ourself as slave to another object, while still keeping the other connections currently in place.

See also:
connectFrom()

void SoField::disconnect SoVRMLInterpOutput * master
 

Disconnect this field as a slave from master.

SbBool SoField::isConnectedFromVRMLInterp void const
 

Returns TRUE if we're a slave of at least one VRML interpolator.

See also:
isConnected(), isConnectedFromEngine(), isConnectedFromField() , connectFrom(SoVRMLInterpOutput *)

SbBool SoField::getConnectedVRMLInterp SoVRMLInterpOutput *& master const
 

Returns TRUE if we are connected as a slave to at least one VRML interpolator. master will be set to the source of the last interpolator connection made.

See also:
isConnectedFromVRMLInterp(), connectFrom(SoVRMLInterpOutput *) , appendConnection(SoVRMLInterpOutput *)

void SoField::disconnect void
 

Disconnect all connections from this field as a slave to master fields, engine outputs or VRML interpolator outputs.

SbBool SoField::isConnected void const
 

Returns TRUE if we're connected from another field, engine or interpolator.

See also:
isConnectedFromField(), isConnectedFromEngine() , isConnectedFromVRMLInterp(), connectFrom()

void SoField::setContainer SoFieldContainer * cont
 

Let the field know to which container it belongs.

See also:
getContainer(), SoFieldContainer

SoFieldContainer * SoField::getContainer void const
 

Returns the SoFieldContainer object "owning" this field.

See also:
SoFieldContainer, setContainer()

SbBool SoField::set const char * valuestring
 

Set the field's value through the given valuestring. The format of the string must adhere to the ASCII format used in Coin data format files.

Only the value should be specified - not the name of the field.

FALSE is returned if the field value is invalid for the field type and can't be parsed in any sensible way.

See also:
get()

void SoField::get SbString & valuestring
 

Returns the field's value as an ASCII string in the export data format for Inventor files.

See also:
set()

SbBool SoField::shouldWrite void const
 

Returns TRUE if it is necessary to write the field when dumping a scene graph. This needs to be done if the field is not default (it has been changed from its default value), if it's ignored, or if it's connected from another field or engine.

void SoField::touch void [virtual]
 

Notify the field as well as the field's owner / container that it has been changed.

Touching a field which is part of any component (engine or node) in a scene graph will lead to a forced redraw. This is useful if you have been doing several updates to the field wrapped in a pair of enableNotify() calls to notify the field's auditors that its value has changed.

See also:
setValue(), enableNotify()

Reimplemented in SoSFTrigger.

void SoField::startNotify void [virtual]
 

Trigger a notification sequence.

At the end of a notification sequence, all "immediate" sensors (i.e. sensors set up with a zero priority) are triggered.

Reimplemented in SoSFTrigger.

void SoField::notify SoNotList * l [virtual]
 

Notify auditors that this field has changed.

Reimplemented in SoSFTrigger, SoSFPath, and SoMFPath.

SbBool SoField::enableNotify SbBool on
 

This method sets whether notification will be propagated on changing the value of the field. The old value of the setting is returned.

See also:
isNotifyEnabled()

SbBool SoField::isNotifyEnabled void const
 

This method returns whether notification of changes to the field value are propagated to the auditors.

See also:
enableNotify()

void SoField::addAuditor void * f,
SoNotRec::Type type
 

Add an auditor to the list. All auditors will be notified whenever this field changes its value(s).

void SoField::removeAuditor void * f,
SoNotRec::Type type
 

Remove an auditor from the list.

int SoField::operator== const SoField & f const
 

Checks for equality. Returns 0 if the fields are of different type or the field's value(s) are not equal.

int SoField::operator!= const SoField & f const
 

Returns TRUE if the fields are of different type or has different value.

void SoField::connectionStatusChanged int numconnections [virtual]
 

Called whenever another slave attaches or detaches itself to us. numconnections is the difference in number of connections made (i.e. if stuff is disconnected, numconnections will be a negative number).

The default method is empty. Overload in subclasses if you want do something special on connections/deconnections.

SbBool SoField::isReadOnly void const
 

Returns TRUE if this field should not be written into at the moment the method is called.

This method is used internally in Coin during notification and evaluation processes, and should normally not be of interest to the application programmer.

SbBool SoField::isSame const SoField & f const [pure virtual]
 

Check for equal type and value(s).

void SoField::copyFrom const SoField & f [pure virtual]
 

Copy value(s) from f into this field.

void SoField::fixCopy SbBool copyconnections [virtual]
 

This method is internally called after copyFrom() during scene graph copies, and should do the operations necessary for fixing up the field instance after it has gotten a new value.

The default method in the SoField superclass does nothing.

The application programmer should normally not need to consider this method, unless he constructs a complex field type which contains new references to container instances (i.e. nodes or engines). Overloading this method is then necessary to update the reference pointers, as they could have been duplicated during the copy operation.

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

SbBool SoField::referencesCopy void const [virtual]
 

Returns TRUE if this field has references to any containers in the scene graph which are also duplicated during the copy operation.

Note that this method only is valid to call during copy operations.

See also the note about the relevance of the fixCopy() method for application programmers, as it is applicable on this method aswell.

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

void SoField::copyConnection const SoField * fromfield
 

If fromfield contains a connection to another field, make this field also use the same connection.

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

Reads and sets the value of this field from the given SoInput instance. Returns FALSE if the field value can not be parsed from the input.

This field has the name given as the second argument.

See also:
set(), write()

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

Write the value of the field to the given SoOutput instance (which can be either a memory buffer or a file, in ASCII or in binary format).

See also:
get(), read(), SoOutput

void SoField::countWriteRefs SoOutput * out const [virtual]
 

This method is called during the first pass of write operations, to count the number of write references to this field and to "forward" the reference counting operation to the field containers we're connected to.

void SoField::evaluate void const
 

Re-evaluates the value of this field any time a getValue() call is made and the field is marked dirty. This is done in this way to gain the advantages of having lazy evaluation.

void SoField::setFieldType int type
 

Set type of this field.

The possible values for type is: 0 for ordinary fields, 1 for VRML2 eventIn fields, 2 for VRML2 eventOut fields, 3 for some other type of eventIn field, 4 for internal fields, 5 for VRML2 exposedField fields.

Note: this method is only used for VRML2 support, and is therefore not "active" yet.

int SoField::getFieldType void const
 

Return the type of this field.

See also:
setFieldType()

SbBool SoField::getDirty void const
 

Do we need re-evaluation?

void SoField::setDirty SbBool dirty
 

Mark field for re-evaluation, but do not trigger it.

void SoField::valueChanged SbBool resetdefault = TRUE [protected]
 

This method is always called whenever the field's value has been changed by direct invocation of setValue() or some such. You should never call this method from anywhere in the code where the field value is being set through an evaluation of its connections.

If resetdefault is TRUE, the flag marking whether or not the field has its default value will be set to FALSE.

The method will also notify any auditors that the field's value has changed.

void SoField::evaluateConnection void const [protected, virtual]
 

If we're connected to a field/engine/interpolator, copy the value from the master source.

SbBool SoField::readValue SoInput * in [protected, pure virtual]
 

Read field value(s).

void SoField::writeValue SoOutput * out const [protected, pure virtual]
 

Write field value(s).

SbBool SoField::readConnection SoInput * in [protected, virtual]
 

Read the fieldcontainer and master field id of a field-to-field connection.

void SoField::writeConnection SoOutput * out const [protected, virtual]
 

Write out information about this field's connection.

SbBool SoField::isDestructing void const [protected]
 

Can be used to check if a field is being destructed.


The documentation for this class was generated from the following files:
Generated at Tue Mar 5 03:31:24 2002 for Coin by doxygen1.2.9 written by Dimitri van Heesch, © 1997-2001