Control References: Overview

The Control Reference, introduced in LabVIEW 6.0, increases code readability and reusability. A control reference is a reference that points to a specific control or indicator. These references can be passed to property and invoke nodes to modify the attributes and behavior of a control, much like attribute nodes did in versions previous to LabVIEW 6.0.

User Interface Code Modularity

Until the release of LabVIEW 6.0, there was no way of encapsulating the user interface portion of code when doing user interface programming. In previous versions of LabVIEW, user interface programming was done by using attribute nodes. Attribute nodes have implicit links to front panel controls and must reside in the block diagram of the same VI as their associated control. Therefore, if you have a VI that manipulates front panel controls extensively, your block diagram will end up with dozens of attribute nodes taking up a lot of space on the block diagram, making the block diagram cluttered and difficult to read. One of the keys to creating good LabVIEW applications is using the hierarchical nature of the VI. Creating modular programs using subVIs makes applications easy to debug, understand, and maintain. Previous to LabVIEW 6.0, there was no way to apply this same modular approach for user interface programming. The introduction of control references alleviates this problem.

By passing references of a control to a subVI, the user has the ability to encapsulate user interface programming code into a subVI. The corresponding results can be seen in the two screenshots below. These VIs reposition the front panel controls to the right or the left by an offset supplied by the user. Notice how much more compact the second block diagram is. It uses control references instead of property (attribute) nodes to accomplish the same task as seen in the first block diagram.

With Attribute Nodes:
The first block diagram uses attribute nodes (replaced by property nodes in LabVIEW 6.0) to do user interface programming of controls/indicators in the front panel. This method requires getting the current position of each control. These positions are then sent to a subVI that calculates a new position. The new position is then passed out of the subVI, and the new position values are set in the main VI.



With Control References:
Control References are wired directly to the subVI, sending a reference or pointer to the control to the subVI. This allows the subVI to perform operations on these controls, as it now has a direct reference back to that specific control. Within the subVI, property nodes take the control reference (refnum) and allow you to access the control's attributes.

Replacement of Attribute Nodes

As of LabVIEW 6.0, the attribute node has been replaced by the property node. The property node has been modified to accept control references (refnums) and be able to have an implicit control refnum input. The use of a property node that is implicitly linked to a control is similar to that of an attribute node. Create a property node by right-clicking the control/indicator and selecting Create>>Property Node. This drops on the block diagram a property node without a refnum input that is implicitly tied to the control. This behavior is similar to that of the attribute node.

One difference between attribute nodes and the revised property nodes is that the attribute node does not have error in and error out terminals, but the property node does. In the attribute node, all of the attributes are evaluated. In the property node, the evaluation stops if there is an error, and any subsequent properties are not evaluated. To keep the behavior consistent, you can right-click the property node and select Ignore Errors Inside Node. In this new mode, all the properties are evaluated even if there are errors. The property node returns the first error, if any, from its error out terminal.

Creating Control References

Creating Control References to Emulate Attribute Nodes (Implicitly Linked)
Use a property node with an implicit refnum input to set or read a control's attributes in the block diagram of the same VI. To create an implicit property node, right-click the front panel control (or its terminal in the block diagram) and create a property node as shown below. The property node is implicitly linked to the front panel control from which you created the property node, in that the information pointing the node to its corresponding front panel control is contained implicitly within the node. An implicitly linked property node is drawn differently from the normal property node, as it does not have a refnum input and output. The referenced control's name will be shown in the property node's label.


You can find the referenced control from the property node by right-clicking and selecting Find>>Control. You also can double-click the property node to find the referenced control. To find the property nodes associated with a front panel control, right-click the control and select Find>>Property Nodes.

Implicit property nodes also can be linked by first placing a property node on the block diagram. Then right-clicking the node and select Link to to see a list of front panel controls that can be linked to. The Link to Control menu item is not available if the refnum input of the property node is wired.



Creating Control References to Separate User Interface Code to a SubVI (Explicitly Linked)
The first section of this document demonstrates one of the advantages of separating the user interface portion of your code to a subVI. This is done by the following steps.

1. Create a Control Refnum Constant by right clicking on the control (or its terminal in the block diagram) and select Create >> Reference.



2. On the front panel of the subVI, you need to have a control refnum that can accept the control reference you are passing to it. There are two ways of creating a control refnum control. One way is to drag the control refnum constant you just created in Step 1 to the front panel of the subVI. This will create a properly configured control refnum control.

Another way is to place a Control Refnum Control (Controls Palette >> Refnums >> Control Refnum) on the front panel. The Control Refnum is then configured to match the Control Refnum Constant by dropping an appropriate control in it as shown below.


3. In the subVI where you created the Control Refnum Control, you can wire the control refnum's terminal in the block diagram to property nodes and thus access a control's attributes from the subVI. You do not need to close the control reference you obtained from the control refnum constant. Set up the subVIs connector pane to have the Control Refnum as one of the inputs. Then wire the Control Refnum Constant you created in the main VI to the Control Refnum terminal of the subVI. This is shown in the diagram above. This method is referred to as an explicitly linked control reference because the Control Refnum Control in the subVI is explicitly wired to the Control Refnum Constant in the main VI, which tells it what control in the main VI that it is linked to.


