Creating SubVIs

Much of LabVIEW's power and convenience stems from its modularity. You can build the parts of your program one complete module at a time by creating subVIs.

A subVI is simply a VI used in (or called by) another VI. A subVI node (comprised of icon/connector in a calling VI block diagram) is analogous to a subroutine call in a main program.

Figure 5.12 shows how the block diagram of Temperature System Demo.vi calls several subVIs.

Figure 5.12. SubVIs are like functions or subprograms called by VIs.

A block diagram can contain several identical subVI nodes that call the same subVI several times.

You can use any VI as a subVI in the block diagram of another VI, provided its icon has been created and its connector assigned. Drop existing VIs on a block diagram to use as subVIs with the Select a VI . . . button in the Functions palette (see Figure 5.13). Choosing this option produces a file dialog box from which you can select any VI in the system; its icon will appear on your diagram.

Figure 5.13. The Select a VI . . . button on the Functions palette

A VI can't call itself directly by calling itself as a subVI. If you really need to do this, and implement recursion, you can have a VI call itself indirectly using a VI reference, which we'll talk about in Chapter 15.

Creating a SubVI from a VI

Before you use a VI as a subVI, you must supply a way for the VI to receive data from and pass data to the calling VI. To do this, you need to assign the VI controls and indicators to terminals on its connector pane, and you must create an icon to represent the VI.

Designing the Icon

Every subVI must have an icon to represent it in the block diagram of a calling VI; the icon is its graphical symbol. You can create the icon by selecting Edit Icon from the pop-up menu of the icon pane in the upper-right corner of the front panel (see Figure 5.14). You must be in edit mode to get this menu.

Figure 5.14. Selecting the Edit Icon . . . option from the icon pane of a VI, in order to open the Icon Editor dialog

You can also access the Icon Editor by double clicking on the icon in the icon pane. The Icon Editor window, shown in Figure 5.15, will appear. Use its tools to design the icon of your choice.

Figure 5.15. The Icon Editor dialog, which allows you to edit a VI's icon

	Pencil	Draws and erases pixel by pixel. Press <shift> to restrict drawing to horizontal, vertical, and diagonal lines.
	Line	Draws straight lines. Press <shift> to restrict drawing to horizontal, vertical, and diagonal lines.
	Color Copy (Dropper)	Copies the foreground color from an element in the icon. Use the <shift> key to select the background color with the dropper.
	Fill (Fill Bucket)	Fills an outlined area with the foreground color.
	Rectangle	Draws a rectangle in the foreground color. Double-click on this tool to frame the icon in the foreground color. Use the <shift> key to constrain the rectangle to a square shape.
	Filled Rectangle	Draws a rectangle bordered with the foreground color and filled with the background color. Double-click on this tool to frame the icon in the foreground color and fill it with the background color.
	Select	Selects an area of the icon for moving, cloning, or other changes. Double-click on this tool to Select All pixels.
	Text	Enters text into the icon design. Double-click on this tool to change the font attributes.
	Foreground/Background	Displays the current foreground and background colors. Click on each to get a palette from which you can choose new colors.

Press and hold down the <control> (Windows), <option> (Mac OS X), or <meta> (Linux) key to momentarily change any tool to the Color Copy tool (and release the key to change back). This trick allows you to quickly "grab" another foreground color without having to change tools.

The buttons at the right of the editing screen perform the following functions:

• OK Saves your drawing as the VI icon and returns to the front panel window.

• Cancel Returns to the front panel window without saving any changes.

• Help Opens the LabVIEW Help documentation for the Icon Editor.

Although rarely used anymore, you can design a separate icon for display in monochrome, 16-color, and 256-color mode (this feature is an inheritance from the old days of LabVIEW where some people would need to run it on monochrome or 16-color monitors). You can design and save each icon version separately; you can also copy an icon from color to black and white (or vice versa) using the Copy from . . . buttons. Your VIs must always have at least a black and white icon. If no black and white icon exists, LabVIEW will force you to use a default icon.

It is a common practice to create an "icon banner" (a distinctive portion of the icon across the top that has text and a background color) and use it across the top of all VIs that belong to a library, class, or module (any collection of VIs that all "belong" in a group). This icon banner will help you quickly identify that your VIs belong to that group.

To create an icon banner, first open a new VI and then open the Icon Editor.

1.	Double-click the Filled Rectangle tool to draw a solid black border (foreground) around a solid white background, as shown in Figure 5.16. Figure 5.16. Double-clicking the Filled Rectangle tool to create an "empty" canvas
2.	Select the Text tool. If you are on Windows, we recommend you use the font named "Small Fonts" and 8-point font size. You can double-click the Text tool to open the Text Tool Font dialog to make this selection. Place the cursor anywhere in the icon canvas and type "WIDGET" (in all uppercase letters). After typing this text, and before you change tools or click the mouse anywhere, reposition the text by pressing the arrow keys (up, down, left, and right) to position the text, as shown in Figure 5.17. See how the text moves? (Note that it is usually easier to position the text with the arrow keys, after inserting it, than it is to perfectly place the text cursor before typing.) Figure 5.17. Using the Text tool to type the "icon banner" text
3.	Select the Line tool and draw a horizontal line below the text, as shown in Figure 5.18. Figure 5.18. Using the Line tool to draw a horizontal line under the "icon banner" text
4.	Select the Fill tool and then choose a color for the background color of your banner. Make sure that the color contrasts with the color you selected for the banner text. Now fill the background color of the banner, as shown in Figure 5.19. Figure 5.19. Using the Fill tool to fill the background of the "icon banner"

