Observers

These functions allow callbacks to be performed in response to nodes being updated. The defined callbacks will take place following the execution of the script, or during a vrYield.

Functions

Type	Name
void	vrAddEventObserver(string uniqueID, string eventType, vrnode node, Any callback) Adds an observer and callback function to execute for events (e.g. 'Activate', 'Touch', 'Break', 'Click', 'DoubleClick', etc.)
void	vrAddGlobalEventObserver(string uniqueID, string eventType, Any callback) Adds an observer and callback function to execute for global events (e.g. 'KeyPress', 'KeyRelease', 'PoseEntered', 'PoseLeft', etc.)
void	vrAddMetaNodeObserver(string uniqueID, string metaNode, table callbacks) Adds an observer of events from a MetaNode. This notifies the script whenever a node of type metaNode is created.
void	vrAddNodeObserver(string uniqueID, node node, table callbacks) Adds an observer of events from a node. This notifies the script in certain circumstances - see the callbacks parameter.
void	vrAddPropertyObserver(string key, Any valueChangedCallback, string metaName, string propNames, vrnode user =nil) Adds an observer of one or more properties of a metanode. The callback function will be executed once per update whenever the value of a specified property is changed.
void	vrAddSettingObserver(string key, Any callback, string settingPath, vrnode user =nil) Adds an observer of a setting. This notifies the script whenever the setting changes.
void	vrAddTransformNodeObserver(string uniqueID, Any transformCallback, Any enabledCallback, vrnode node, vrnode user =nil) Add an observer to the SGNode of a vrtree node.
void	vrRemoveObserver(string uniqueID) Removes an observer.

Functions Documentation

vrAddEventObserver

void vrAddEventObserver(
    string uniqueID,
    string eventType,
    vrnode node,
    Any callback
)

Adds an observer and callback function to execute for events (e.g. 'Activate', 'Touch', 'Break', 'Click', 'DoubleClick', etc.)

Parameters:

• uniqueID A unique ID for use in vrRemoveObserver
• eventType The type of event to observe, such as 'Activate' or 'Touch'
• node The node to observe for new events
• callback A Lua function to call when events are activated. This function should have a signature of function(). It can be a string name of a global function or a Lua function object

vrAddGlobalEventObserver

void vrAddGlobalEventObserver(
    string uniqueID,
    string eventType,
    Any callback
)

Adds an observer and callback function to execute for global events (e.g. 'KeyPress', 'KeyRelease', 'PoseEntered', 'PoseLeft', etc.)

Parameters:

• uniqueID A unique ID for use in vrRemoveObserver
• eventType The type of global event to observe, such as 'KeyPress' or 'PoseEntered'
• callback A Lua function to call when global events are activated. This function should have a signature of function(). It can be a string name of a global function or a Lua function object

vrAddMetaNodeObserver

void vrAddMetaNodeObserver(
    string uniqueID,
    string metaNode,
    table callbacks
)

Adds an observer of events from a MetaNode. This notifies the script whenever a node of type metaNode is created.

Parameters:

• uniqueID A unique ID for this observer. Use this with vrRemoveObserver.
• metaNode The type of node to observe.
• callbacks Table of callbacks. Each value can be a string name of a global function or a lua function object. Possible keys are:
  • nodeCreated - called when a node is created. This function should have a signature of function(meta, newnode).
  • nodeRenamed - called when a node's name is changed. This function should have a signature of function(meta, node).
  • nodeParentChanged - called when a node's parent is changed. This function should have a signature of function(meta, node, oldParent, newParent).
  • nodeAddingToRecycleBin - called when a node is added to the recycle bin. This function should have a signature of function(meta, node).
  • nodeRestoredFromRecycleBin - called when a node is restored from the recycle bin, e.g. with an undo command. This function should have a signature of function(meta, node).
  • nodeDestroying - called when a node is finally deleted, usually when closing the scene. You are more likely to want nodeAddingToRecycleBin. This function should have a signature of function(meta, node).
  • nodeChildAdded - called when a new child was added to a node. This function should have a signature of function(meta, parent, child).
  • nodeChildRemoved - called when a child was unlinked from a node. This function should have a signature of function(meta, parent, child).
  • nodePathChanged - called when the node or one of its ancestors has been re-parented. This function should have a signature of function(meta, node).
  • nodeLinkAdded - called when a property link was set between nodes. This function should have a signature of function(meta, from, to).
  • nodeLinkRemoved - called when a property link between nodes was removed. This function should have a signature of function(meta, from, to).
  • nodeCloned - called when a node was cloned. This function should have a signature of function(meta, orig, clone).