Using Control References to Pass Access of Front Panel Controls to SubVIs
We have already seen how to place our user interface code in subVIs. We can also pass access to front panel control or indicator values to subVIs. This is done the same way as described in the section directly above discussing explicitly linked control references.

In the main VI, there is a Control Reference Constant for the Waveform Chart Indicator and the Boolean Strop Control. These references are wired to the subVI.




The subVI has two Control Refnum Controls. One corresponding to the Waveform Chart and one to the Boolean. Looking at the subVI block diagram, we can see what is being done with the control and indicator from the main VI. The Waveform Chart Refnum is fed to a Property Node that turns on autoscaling for the chart. This refnum is then passed inside the while loop where it is used to write a value to the chart in the front panel of the main VI. Meanwhile, the Boolean refnum is being used to read the current value of the Boolean control in the main VI's front panel to determine when the user selected the stop button.



This example illustrates how to read and write values from a subVI to controls and indicators in a main VI. A similar example that would be useful involves doing data acquisition in a subVI, displaying the data in the main VI, and terminating the data acquisition being done in the subVI from the main VI.

Weak vs. Strict Type Control Refnums

Allowing the user to choose refnums to be weakly or strictly typed gives them more freedom in programming. A weakly typed refnum is one that does not contain information about the type of data that the refnum points to. Conversely, a strictly typed refnum does contain the data type for the object that it points to. You can change between weakly and strictly refnums by right clicking on the refnum (or its terminal in the block diagram) and selecting "Include Data Type" for strictly and deselecting it for a weakly typed refnum. A red star on the Control Reference Control designates that the refnum is strictly typed. There are different cases for when you may want to use a strictly typed refnum over a weakly typed refnum and vice versa.

A control refnum terminal that is strictly typed can only accept control references that are strictly typed to a compatible type. For example, if a subVI expects a control refnum of type Slide(Int32), you can wire a control reference of type Slide(Int32), Slide(Int8), or Slide(DBL), but not of type Slide(Cluster of DBLs). Wiring in the Slide(Int8) or Slide(DBL) will result in type coercion (no error) and thus a coercion dot as these representations are being coerced to Int32. Wiring the Slide(Cluster of DBLs) will result in a type conflict (error) and thus a broken wire. This is because the Int8 and DBL are numerics like the Int32 and can thus be coerced to be of Int32 representation. The Cluster of DBLs however, is not a numeric, but a totally different data type. Therefore, a cluster being of different data type than the numeric will result in a type conflict if wired together. Strictly typed references are most beneficial when you know exactly what type of data you will be using.

A control refnum terminal that is weakly typed does not care about the data type information of the input control refnum. If a subVI expects a control reference of type Slide(any data type), because it is weakly typed, you can wire a control refnum of type Slide(Int32), Slide(cluster of DBLs), etc. In this case, as long as the control is of the class Slide, it will be accepted by the weakly typed control refnum no matter what data type the Slide is. Thus, to create a subVI that operates on any slide, the user should use a weakly typed control refnum. If the user wants to access the slide's data in the subVI as the exact data type, he needs to use a strictly typed control refnum. Using weakly typed references can be beneficial when you want to allow a wide range of data types for a given control. It provides versatility of code as a subVI with a weakly typed control reference could be used multiple times on Slides (in this case) with varying data type.

Note: The chart history data property is available only when you wire a strictly typed chart refnum to a property node. This is because the data type of the history data of a chart depends on the data type of the chart itself. Therefore, if you need to use the chart history data property, remember to use a strictly typed reference.

Control Refnum Object Classes

As mentioned in the previous section, weakly and strictly typing allows for mobility within a certain class. But how do we give this same type of freedom for a control refnum to handle multiple classes. There are two ways to configure a Refnum Control for a particular class. The first method is mentioned above where an actual control is dropped in a refnum control container. Control refnums created by this method are strictly typed. The other way to select the control class is to right click on the control container, Select VI Server Class, and then select the desired class of the control. Refnum controls created in this method are weakly typed. The example below shows how a Boolean class is selected for a refnum control.


Selecting a more generic class for a control refnum will allow it to accept a wider range of objects. The top entry in each of the sub-menus above includes all of the entries beneath it. For example, selecting GObject will make that control refnum able to accept references from decorations, scales, controls, and panels. This could be a beneficial practice if we want to perform the same, general operation on multiple objects. All controls have the attribute "Visible". Therefore, if we wanted to be able to selectively turn on and off the visibility of our front panel controls, we could have one subVI to do this. This is because we would set the refnum control in that subVI to be of type "Control" so that it would accept all types of controls that we may have.

The following example shows a main VI allowing the user to select whether to write a value to a digital control or a slide. A refnum constant is created for each control and sent to a subVI. The subVI then writes the value to the control specified by the refnum. It is important to note here that digital controls and slides are both in the numeric class(both located in the numeric palette). Therefore, Numeric was selected as the VI Server Class for the refnum control in the subVI, allowing it to accept either the digital control or the slide control as Digital and Slide are two subclasses under the Numeric Class.

Reader Comments | Submit a comment »

"3. In the subVI where you created the Control Refnum Control, you can wire the control refnum's terminal in the block diagram to property nodes and thus access a control's attributes from the subVI." No explanation on how to make a property node
- shipleys@pxi.com - Oct 12, 2004