Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Next »

Available since firmware version 7.0

The ifSGNodeField interface allows you to query, and get, set, and perform other similar manipulation operations on Scene Graph node fields. The ifSGNodeField interface also allows you to set and unset event observers on a subject node field.

Implemented By

Supported Methods

Description of Methods 


hasField(name as String) as Boolean

Returns true if the subject node has a field whose name exactly matches name, or whose fully lowercase analog is identical to that of name. Returns false otherwise.


getField(name as String) as Object

Returns the appropriately-typed value from the subject node field identified by name.

You can also use the node.field syntax to get the same result as getField(). That is, rectpos = rect.getField("translation") is equivalent to rectpos = rect.translation. You can also use the syntax node[field].


getFields() as Object

Returns an associative array with all of the node field names as associative array element keys, and corresponding field values as corresponding associative array element values.


addField(field as String, type as String, alwayNotify as Boolean)

Adds the field name specified by field, with the type specified by type, to the subject node. The added field is initialized to the default value for the type. The third argument, alwaysNotify, specifies whether observers of the field are triggered only when the field value changes (alwaysNotify set to false), or whenever the field value is set, whether to the same or a new value (alwaysNotify set to true).


addFields(aa as Object)

Adds the field(s) and corresponding field value(s) defined as key-value pair(s) in the associative array aa to the subject node. The types of the added fields are determined by the values which correspond to the allowable types for an <interface> field.


getFieldType(field_name as String) as String

Returns a string that is the type of the field specified by field_name for the subject node.


getFieldTypes() as Object

Returns an associative array for the subject node containing all the field names as the array keys, and corresponding field types as the array values.


setField(name as String, value as Object)

Sets the value of the subject node field identified by name to value. This will fail and stop script execution if the value is not of the appropriate type.

You can also use the node.field syntax to get the same result as setField(). That is, rect.setField("opacity", 0.5) is equivalent to rect.opacity = 0.5.


setFields(aa as Object)

Sets the value of subject node fields indicated by the corresponding key.


queueFields(queue_node as Boolean) as Boolean

If queue_node is set to true, subsequent operations on the node fields will queue on the node itself rather than on the Scene node render thread. This prevents the operations from being executed immediately. Subsequently setting queue_node to false will then cause all of the operations to be transferred to the Scene node render thread queue to be immediately executed in a single render cycle. This can be helpful when multiple fields of a node that affect the appearance of the user interface need to be changed at one time from another thread. It should not be used on a node that is not owned by the render thread, as the render thread will not be able to execute the operations when they are released to it. You can use it when a node owned by a Task node thread is transferred to the render thread, by setting it to a child or a node field of a node already owned by the render thread, where the queue is then released.


observeField(fieldName as String, function as String)

fieldNameThe subject node field to observe
function The function to call when the field value changes

observeField(fieldName as String, port as Object)

fieldNameThe subject node field to observe 
 portroMessagePort object to pass an roSGNodeEvent message when the field value changes

The observeField() method is overloaded: the first form calls a function when the subject node field value changes; the second form passes an roSGNodeEvent message to an roMessagePort object.

First Form

For this form, you can pass a roSGNodeEvent message as an argument to the callback function. In the callback function you can get the node ID, the field name, and the field value at the time it was set, from the roSGNodeEvent message, using the same functions described in the second form. The roSGNodeEvent message also includes a pointer to the node that can be accessed using getRoSGNode(), to associate nodes without an ID in the callback function. Even more information can be accessed in the callback function by storing the information in a custom field of the node. This version of the observeField() method will either pass the roSGNodeEvent message or not, depending on the whether the argument is specified in the callback function. 

Second Form

Available since firmware version 7.1

This form sends an roSGNodeEvent message to the roMessagePort identified by port when the subject node field identified by fieldName changes value. Running the GetNode() function on the message will retrieve the ID of the node that changed, running the GetField() function on the message will get the name of the field that changed, and running the GetData() function on the message will get the new field value at the time of the change. This allows other threads to react to field changes, and avoids missing a value when the field changes twice before the message handler is able to receive the roSGNodeEvent messages.


unobserveField(name as String)

Removes the previously established connections between the subject node field identified by name and any callback functions or message ports.


  • No labels