Example:

Script

local callbackMap = {
  nodeCreated = function(meta, node)
    print(node:getName() .. " created")
  end,

  nodeRenamed = function(meta, node)
    print(node:getName() .. " renamed")
  end,

  nodeParentChanged = function(meta, node, old, new)
    if(old and new) then
      print(node:getName() .. " moved from " .. old:getName() .. " to " .. new:getName()) 
    end
  end,
  
  nodeAddingToRecycleBin = function(meta, node)
    print(node:getName() .. " removed")
  end
}

vrAddMetaNodeObserver(
  "nodeObserver",
  "Assembly",
  callbackMap
)

local myNode = vrCreateNode("Assembly", "ObservedNode", vrScenesNode())

myNode:setParent(vrLibrariesNode())
vrYield(0)

myNode:setName("NamedNode")
vrYield(0)

vrDeleteNode(myNode)
vrYield(0)

vrRemoveObserver("nodeObserver")

Output

Running...
ObservedNode created
ObservedNode moved from Scenes to Libraries
NamedNode renamed
NamedNode removed
NamedNode moved from Libraries to RecycleBin
Ended.

vrAddNodeObserver

void vrAddNodeObserver(
    string uniqueID,
    node node,
    table callbacks
)

Adds an observer of events from a node. This notifies the script in certain circumstances - see the callbacks parameter.

Parameters:

• uniqueID A unique ID for this observer. Use this with vrRemoveObserver.
• node The node to observe.
• callbacks table Table of callbacks. Each value can be a string name of a global function, or a lua function object. Possible keys are:
  • valuesChanged - called when any of the node values change and should have a signature of function(node).
  • addingToRecycleBin - called when the node is sent to the recycle bin and should have a signature of function(node).
  • restoredFromRecycleBin - called when the node is restored from the recycle bin, e.g. with an undo command and should have a signature of function(node).
  • destroying - called when the node is finally deleted, usually when closing the scene and should have a signature of function(node). You are more likely to want addingToRecycleBin.
  • addChild - called when a new child was added to a node and should have a signature of function(parent, child).
  • removeChild - called when a child was unlinked from a node and should have a signature of function(parent, child).
  • parentChanged - called when a node's parent was changed and should have a signature of function(npde,newParent, oldParent).
  • pathChanged - called when a node or one of its ancestors has been re-parented and should have a signature of function(node).
  • renameNode - called when a node has just been renamed and should have a signature of function(node).
  • addLink - called when a property link was set between nodes and should have a signature of function(toNode, fromNode).
  • removeLink - called when a property link between nodes was removed and should have a signature of function(toNode, fromNode).
  • cloned - called when a node has been cloned and should have a signature of function(orig, cloned).

Example:

Script

local myNode = vrCreateNode("Assembly", "ObservedNode", vrScenesNode())
vrYield(0)

local callbackMap = {
  valuesChanged = function(node)
    print(node:getName() .. " enabled: " .. tostring(node.Enabled))
  end,

  addingToRecycleBin = function(node)
    print(node:getName() .. " removed")
  end
}

vrAddNodeObserver(
  "nodeObserver",
  myNode,
  callbackMap
)

myNode.Enabled = false
vrYield(0)

myNode.Enabled = true
vrYield(0)

vrDeleteNode(myNode)
vrYield(0)

vrRemoveObserver("nodeObserver")

Output

Running...
ObservedNode enabled: false
ObservedNode enabled: true
ObservedNode removed
Ended.

vrAddPropertyObserver

void vrAddPropertyObserver(
    string key,
    Any valueChangedCallback,
    string metaName,
    string propNames,
    vrnode user =nil
)

Adds an observer of one or more properties of a metanode. The callback function will be executed once per update whenever the value of a specified property is changed.

Parameters:

