Castle Game Engine: X3DFields: Class TX3DField

# Class TX3DField
Description | Hierarchy | Fields | Methods | Properties
## Unit X3DFields ## Declaration `type TX3DField = class(TX3DFieldOrEvent)` ## Description Base class for all VRML/X3D fields. Common notes for all descendants: most of them expose field or property "Value", this is (surprise, surprise!) the value of the field. Many of them also expose DefaultValue and DefaultValueExists fields/properties, these should be the default VRML value for this field. You can even change DefaultValue after the object is created. Most of descendants include constructor that initializes both DefaultValue and Value to the same thing, as this is what you usually want. Some notes about `Assign` method (inherited from TPersistent and overridied appropriately in `TX3DField` descendants): There are some exceptions, but usually assignment is possible only when source and destination field classes are equal. Assignment (by `Assign`, inherited from TPersistent) tries to copy everything: name (with alternative names), default value, IsClauseNames, ValueFromIsClause, Exposed, and of course current value. Exceptions are things related to hierarchy of containers: ParentNode, ParentInterfaceDeclaration. Also ExposedEventsLinked. If you want to copy only the current value, use AssignValue (or AssignLerp, where available). ## Hierarchy TPersistent TNonRefCountedInterfacedPersistent TX3DFileItem TX3DFieldOrEvent TX3DField ## Overview ### Methods
| `procedure SaveToStreamValue(Writer: TX3DWriter); virtual; abstract;`
| `function SaveToXmlValue: TSaveToXmlMethod; virtual;`
| `procedure VRMLFieldAssignCommon(Source: TX3DField);`
| `procedure AssignValueRaiseInvalidClass(Source: TX3DField);`
| `class function ExposedEventsFieldClass: TX3DFieldClass; virtual;`
| `procedure ExposedEventReceive(Event: TX3DEvent; Value: TX3DField; const Time: TX3DTime); virtual;`
| `constructor Create(AParentNode: TX3DFileItem; const AName: string);`
| `constructor CreateUndefined(AParentNode: TX3DFileItem; const AName: string; const AExposed: boolean); virtual;`
| `destructor Destroy; override;`
| `procedure Parse(Lexer: TX3DLexer; Reader: TX3DReader; IsClauseAllowed: boolean);`
| `procedure ParseValue(Lexer: TX3DLexer; Reader: TX3DReader); virtual; abstract;`
| `procedure ParseXMLAttributeLexer(Lexer: TX3DLexer; Reader: TX3DReader); virtual;`
| `procedure ParseXMLAttribute(const AttributeValue: string; Reader: TX3DReader); virtual;`
| `procedure ParseXMLElement(Element: TDOMElement; Reader: TX3DReader); virtual;`
| `procedure FieldSaveToStream(Writer: TX3DWriter; FieldSaveWhenDefault: boolean = false; XmlAvoidSavingNameBeforeValue: boolean = false);`
| `procedure SaveToStream(Writer: TX3DWriter); override;`
| `function SaveToXml: TSaveToXmlMethod; override;`
| `function EqualsDefaultValue: boolean; virtual;`
| `function Equals(SecondValue: TX3DField; const EqualityEpsilon: Double): boolean; virtual; reintroduce;`
| `function FastEqualsValue(SecondValue: TX3DField): boolean; virtual;`
| `function EventIn: TX3DEvent;`
| `function EventOut: TX3DEvent;`
| `class function TypeName: string; virtual;`
| `class function CreateEvent(const AParentNode: TX3DFileItem; const AName: string; const AInEvent: boolean): TX3DEvent; virtual;`
| `procedure AssignValue(Source: TX3DField); virtual;`
| `procedure AssignDefaultValueFromValue; virtual;`
| `procedure AssignLerp(const A: Double; Value1, Value2: TX3DField); virtual;`
| `function CanAssignLerp: boolean; virtual;`
| `procedure AddAlternativeName(const AlternativeName: string; VrmlMajorVersion: Integer); override;`
| `procedure Changed;`
| `function ExecuteChanges: TX3DChanges; virtual;`
| `procedure Send(Value: TX3DField);`
| `function OnReceive: TX3DEventReceiveList;`
### Properties
| `property ValueFromIsClause: boolean read FValueFromIsClause write FValueFromIsClause;`
| `property Exposed: boolean read FExposed write SetExposed default true;`
| `property ExposedEvents [InEvent:boolean]: TX3DEvent read GetExposedEvents;`
| `property ExposedEventsLinked: boolean read FExposedEventsLinked write SetExposedEventsLinked default true;`
| `property ChangesAlways: TX3DChanges read FChangesAlways write FChangesAlways;`
## Description ### Methods
| `procedure SaveToStreamValue(Writer: TX3DWriter); virtual; abstract;`
Save field value to a stream. Must be overriden for each specific field. For classic encoding, FieldSaveToStream and SaveToStream write Indent, Name, ' ', then call `SaveToStreamValue`, then write NL. IS clauses are not saved by FieldSaveToStream or SaveToStream. (They must be saved specially, by SaveToStreamClassicIsClauses or special XML output.) SaveToStream still checks ValueFromIsClause, if ValueFromIsClause we will not call `SaveToStreamValue`. So when overriding `SaveToStreamValue`, you can safely assume that ValueFromIsClause is `False`.
| `function SaveToXmlValue: TSaveToXmlMethod; virtual;`
Save method of SaveToStreamValue. May assume things that SaveToStreamValue may issume, for example: if this is used at all, then at least field value is not default (so there is a need to write this field) and such.
| `procedure VRMLFieldAssignCommon(Source: TX3DField);`
Call this inside overriden Assign methods. I don't want to place this inside TX3DField.Assign, since I want "inherited" in Assign methods to cause exception.
| `procedure AssignValueRaiseInvalidClass(Source: TX3DField);`
| `class function ExposedEventsFieldClass: TX3DFieldClass; virtual;`
Class of the fields allowed in the exposed events of this field. This should usually be using ClassType of this object, and this is the default implementation of this method in TX3DField. You can override this to return some ancestor (from which, and to which, you can assign) if your TX3DField descendant doesn't change how the `Assign` method works. E.g. TSFTextureUpdate class, that wants to be fully compatible with normal TSFString.
| `procedure ExposedEventReceive(Event: TX3DEvent; Value: TX3DField; const Time: TX3DTime); virtual;`
Handle exposed input event. In TX3DField class, this does everything usually needed — assigns value, sends an output event, notifies Changed. You can override this for some special purposes. For special needs, you do not even need to call `inherited` in overriden versions. This is suitable e.g. for cases when TimeSensor.set_startTime or such must be ignored.
| `constructor Create(AParentNode: TX3DFileItem; const AName: string);`
Normal constructor. Descendants implementors notes: when implementing constructors in descendants, remember that Create in this class actually just calls CreateUndefined, and CreateUndefined is virtual. So when calling `inherited Create`, be aware that actually you may be calling your own overriden CreateUndefined. In fact, in descendants you should focus on moving all the work to CreateUndefined constructor. The Create constructor should be just a comfortable extension of CreateUndefined, that does the same and addiionally gets parameters that specify default field value.
| `constructor CreateUndefined(AParentNode: TX3DFileItem; const AName: string; const AExposed: boolean); virtual;`
Virtual constructor, that you can use to construct field instance when field class is known only at runtime. The idea is that in some cases, you need to create fields using variable like FieldClass: TX3DFieldClass. See e.g. TX3DInterfaceDeclaration, VRML 2.0 feature that simply requires this ability, also implementation of TX3DSimpleMultField.Parse and TX3DSimpleMultField.CreateItemBeforeParse. Later you can initialize such instance from string using it's Parse method. Note that some exceptional fields simply cannot work when initialized by this constructor: these are SFEnum and SFBitMask fields. They simply need to know their TSFEnum.EnumNames, or TSFBitMask.FlagNames + TSFBitMask.NoneString + TSFBitMask.AllString before they can be parsed. I guess that's one of the reasons why these field types were entirely removed from VRML 2.0.
| `destructor Destroy; override;`
| `procedure Parse(Lexer: TX3DLexer; Reader: TX3DReader; IsClauseAllowed: boolean);`
Parse inits properties from Lexer. In this class, Parse only appends to IsClauseNames: if we stand on "IS" clause (see VRML 2.0 spec about "IS" clause) and IsClauseAllowed then we append specified identifier to IsClauseNames. If "IS" clause not found, we call ParseValue which should actually parse field's value. Descendants should override ParseValue.
| `procedure ParseValue(Lexer: TX3DLexer; Reader: TX3DReader); virtual; abstract;`
| `procedure ParseXMLAttributeLexer(Lexer: TX3DLexer; Reader: TX3DReader); virtual;`
Parse field value from X3D XML encoded attribute using a Lexer. Attributes in X3D are generally encoded such that normal `ParseValue(Lexer, nil)` call is appropriate, so this is done in this class.
| `procedure ParseXMLAttribute(const AttributeValue: string; Reader: TX3DReader); virtual;`
Parse field value from X3D XML encoded attribute. Implementation in this class creates a Lexer to parse the string, and calls ParseXMLAttributeLexer.
| `procedure ParseXMLElement(Element: TDOMElement; Reader: TX3DReader); virtual;`
Parse field's value from XML Element children. This is used to read SFNode / MFNode field value inside <field> (for interface declaration default field value) and <fieldValue> inside <ProtoInstance>.
| `procedure FieldSaveToStream(Writer: TX3DWriter; FieldSaveWhenDefault: boolean = false; XmlAvoidSavingNameBeforeValue: boolean = false);`
Save the field to the stream. Field name (if set, omitted if empty) and value are saved. Unless the current field value equals default value and FieldSaveWhenDefault is `False` (default), then nothing is saved. IS clauses are not saved here (because they often have to be treated specially anyway, for XML encoding, for prototype declarations etc.).
| `procedure SaveToStream(Writer: TX3DWriter); override;`
Save the field to the stream. This simply calls FieldSaveToStream(Writer). See FieldSaveToStream for more comments and when you need control over FieldSaveWhenDefault behavior. It doesn't actually save anything if field value is defined and equals default value.
| `function SaveToXml: TSaveToXmlMethod; override;`
| `function EqualsDefaultValue: boolean; virtual;`
Zwraca zawsze false w tej klasie. Mozesz to przedefiniowac w podklasach aby SaveToStream nie zapisywalo do strumienia pol o wartosci domyslnej.
| `function Equals(SecondValue: TX3DField; const EqualityEpsilon: Double): boolean; virtual; reintroduce;`
`True` if the SecondValue object has exactly the same type and properties. For this class, this returns just (SecondValue.Name = Name). All descendants (that add some property that should be compared) should override this like
      Result := (inherited Equals(SecondValue, EqualityEpsilon)) and
        (SecondValue is TMyType) and
        (TMyType(SecondValue).MyProperty = MyProperty);
