Navigating from a Wire to a Node Using VI Scripting

You navigate from a wire to a node any time that you use a wire reference to obtain a reference to a node that it connects to. Navigating from a wire to a connected node is a navigation subtask that you can combine with other navigation subtasks to accomplish larger navigation goals. Refer to navigation overview to learn more about how navigating from a wire to a node interacts with other navigation tasks.

What to Use

What to Do

Before you start: Open the Navigating Nodes and Wires VI in the labview\examples\Application Control\VI Scripting\Finding and Modifying Objects directory for an example that illustrates each step of the following procedure. Note that this example also illustrates the procedure for navigating from a node to a wire.

Expand the procedure for more information about this specific example.

When navigating from a wire to a node, you most commonly obtain the wire reference as the result of previous navigation.

Example Details

In the example, the scripting VI obtains the initial wire reference by navigating from the One Button Dialog function to the wire connected to the button name input of that function.

Use the Wire:Terminals[] property of the wire to obtain references to the terminals of the wire.

Identify which terminal or terminals of the wire best further your navigation goals.

In some navigation tasks, you might be interested in only one terminal of the wire. In other navigation tasks, you might be interested in inspecting or navigating across all the terminals of the wire.

Example Details

In the example, the scripting VI requires only the source terminal of the wire.

Use the Index Array function with the Terminals[] array from step 2 to obtain a reference to the desired terminal.

The first element in the Terminals[] array is always a reference to the source terminal of the wire. If the wire connects only two terminals, the second element in the array is a reference to the sink terminal of the wire. If the wire has multiple sink terminals, the array stores them in random order beginning at index 1 of the array.

When a wire has multiple sink terminals, you can use a For Loop to iterate across each terminal reference in the array. Repeat step 5 for each terminal reference.

Example Details

In the example, the scripting VI requires a reference only to the source terminal of the wire. Because the source terminal is always stored at the beginning of the Terminals[] array of a wire, the scripting VI uses the Index Array function to obtain a reference to the terminal at index 0 of the Terminals[] array.

Use the Terminal:Owner property of the returned terminal reference to obtain a reference to the connected node.

(Optional) Use the To More Specific Class function to cast the returned reference to its actual class. This step provides the following benefits:

Identifies class—The To More Specific Class function casts the referenced object to a more specific class only if the object is a member of that class. Therefore, you can use the To More Specific Class function to check the class of the reference. This check is necessary when you want to interact with the referenced object only if it is a member of a certain class.

Enables access to more properties and methods—When you cast the reference to a more specific class, you can use more specific properties and methods of the reference. The Terminal:Owner property in the previous step always returns a GObject reference, a class which supports only a limited set of properties and methods.

Example Details

In the example, the scripting VI can modify the returned node only if it is a string constant. Thus, the scripting VI tries to cast the reference to a string constant. The Case structure determines whether the To More Specific Class function returns an error and therefore whether the referenced object is a string constant.

Use the node reference to either edit the node or to continue navigating.

Example Details

In the example, the scripting VI edits the node rather than using it to continue navigating. The scripting VI sets the value of the node, a string constant, to Okay! by using the StringConstant:Value property.

Use the Close Reference function to close the wire reference, the terminal reference, and the node reference when you are finished using them.

Caveats and Recommendations

Downcast the reference returned by the Terminal:Owner property—The Terminal:Owner property always returns a reference to a Generic object. However, if you know that the terminal connects the wire to a more specific class of object, you can use the To More Specific Class function to downcast the returned reference to the more specific class. When you downcast a reference to a more specific class, you are able to call more specific properties or methods on the reference.

Close all references that you open—An excessive number of open references negatively impacts the performance of a VI. Read about closing VI and object references for more performance details.

Additional Examples

Refer to the Navigation Overview VI in the labview\examples\VIScripting\Application Control\VI Scripting\Finding and Modifying Objects directory for a complete navigation example that includes navigating from a node to a wire.