ifSGNodeDict

The ifSGNodeDict interface allows you access information about the nodes in a SceneGraph node tree, and find and return a node with a specific ID.

Implemented by

Supported methods

findNode(name as String) as Object

Description

Returns the node that is a descendant of the nearest component ancestor of the subject node (possibly the subject node itself) and whose id field is set to name. The search for the descendant node is a breadth-first search that includes child nodes in nodes that are declared as custom components defined in other XML component files. These together allow finding siblings and cousins of a node within the context of a component. If a node with the specified name is not found, an invalid object is returned

Parameters

Return Value

The node that is a descendant of the nearest component ancestor of the subject node.

subtype() as String

Description

Returns the subtype of the subject node as specified when it was created.

Return Value

The subtype of the subject node.

parentSubtype(nodeType as String) as String

Description

Returns the subtype of the parent of the nodeType in the SceneGraph node class hierarchy.

This method does not actually reference the subject node.

Parameters

Return Value

The subtype of the parent node.

isSubtype(nodeType as String) as Boolean

Description

Checks whether the subtype of the subject node is a descendant of the subtype nodeType in the SceneGraph node class hierarchy.

Parameters

Return Value

A flag indicating whether the subtype of the subject node is a descendant of the subtype nodeType.

isSameNode(RoSGNode as Object) as Boolean

Description

Checks whether a specific roSGNode refers to the same SceneGraph node object as the subject node.

This can be useful when the RoSGNode objects come from two different sources, for example when one is stored in an associative array, and the other is obtained from an RoSGNode interface method that returns an RoSGNode object, like getChild(). It may be that the application needs to know whether the two RoSGNode objects are actually referring to the same underlying SceneGraph node.

Return Value

A flag indicating whether the nodes refer to the same SceneGraph node object.

Example:

The following example should print "same":

n = createObject("roSGNode", "Node")
c = n.createChild("Node")
if c.isSameNode(n.getChild(0)) then print "same"

clone(isDeepCopy as Boolean) as Object

Returns a copy of the entire node tree or just a shallow copy.

Return Value

A node tree.

callFunc(funcName as String, ...) as Dynamic

callFunc() is a synchronized interface on roSGNode. It always executes in the component's owning ScriptEngine and thread (by rendezvous if necessary), and it will always use the m and m.top of the owning component. Any context from the caller can be passed via one or more method parameters, which may be of any type (previously, callFunc() only supported a single associative array parameter).

To call the function, use the callFunc field with the required method signature. A return value, if any, can be an object that is similarly arbitrary. The method being called must determine how to interpret the parameters included in the callFunc field.

Functional field declaration

<interface>
    <function name="addSomeValue" />
</interface>

Function definition

function addSomeValue(params as Object) as Object
    passedDataLabel = m.top.findNode("passedDataLabel")
    passedDataLabel.text = params.passedString
    result = {
        resultString : "Returned Value " + stri(params.passedInt + 4)
    }

    return result
end function

callFunc with parameters

params = {passedString:"", passedInt:12}
result = node.callFunc("addSomeValue", params)

hasFunc(callableFunc as String) as Boolean

Checks whether the specified callable function exists.

Return Value

A flag indicating whether the specified callable function exists.

threadinfo() as Object

Description

A runtime debugging method for helping minimize Rendezvous spread. This method can be called on any node from any thread.

The following example shows the associative array returned by this method, formatted as JSON. All values are strings.

{
  "currentThread": {
    "id": "02A3C1",
    "name": "MyTask",
    "type": "Task"
  },
  "node": {
    "id": "myNode",
    "owningThread": {
      "id": "01581F",
      "name": "MainScene",
      "type": "Render"
    },
    "type": "MyComponent",
    "willRendezvousFromCurrentThread": "Yes"
  },
  "renderThread": {
    "id": "01581F",
    "type": "Render"
  }
}

Do not call this method from within function main() or any function called by function main()

Return Value

An roAssociativeArray with the following information:

• What is calling a thread function is being called from.
• On which component's behalf (what m.top) the current function is executing.
• The thread ownership of the node in question.
• Whether or not access to the node from the current thread would cause a rendezvous.

signalBeacon(beacon As String) As Integer

Description

Signals start and/or stop points for measuring app launch and Electronic Program Grid (EPG) launch times.

To pass certification, an app must finish launching within the time specified in the certification performance requirements. The Roku OS automatically fires an AppLaunchInitiate event to mark when the user presses the OK button to launch an app from the Roku home screen. The app, however, must fire the corresponding AppLaunchComplete to mark when the app home page is fully rendered or when video playback starts after handling a deep link and the app can respond to commands sent via the remote control.

Starting in Roku OS 9.3, if the app UI displays a login or user selection dialog before the home page, the app can fire AppDialogInitiate and AppDialogComplete beacons when the dialog loads and exits, respectively. These new beacons enable more accurate measurements of app launch times as the time spent on any dialogs requiring user input prior to rendering the home page are subtracted from the overall app launch time. If the app displays more that one dialog before the home page, multiple pairs of AppDialogInitiate/AppDialogComplete beacons may be fired. Do not fire AppDialog beacons on message dialogs that do not involve any user interaction (for example, a "please wait" or "loading" dialog).

To fire signal beacons within your application, call the signalBeacon() function on any node as demonstrated in the following examples:

myScene.signalBeacon("AppLaunchComplete")
myEPGComponent.signalBeacon("EPGLaunchInitiate")
m.top.signalBeacon("EPGLaunchComplete")

Only the first sequence of EPG launch beacons is recorded. If a user launches the EPG more than once while the app is running, a warning message is output to the debug console. This warning message, which acknowledges the receipt of the beacon while notifying that subsequent ones will not be recorded, may be ignored.

Only EPG launch sequences that start within 5 seconds of the AppLaunchComplete event being fired qualify as a valid measurements for certification. EPG launch sequences fired after the 5-second window are still recorded so that app performance can be compared against requirements.

The following table summarizes when to fire the AppLaunchComplete, AppDialogInitiate/AppDialogComplete, and EPGLauchInitiate/EPGLauchComplete beacons and when their timestamps are recorded:

Return Value

When you fire a launch event, the system will return an integer indicating the result of its signaling:

In addition to the app launch, dialog launch, and EPG launch times, the Roku OS automatically measures five other certification performance metrics: app compile time, video start time, live start time, channel change time, and channel exit time. You can use the BrightScript console (port 8085) to view a report detailing your app's performance. See Measuring app performance for more information.