Obtaining References to Objects in an Unknown Target VI Using VI Scripting

Requires: VI Scripting

You can use VI Scripting to inspect or modify target VIs whose contents are not known until run time. As in any VI Scripting application, you must obtain references to the objects that you want to manipulate in the target VI. However, because you do not know the contents of the target VI until run time, you cannot use the Open VI Object Reference function to locate the objects by their label. Instead, you can use the Traverse for GObjects VI to identify groups of objects that are members of the same class. Then, you can iterate through the returned array of objects to determine which objects you want to manipulate.

What to Use

This VI Scripting task requires the following objects:

Traverse for GObjects		To More Specific Class		Close Reference
Add  Find		Add  Find		Add  Find

What to Do

Before you start: Open the Obtaining Unknown Object References 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.

Expand the procedure for more information about this specific example.

1. Obtain a reference to the target VI that contains the objects you want to inspect or edit.

   Example Details

   In the example, the Open VI Reference function provides a reference to the VI specified by the Path to target VI control. This implementation enables the user to apply the scripting VI to any target VI just by specifying a different VI path. Furthermore, the scripting VI can be converted to a subVI if the user wants to programmatically apply it to a set of VIs.

2. Determine the class and location of the objects whose references you want to obtain.
   1. Containing VI—Wire this reference to the VI Refnum input of the Traverse for GObjects VI.
   2. Location within VI—Within the target VI, objects can be located on a front panel, on a block diagram, in a cluster, or on the diagram of a structure such as a For Loop or Case structure. You must specify which of these locations you want the Traverse for GObjects VI to search by creating a constant from the Traverse Target input.

      Example Details

      In the example, the scripting VI needs to manipulate control terminals, which are block diagram objects. Therefore, the scripting VI specifies BD as the container for the scripting VI to search.

      Note  If the objects of interest are in a cluster or a diagram of a structure, select Other from the enumerated list of possibilities for the Traverse Target input. In both cases, wire the reference for the container cluster or diagram to the Other Refnum input of the Traverse for GObjects VI.

   3. Class name of the object—Refer to the anatomies of common VI objects to determine the class name of the objects you want to manipulate.

      Example Details

      In the example, because the scripting VI is obtaining references to control terminals, the scripting VI uses the class name of control terminals, ControlTerminal.

3. Use the Traverse for GObjects VI to obtain references to the desired objects by wiring the information from step 2 to the Traverse for GObjects VI.
4. Iterate through the returned array of references to manipulate individual objects.

   Example Details

   In the example, the scripting VI uses a For Loop to gain access to each element in the References array.

5. Use the To More Specific Class function to cast each returned reference to a more specific class. The Traverse for GObjects VI returns an array of GObject references rather than references that are members of the class specified by the Class Name input. However, you can safely use the To More Specific Class function to cast the returned references to the class specified by Class Name. When you cast a reference to a more specific class, you can call more specific properties or methods on the reference.

   Example Details

   In the example, the scripting VI casts each returned reference to a ControlTerminal. This cast is necessary because the goal of making the control terminal labels visible can be accomplished only by setting the ControlTerminal:Label.Visible property to TRUE, and the Label.Visible property is not available for GObjects. This cast does not produce an error because the Traverse for GObjects VI had searched specifically for ControlTerminal objects.

6. Wire the reference to a Property Node or Invoke Node to get or set information about the referenced object.

   Example Details

   In the example, the scripting VI uses a Property Node to set the Label.Visible property of each ControlTerminal reference to TRUE, thereby making the label of the corresponding control terminal visible.

7. Use the Close Reference function to close each open object reference when you are finished using it.

Caveats and Recommendations

• Check the class of each reference when necessary—If you wire the name of a parent class to the Traverse for GObjects VI, you obtain an array of references that share a parent class but may not be members of the same child class. For example, if you use the Traverse for GObjects VI to search for all objects that are members of the Loop class, the VI returns references to both ForLoops and WhileLoops. You can use one of the following two approaches to check the class of a reference:
  • Use the To More Specific Class function to try to cast the reference to a specific class. If the function does not return an error, the reference matches the specific class.
  • Compare the Class Name property of an individual returned reference with the class name that you want to match.
• 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 Using Traverse VI in the labview\examples\Application Control\VI Scripting\Finding and Modifying Objects directory for an example of using the Traverse for GObjects VI.

 Open example  Find related examples