• key A unique key for this observer. This can be passed to the vrRemoveObserver function to remove this observer
• valueChangedCallback A Lua function to execute whenever a specified property is changed. This function should have a signature like "function(node, value1, ...)" - i.e. with a value argument for each observed property. It can be a string name of a global function or a Lua function object
• metaName The name of the metanode to observe for property changes (i.e. "Assembly")
• propNames A comma-separated list of properties to observe (e.g. "Enabled" or "Enabled,Transform")
• user The user associated with this observer (optional - defaults to current user)

Example:

Script

local myNode = vrCreateNode("Assembly", "ObservedNode", vrScenesNode())
vrYield(0)

local myCallback = function(node, value)
  print(node:getName() .. " enabled: " .. tostring(value))
end

vrAddPropertyObserver(
  "enabledObserver",
  myCallback,
  "Assembly",
  "Enabled"
)

myNode.Enabled = false
vrYield(0)

myNode.Enabled = true
vrYield(0)

vrRemoveObserver("enabledObserver")
vrDeleteNode(myNode)

Output

Running...
ObservedNode enabled: false
ObservedNode enabled: true
Ended.

vrAddSettingObserver

void vrAddSettingObserver(
    string key,
    Any callback,
    string settingPath,
    vrnode user =nil
)

Adds an observer of a setting. This notifies the script whenever the setting changes.

Parameters:

• key A unique key for this observer. Use this with vrRemoveObserver
• callback Lua function to call when a node is created. This function should have a signature of function(value). This can be a string name of a global function, or a Lua function object
• settingPath Path to the setting to observe (relative to the registry root)
• user The user that this observer belongs to (defaults to the current user)

Example:

This function makes use of the capability of passing local Lua functions into the API to be called later. The following line of code provides a simple function to print the value of a setting whenever it changes. Whenever the Clip Planes setting in the Renderer/Scene category is changed (e.g. by the user interface), the script will print the new value of the setting.

Script

vrAddSettingObserver("clipobs", function(value) print(value) end, "Renderer/Scene/ClipRange")

Output

Running...
0.310, 500.000
0.320, 500.000
0.330, 500.000
0.320, 500.000
0.310, 500.000
0.300, 500.000
Ended.

This doesn’t have to be an anonymous function, either, it can be a separate function defined locally or globally, and can also accept a string as the name of a global function.

local function printer(value) 
  print(value) 
end

vrAddSettingObserver("clipobs", printer, "Renderer/Scene/ClipRange")

vrAddTransformNodeObserver

void vrAddTransformNodeObserver(
    string uniqueID,
    Any transformCallback,
    Any enabledCallback,
    vrnode node,
    vrnode user =nil
)

Add an observer to the SGNode of a vrtree node.

Parameters:

• uniqueID A unique ID for this observer. Use this with vrRemoveObserver.
• transformCallback Lua function to call when the nodes transform changes. This function should have a signature of function(node, transform). This can be a string name of a global function, or a lua function object
• enabledCallback Lua function to call when the nodes enabled state changes. This function should have a signature of function(node, enabled). This can be a string name of a global function, or a lua function object
• node The node to observe.
• user THe user associated with this observer.

Example:

Script

local myNode = vrCreateNode("Assembly", "ObservedNode", vrScenesNode())
vrYield(0)

local myTransformCallback = function(node, value)
  print(node:getName() .. " transformed:")
  print(tostring(value))
end

local myEnabledCallback = function(node, value)
  print(node:getName() .. " enabled: " .. tostring(value))
end

vrAddTransformNodeObserver(
  "transformObserver",
  myTransformCallback,
  myEnabledCallback,
  myNode
)

myNode.Enabled = false
vrYield(0)

myNode.Enabled = true
vrYield(0)

local transform = myNode.Transform
transform.position.x = transform.position.x + 1.0
vrYield(0)

vrRemoveObserver("transformObserver")

vrDeleteNode(myNode)
vrYield(0)

Output

Running...
ObservedNode enabled: false
ObservedNode enabled: true
ObservedNode transformed:
1 0 0 0
0 1 0 0
0 0 1 0
1 0 0 1
Ended.

vrRemoveObserver

void vrRemoveObserver(
    string uniqueID
)

Removes an observer.

Parameters:

• uniqueID The unique ID specified when adding the observer.