Class TX3DField

Unit

Declaration

type TX3DField = class(TX3DFieldOrEvent)

Description

Base class for all VRML/X3D fields.

Common notes for all descendants: most of them expose a field or property "Value", which specifies the current value of the field. Many of them also expose DefaultValue and DefaultValueExists fields/properties, these should be the default X3D 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):

  1. There are some exceptions, but usually assignment is possible only when source and destination field classes are equal.

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

Overview

Fields

Public OnInputIgnore: TInputIgnoreEvent;

Methods

Public constructor CreateUndefined(const AParentNode: TX3DFileItem; const AExposed: boolean; const AName: String); virtual;
Public destructor Destroy; override;
Public procedure Parse(Lexer: TX3DLexer; Reader: TX3DReader; IsClauseAllowed: boolean);
Public procedure ParseValue(Lexer: TX3DLexer; Reader: TX3DReader); virtual; abstract;
Public procedure ParseXMLAttributeLexer(Lexer: TX3DLexer; Reader: TX3DReader); virtual;
Public procedure ParseXMLAttribute(const AttributeValue: String; Reader: TX3DReader); virtual;
Public procedure ParseXMLElement(Element: TDOMElement; Reader: TX3DReader); virtual;
Public procedure FieldSaveToStream(Writer: TX3DWriter; FieldSaveWhenDefault: boolean = false; XmlAvoidSavingNameBeforeValue: boolean = false);
Public procedure SaveToStream(Writer: TX3DWriter); override;
Public function SaveToXml: TSaveToXmlMethod; override;
Public function EqualsDefaultValue: boolean; virtual;
Public function Equals(SecondValue: TX3DField): boolean; reintroduce; virtual;
Public function FastEqualsValue(SecondValue: TX3DField): boolean; virtual;
Public function EventIn: TX3DEvent;
Public function EventOut: TX3DEvent;
Public class function X3DType: String; virtual;
Public class function TypeName: String; deprecated 'use X3DType';
Public class function CreateEvent(const AParentNode: TX3DFileItem; const AName: String; const AInEvent: boolean): TX3DEvent; virtual;
Public procedure AssignValue(Source: TX3DField); virtual;
Public procedure AssignDefaultValueFromValue; virtual;
Public procedure UnassignDefaultValue; virtual;
Public procedure AssignLerp(const A: Double; Value1, Value2: TX3DField); virtual;
Public function CanAssignLerp: boolean; virtual;
Public procedure AddAlternativeName(const AlternativeName: String; const X3DMajorVersion: Integer); override;
Public procedure Changed;
Public function ExecuteChange: TX3DChange; virtual;
Public procedure Send(Value: TX3DField); overload;
Public procedure AddNotification(const Notification: TX3DEventReceive);
Public procedure RemoveNotification(const Notification: TX3DEventReceive);

Properties

Public property ValueFromIsClause: boolean read FValueFromIsClause write FValueFromIsClause;
Public property Exposed: boolean read FExposed write SetExposed default false;
Public property ExposedEvents [InEvent: boolean]: TX3DEvent read GetExposedEvents;
Public property ExposedEventsLinked: boolean read FExposedEventsLinked write SetExposedEventsLinked default true;
Public property ChangeAlways: TX3DChange read FChangeAlways write FChangeAlways default chNone;

Description

Fields

Public OnInputIgnore: TInputIgnoreEvent;

This item has no description.

Methods

Public constructor CreateUndefined(const AParentNode: TX3DFileItem; const AExposed: boolean; const AName: String); virtual;

Main constructor that initializes field when default value is not known.

It is virtual, so you can use it to construct field instance when field class is known only at runtime. For example you can have variable like "FieldClass: TX3DFieldClass" and use it to construct the field instance. Such field can be later initialized e.g. using Parse.

Note: Two exceptional VRML 1.0 fields simply cannot work when initialized by this constructor: TSFEnum and TSFBitMask . They simply need to know their TSFEnum.EnumNames, or TSFBitMask.FlagNames + TSFBitMask.NoneString + TSFBitMask.AllString before they can be parsed. Luckily these fields have been removed in VRML 2.0 and X3D so we don't need to support them e.g. in VRML 2.0 and X3D prototypes.

Descendants implementors:

1. Descendants should override this virtual constructor, CreateUndefined, to do all obligatory initialization work (e.g. create some internal TStringList).

Call "inherited" at the beginning of the implementation of this overridden "CreateUndefined".

2. Can Create also a convenience non-virtual constructor Create, that takes as parameter initial value (with type specific to given field, e.g. Integer for TSFInt32).

This convenience constructor should call "CreateUndefined" (not "inherited Create" or "inherited CreateUndefined"!) at the beginning.