For varius floating-point fields in this unit: we compare each float using EqualityEpsilon, i.e. if the difference is < EqualityEpsilon then the floats are assumed equal. Pass EqualityEpsilon = 0.0 to perform *exact* comparison (this case will be optimized in implementation, by using routines like CompareMem instead of comparing float-by-float). Note that this *doesn't* compare the default values of two fields instances. This compares only the current values of two fields instances, and eventually some other properties that affect parsing (like names for TSFEnum and TSFBitMask) or allowed future values (like TSFFloat.MustBeNonnegative).
| `function FastEqualsValue(SecondValue: TX3DField): boolean; virtual;`
Compare value of this field, with other field, fast. This compares only the values of the fields, not other properties (it doesn't care about names of the fields or such, or default values; only current values). In other words, it compares only the things copied by AssignValue. This tries to compare very fast, which means that for large (multi-valued) fields it may give up and answer `False` even when they are in fact equal. So this is usable only for optimization purposes: when it answers `True`, it is `True`. When it answers `False`, it actually doesn't know. Default implementation in this class (`TX3DField`) just returns `False`.
| `function EventIn: TX3DEvent;`
Exposed events of this field. `Nil` if this field is not exposed. `EventIn` is always equivalent to ExposedEvents[true], EventOut is always equivalent to ExposedEvents[false].
| `function EventOut: TX3DEvent;`
| `class function TypeName: string; virtual;`
Field type name in VRML/X3D. As for VRML/X3D interface declaration statements. In base TX3DField class, this teturns `XFAny` (name indicating any type, used by instantreality and us).
| `class function CreateEvent(const AParentNode: TX3DFileItem; const AName: string; const AInEvent: boolean): TX3DEvent; virtual;`
Create TX3DEvent descendant suitable as exposed event for this field.
| `procedure AssignValue(Source: TX3DField); virtual;`
Copies the current field value. Contrary to TPersistent.Assign, this doesn't copy the rest of properties. After setting, our ValueFromIsClause is always changed to `False`. You can manually change it to `True`, if this copy indeed was done following "IS" clause. Descendants implementors notes: In this class, implementation takes care of setting our ValueFromIsClause to `False`. In descendants, you should do like
            if Source is <appropriate class> then
            begin
              inherited;
              Value := Source.value;
            end else
              AssignValueRaiseInvalidClass(Source);
###### Exceptions raised EX3DFieldAssignInvalidClass Usually it's required the Source class to be equal to our class, if Source classes cannot be assigned we raise EX3DFieldCannotAssignClass. EX3DFieldAssign Raised in case of any field assignment problem. It's guaranteed that in case of such problem, our value will not be modified before raising the exception. EX3DFieldAssignInvalidClass inherits from EX3DFieldAssign, so actually EX3DFieldAssignInvalidClass is just a special case of this exceptiion.
| `procedure AssignDefaultValueFromValue; virtual;`
Set field's default value from the current value. Note that for now this doesn't guarantee that every possible field's value can be stored as default value. In case of trouble, it will silently record "no default is known" information, so e.g. EqualsDefaultValue will always return `False`. Our default value mechanisms are sometimes limited, not every value can be a default value. For example, for multiple-valued nodes, we usually cannot save arrays longer than one as default value. This is not a problem, since X3D specification doesn't specify too long default values. But it may be a problem for prototypes, since then user can assign any value as default value. May be corrected in the future.
| `procedure AssignLerp(const A: Double; Value1, Value2: TX3DField); virtual;`
Assigns value to this node calculated from linear interpolation between two given nodes Value1, Value2. Just like other lerp functions in our units (like CastleVectors.Lerp). Like AssignValue, this copies only the current value. All other properties (like Name, IsClauseNames, ValueFromIsClause, default value) are untouched. There are some special precautions for this: First of all, `AssignLerp` is defined only for fields where CanAssignLerp returns `True`, so always check CanAssignLerp first. All float-based VRML fields should have this implemented. Use this only if Value1 and Value2 are equal or descendant of target (Self) class. For multiple-value fields, counts of Value1 and Value2 must be equal, or EX3DMultFieldDifferentCount will be raised. ###### Exceptions raised EX3DMultFieldDifferentCount When field is multiple-value VRML field and Value1.Count <> Value2.Count.
| `function CanAssignLerp: boolean; virtual;`
Is AssignLerp usable on this field type? Descendants implementors notes: In this class, this always returns `False`.
| `procedure AddAlternativeName(const AlternativeName: string; VrmlMajorVersion: Integer); override;`
| `procedure Changed;`
Notify ParentNode.Scene that the value of this field changed.
| `function ExecuteChanges: TX3DChanges; virtual;`
What happens when the value of this field changes. This is called, exactly once, by TCastleSceneCore.ChangedField to determine what must be done when we know that value of this field changed. In overridden descendants, this can also do something immediately. Overriding this is similar to registering your callback in OnReceive list, with two benefits: This method may be not called (although no guarantees) when the actual field value did not change. In contrast, the OnReceive event is always fired, even when you send the same value to an exposed field, because VRML/X3D events and routes must be fired anyway. This is useful also for fields that are not exposed, and can be changed only by ObjectPascal code. So overridding this is closer to "do something when field value changes" than registering callback in OnReceive list.
| `procedure Send(Value: TX3DField);`
Set the value of the field, notifying the scenes and events engine. This sets the value of this field in the nicest possible way for any possible TCastleSceneCore (with events on or off) containing the node with this field. Precise specification: If this is an exposed field and we have events engine working: We will send this value through it's input event. In this case, this is equivalent to doing `EventIn.Send(Value, Scene.Time)`. The scenes (including events engine) will be notified correctly by exposed events handler already. Otherwise, we will just set the fields value. And then notify the scenes (including events engine).
| `function OnReceive: TX3DEventReceiveList;`
Notifications when exposed field received new value through VRML/X3D event. Only for exposed fields (`Nil` for not exposed fields). This is simply a shortcut for `EventOut.OnReceive`, see TX3DEvent.OnReceive for details how does this work. Note that this observes the "out" event (not the "in" event). This way you know inside the handler that the field value is already changed as appropriate. Inside "in" event handlers, you would not know this (it would depend on the order in which handlers are run, one "in" handler sets the field value). Note that "out" event handlers are executed before Scene is notified about the field value change (before TCastleSceneCore.ChangedField is called). This is also usually exactly what you want — you can change the scene graph inside the event handler (for example, load something on Inline.load or Inline.url changes), and let the TX3DField.ChangesAlways cause appropriate action on this change.
### Properties
| `property ValueFromIsClause: boolean read FValueFromIsClause write FValueFromIsClause;`
Does current field value came from expanding "IS" clause. If yes, then saving this field to stream will only save it's "IS" clauses, never saving actual value.
| `property Exposed: boolean read FExposed write SetExposed default true;`
Does this field generate/accept events, that is an "exposedField" (in VRML 2.0) or "inputOutput" (in X3D).
| `property ExposedEvents [InEvent:boolean]: TX3DEvent read GetExposedEvents;`
These are the set_xxx and xxx_changed events exposed by this field. `Nil` if Exposed is `False`.
| `property ExposedEventsLinked: boolean read FExposedEventsLinked write SetExposedEventsLinked default true;`
When `True` (default) we will automatically handle exposed events behavior. This means that we will listen on EventIn, and when something will be received we will set current field's value and produce appropriate EventOut. You almost certainly want to leave this as `True` in all typical situations, as it takes care of implementing required exposed events behavior. That said, in special cases you may decide to break this.
| `property ChangesAlways: TX3DChanges read FChangesAlways write FChangesAlways;`
What always happens when the value of this field changes. This is included in the ExecuteChanges method result. So instead of using this property, you could always override ExecuteChanges method. But often it's easier to use the property. By default this is an empty set. This is suitable for things that aren't *directly* an actual content (but only an intermediate value to change other stuff). This includes all metadata fields and nodes, all fields in event utilities, Script node, interpolators... See TX3DChange for possible values.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:13