Event utilities component - extensions

Contents:

1. Boolean value toggler (Toggler node)

Toggler (API reference) is simple event utility for setting/observing a boolean value in various ways. Something like a standard X3D BooleanToggle on steroids.

Toggler  : X3DChildNode {
  SFNode     [in,out]      metadata    NULL        # [X3DMetadataObject]
  SFBool     [in,out]      status      FALSE     
  SFBool     [in,out]      notStatus   TRUE      
  XFAny      [in]          toggle                  # the type/value send here is ignored
  XFAny      [in]          set                     # the type/value send here is ignored
  XFAny      [in]          reset                   # the type/value send here is ignored
  SFBool     [out]         changed                 # always sends TRUE
  SFBool     [out]         on                      # always sends TRUE
  SFBool     [out]         off                     # always sends TRUE
  SFBool     [in,out]      enabled     TRUE      
}

"status" is the boolean value stored. "notStatus" is always the negated value of "status". You can set either of them (by sending "set_status" or "set_notStatus"). Changing any of them causes both output events to be send. That is, "status_changed" receives the new boolean value stored, "notStatus_changed" received the negation of the new value stored.

The input events "toggle", "set" and "reset" provide altenative ways to change the stored boolean value. They accept any VRML/X3D type/value as input (this is called XFAny by InstantPlayer), and the value send is actually completely ignored. "toggle" always toggles (negates) the stored value, "set" changes the stored value to TRUE, "reset" changes the stored value to FALSE.

The output events "changed", "on", "off" provide altenative ways to observe the stored boolean value. They always generate a boolean TRUE value when specific thing happens. "changed" event is generated when the value changes, "on" event is generated when the value changes to TRUE, "off" event is generated when the value changes to FALSE.

"enabled" allows to disable input/output events handling. When enabled = FALSE then sending input events to above fields has no effect (stored boolean value doesn't change), and no output events are generated.

Compatible with InstantReality Toggler node.

2. Force sequencer continuous output (X3DSequencerNode.forceContinuousValue_Changed)

X3DSequencerNode {
  ...
  SFBool     [in,out]      forceContinuousValue_Changed  FALSE     
}

By default (when this field is FALSE) the behavior of sequencer nodes follows the X3D spec: The sequencer node sends only one value_changed output event per key[i] interval.

When forceContinuousValue_Changed is TRUE then on every action possibly changing the continuous key, we output value_changed. In particular, this means that every set_fraction will cause appropriate "value_changed", even if previous set_fraction already generated the same "value_changed". This is consistent with float interpolator nodes, and it is very useful sometimes: when multiple IntegerSequencer nodes may affect the same Switch.whichChoice (but only one IntegerSequencer is active at a time, i.e. only one TimeSensor actually uses some IntegerSequencer), you want to be sure to send IntegerSequencer.value_changed continuously.

3. Trigger multiple outputs of any type when some input is received (ValueTrigger)

ValueTrigger : X3DTriggerNode {
  ...
  SFBool     [in,out]      enabled     TRUE      
  SFBool     [in]          trigger               
  ... additional custom fields ...
}

The way to specify additional custom fields is the same as for standard Script or ComposedShader nodes.

When the input trigger receives a value TRUE, and enabled is TRUE, this node generates output using all custom fields.

An example usage (in X3D classic encoding):

DEF MyValueTrigger ValueTrigger {
  inputOutput SFVec3f myBboxCenter 1  2  3
  inputOutput SFVec3f myBboxSize   10 20 30
}
 
# When a MyTimeSensor becomes active (when the animation starts)....
ROUTE MyTimeSensor.isActive TO MyValueTrigger.trigger
 
# ...set the MyShape bounding box to predefined values
ROUTE MyValueTrigger.myBboxCenter TO MyShape.bboxCenter
ROUTE MyValueTrigger.myBboxSize   TO MyShape.bboxSize

This extension is mostly compatible with InstantReality node of the same name, but we allow only SFBool for trigger.