Class TX3DEvent

Unit

Declaration

type TX3DEvent = class(TX3DFieldOrEvent)

Description

X3D event.

Hierarchy

Overview

Methods

Public constructor Create(AParentNode: TX3DFileItem; const AName: string; const AFieldClass: TX3DFieldClass; const AInEvent: boolean);
Public destructor Destroy; override;
Public procedure Parse(Lexer: TX3DLexer);
Public procedure SaveToStream(Writer: TX3DWriter); override;
Public function SaveToXml: TSaveToXmlMethod; override;
Public procedure Send(Field: TX3DField; const Time: TX3DTime); overload;
Public procedure Send(Field: TX3DField); overload;
Public procedure AddNotification(const Notification: TX3DEventReceive);
Public procedure RemoveNotification(const Notification: TX3DEventReceive);
Public function SendNeeded: boolean;
Public procedure Assign(Source: TPersistent); override;

Properties

Public property FieldClass: TX3DFieldClass read FFieldClass;
Public property InEvent: boolean read FInEvent;
Public property ParentExposedField: TX3DField read FParentExposedField write FParentExposedField;

Description

Methods

Public constructor Create(AParentNode: TX3DFileItem; const AName: string; const AFieldClass: TX3DFieldClass; const AInEvent: boolean);
 
Public destructor Destroy; override;
 
Public procedure Parse(Lexer: TX3DLexer);

This only reads (optional) "IS" clause of the event, as may occur in VRML nodeBodyStatement.

Public procedure SaveToStream(Writer: TX3DWriter); override;
 
Public function SaveToXml: TSaveToXmlMethod; override;
 
Public procedure Send(Field: TX3DField; const Time: TX3DTime); overload;

Send a value to event. For input fields, this is used by routes, scripts etc. to send an event to a field. For output fields, this is used by node itself to send event to routes, scripts etc.

Field must be non-nil, of class FieldClass.

The Field instance doesn't become owned in any way by the TX3DEvent. That is, it's the caller responsibility to free the Field instance at any comfortable time, possibly right after calling Send.

Overloaded versions without explicit Time parameter just take time from ParentNode.Scene.GetTime. If ParentNode is Nil (which should not happen with normal fields within nodes) or if ParentNode.Scene is Nil (which may happen only if events processing is not turned on, that is TCastleSceneCore.ProcessEvents is False) then event is not send.

Public procedure Send(Field: TX3DField); overload;
 
Public procedure AddNotification(const Notification: TX3DEventReceive);

Add notification about receiving new value. For input events, these are used by node itself to listen to events send to it. For output events, these are used by routes, scripts to listen to events occuring.

When you handle this callback to send another X3D event, you should pass around the same Time value. This makes sure that X3D route loop detection mechanism works fine. For example, here's how handling TimeSensor.elapsedTime_receive event sends fraction_changed event:

procedure TTimeSensorNode.EventElapsedTimeReceive(
  const Event: TX3DEvent; const Value: TX3DField; const Time: TX3DTime);
var
  Fraction: Single;
begin
  if FdEnabled.Value then
  begin
    Fraction := ...; // doesn't matter here how this is calculated
    // Pass "Time" parameter further by a call below
    Eventfraction_changed.Send(Fraction, Time);
  end;
end;

All callbacks registered here are simply called by Send method.

Public procedure RemoveNotification(const Notification: TX3DEventReceive);

Remove notification (previously added by AddNotification) about receiving new value.

This is guaranteed to work correctly even if we're right now in the middle of this event's processing (which means that we may be iterating over a list of notifications). The handler may be actually removed a bit later (when it's safe).

Note that adding a notification two-times makes it called two times. Removing a notification removes one copy of a notification, so it should then be removed two-times too.

Public function SendNeeded: boolean;

Is anything actually listening on this events Send?

Sometimes, even preparing a value to Send is quite time-consuming (example: CoordinateInterpolator, where a long MFVec3f value has to be computer). Then checking SendNeeded is useful: if SendNeeded = False, you know that there's no point in preparing Value to send, because actually Send will do nothing.

For example, event out to which no ROUTE is connected, and no Script can listen to it.

For now, this simply returns whether any callback is registered by AddNotification.

Public procedure Assign(Source: TPersistent); override;

Assign from another event. The FieldClass and InEvent is copied.

The notifications (from AddNotification) and ParentExposedField are not copied, since they shouldn't be copied so easily (ParentExposedField is related to hierarchy of containers, copying notification would be surprising to the notification listener).

Properties

Public property FieldClass: TX3DFieldClass read FFieldClass;
 
Public property InEvent: boolean read FInEvent;

Is it "in" or "out" event ?

Public property ParentExposedField: TX3DField read FParentExposedField write FParentExposedField;

If this event is an exposed event belonging to some field, this references parent field. Otherwise it's Nil.


Generated by PasDoc 0.16.0.