Congratulationsyou now have an icon banner. If you want, you can use this VI as a template for creating other VIs in your "widget" component. Or, you can just copy the banner, using the Select tool, and paste it into other icons after opening the Icon Editor for the target VI.

You can choose different text and background colors for each library, class, module, etc., in your project.

For each VI in a group, place specific text or graphics in the open area beneath the icon banner that is unique to that VI and signifies the VI's function.

Assigning the Connector

Before you can use a VI as a subVI, you will need to assign connector terminals. The connector is LabVIEW's way of passing data into and out of a subVI, just like you must define parameters for a subroutine in a conventional language. The connector of a VI assigns the VI's control and indicators to input and output terminals. To define your connector, pop up in the icon pane and select Show Connector (when you want to see the icon again, pop up on the connector and select Show Icon). LabVIEW chooses the default connector, having 12 terminals. If you want a different one, choose it from the Patterns menu, obtained by popping up on the connector. You can also rotate and flip your connector if it doesn't have a convenient orientation, using commands in the connector pop-up menu.

It is generally recommended (and considered good "style" by many experienced LabVIEW developers) to use the default connector pane (which has 12 terminals) and to use the left-side terminals for inputs (controls) and the right-side terminals for outputs (indicators). Having 12 terminals will give you "spare" (unused) terminals, which you can assign to controls or indicators at a later time.

Follow these steps to assign a terminal to a control or indicator:

1.	Click on a terminal in the connector. The cursor automatically changes to the Wiring tool, and the terminal turns black, as shown in Figure 5.20. Figure 5.20. Your VI with the upper left connector pane terminal selected for wiring to a front panel control
2.	Click on the control or indicator you want that terminal to represent. A moving dotted line frames the control or indicator (see Figure 5.21). Figure 5.21. Your VI with the upper left connector pane terminal wired to the Number 1 control
3.	After you have successfully assigned the control or indicator to the connector pane terminal, it will appear orange, the color LabVIEW uses for floating point numbers (or the different color for the data type of the control or indicator that you've chosen).

If the terminal is white or black, you have not made the connection correctly. Repeat the previous steps if necessary. You can have up to 28 connector terminals for each VI.

You can reverse the order of the first two steps, but you must choose the wiring tool first.

If you make a mistake, you can Disconnect a particular terminal or Disconnect All by selecting the appropriate action from the connector's pop-up menu.

Creating SubVIs from a Block Diagram Selection

Sometimes you won't realize you should have used a subVI for a certain section of code until you've already built it into the main program. Fortunately, you can also create subVIs by converting a part of the code in an existing VI. Use the Positioning tool to select the section of the VI that you want to replace with a subVI, choose Create SubVI from the Edit menu, and watch LabVIEW replace that section with a subVI, complete with correct wiring and an icon. You can double click on your new subVI to view its front panel, edit its icon, look at its connector, and save it under its new name. Use Create SubVI with caution, as you may cause some unexpected results. You will learn more about this handy feature in Chapter 15, "Advanced LabVIEW Features," where we'll describe the restrictions that apply as well as common pitfalls.

SubVI Help: Recommended, Required, and Optional Inputs

If you bring up the Help window on a subVI node in a block diagram, its description and wiring pattern will appear. Input labels appear on the left, while outputs appear on the right. You can also bring up the Help window on the current VI's icon pane to see its parameters and description. You will learn how to edit the description in the next section.

Built-in LabVIEW functions automatically detect if you have not wired a required input and break the VI until you do. You can also configure your subVls to have the same types of required, recommended, and optional inputs as functions. When an input is required, you cannot run the VI as a subVI without wiring that input correctly. When an input or output is recommended, you can run the VI, but the Error List window will list a warning (if you have warnings enabled) that tells you a recommended input or output is unwired. When an input is optional, no restrictions are enforced, and the connection is often considered advanced.

To mark a connection as required, recommended, or optional (or see what state it's in currently), pop up on the assigned terminal in the connector pane and take a look at the This Connection Is>> pullout menu. A checkmark next to Required, Recommended, or Optional indicates its current state (see Figure 5.22).

Figure 5.22. A connector pane terminal shown as Recommended, from the pop-up menu

In the Help window, required connections appear bold, recommended connections are in plain text, and optional connections are grayed if you are using detailed help view. If the Help window is set to simple help view, optional connections are hidden.

Relink to SubVI: Changing Connector Panes of SubVIs

If you change the connector pane pattern (number of terminals, etc.) of a VI that is being used as a subVI, you will have to relink the subVI before you will be able to run (if you press the broken Run button of the VI that contains the modified subVI, you will see that there is a "bad linkage to subVI" error with details stating, "The connector pane connections of the subVI do not match the way it is wired on this diagram."). The subVI whose connector pane was modified will be grayed out, indicating that it has bad linkage. You can correct this problem by selecting Relink To SubVI from the grayed-out subVI's pop-up menu, as shown in Figure 5.23.

Figure 5.23. Relinking a subVI with bad linkage (caused by changing the connector pane pattern)

Choosing a connector pane pattern that has more terminals than your immediate needs means that you can wire additional controls and indicators to your connector pane, at a later time, without having to relink callers (as you would if you had to change your connector pane pattern). This foresight can save you a lot of time later, and help you avoid potential mistakes that can happen during the relinking process.