TODO: Rename this to just Create, to obscure parent Create. After everything migrated to calling CreateUndefined.

Public destructor Destroy; override;

This item has no description.

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

Public procedure ParseValue(Lexer: TX3DLexer; Reader: TX3DReader); virtual; abstract;

This item has no description.

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

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

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

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

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

Public function SaveToXml: TSaveToXmlMethod; override;

This item has no description. Showing description inherited from TX3DFileItem.SaveToXml.

How is this saved to X3D XML encoding. This determines when SaveToStream is called. It also cooperates with some SaveToStream implementations, guiding how the item is actually saved. By default it is sxChildElement.

Public function EqualsDefaultValue: boolean; virtual;

Whether the value is equal to default. Returns always False in TX3DField, descendants should override it. It is used when writing the field value to X3D file (values that are default do not have to be written, ever).

Public function Equals(SecondValue: TX3DField): boolean; reintroduce; virtual;

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)) and
  (SecondValue is TMyType) and
  (TMyType(SecondValue).MyProperty = MyProperty);

The floating-point fields may be compared with a small epsilon tolerance by this method.

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

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

Public 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].

Public function EventOut: TX3DEvent;

This item has no description.

Public class function X3DType: String; virtual;

Field type in X3D, like 'SFString' or 'MFInt32'. As for VRML/X3D interface declaration statements. In base TX3DField class, this returns XFAny (name indicating any type, used by instantreality and us).

Public class function TypeName: String; deprecated 'use X3DType';

Warning: this symbol is deprecated: use X3DType

This item has no description.

Public class function CreateEvent(const AParentNode: TX3DFileItem; const AName: String; const AInEvent: boolean): TX3DEvent; virtual;

Create TX3DEvent descendant suitable as exposed event for this field.

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

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

Public procedure UnassignDefaultValue; virtual;

Remove default value, recording that "no default is known". In effect EqualsDefaultValue will always return False.

Public 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 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 EListsDifferentCount will be raised.

Exceptions raised
EListsDifferentCount
When field is multiple-value field and Value1.Count <> Value2.Count.
Public function CanAssignLerp: boolean; virtual;

Is AssignLerp usable on this field type?

Descendants implementors notes: In this class, this always returns False.

Public procedure AddAlternativeName(const AlternativeName: String; const X3DMajorVersion: Integer); override;

This item has no description. Showing description inherited from TX3DFieldOrEvent.AddAlternativeName.

Add alternative name for the same field/event, to be used in different VRML version.

When VRML major version is exactly equal X3DMajorVersion, the AlternativeName should be used — for both reading and writing of this field/event. In some cases, when reading, we may also allow all versions (both original and alternative), but this is mostly for implementation simplicity — don't count on it.

A special value 0 for X3DMajorVersion means that this is just an alternative name, that should be allowed when reading (as alternative to normal Name), and never used when writing.

Alternative names is a very handy mechanism for cases when the only thing that changed between VRML versions is the field name. Example: Switch node's children/choice, LOD node's children/level, Polyline2D lineSegments/point.

Note that this also works for ExposedEvents with exposed TX3DField: if a field has alternative names, then it's exposed events always also have appropriate alternative names.

Public procedure Changed;

Notify ParentNode.Scene that the value of this field changed.

Public function ExecuteChange: TX3DChange; virtual;

What happens when the value of this field changes. This is called, exactly once, by TCastleSceneCore.InternalChangedField 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 by EventOut.AddNotification, with two additional benefits:

  1. This method may be not called (although no guarantees) when the actual field value did not change. In contrast, the event notification is always fired, even when you send the same value to an exposed field, because VRML/X3D events and routes must be fired anyway.

  2. 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 notification by EventOut.AddNotification.

Public procedure Send(Value: TX3DField); overload;

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

Public procedure AddNotification(const Notification: TX3DEventReceive);

Notifications when exposed field received new value through VRML/X3D event. Use only for exposed fields. This is simply a shortcut for EventOut.AddNotification, EventOut.RemoveNotification, see TX3DEvent.AddNotification 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.InternalChangedField 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.ChangeAlways cause appropriate action on this change.

Public procedure RemoveNotification(const Notification: TX3DEventReceive);

This item has no description.

Properties

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

Public property Exposed: boolean read FExposed write SetExposed default false;

Does this field generate/accept events, that is an "exposedField" (in VRML 2.0) or "inputOutput" (in X3D).

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

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

Public property ChangeAlways: TX3DChange read FChangeAlways write FChangeAlways default chNone;

What always happens when the value of this field changes.

This is included in the ExecuteChange method result. So instead of using this property, you could always override ExecuteChange method. But often it's easier to use the property.

By default this is chNone. See TX3DChange for possible values.


Generated by PasDoc 0.16.0-snapshot.