Configuring Your VI

Often you may want your program to bring up a new window when a certain button is pressed or a certain event occurs. For example, you may have a "main" front panel with several buttons that present options. Pressing one of the buttons would lead the user to a new screen, which may in turn contain an "Exit" button that would close the window and return to the main front panel. Because this pop-up window will usually be the front panel of a subVI, you also may want to customize what features of this window should appear, such as the Toolbar, or the clickable box that closes the window.

You can set several options that govern the window appearance and the execution of your VIs in two different places:

1.	VI Properties . . . (from the pop-up menu of the VI's icon pane, which you will find in the upper-right corner of the front panel window).
2.	SubVI Node Setup . . . (from the pop-up menu on a subVI's icon in the block diagram).

A very important distinction should be made at this point: the setup options under SubVI Node Setup for a subVI affect only that particular instance of the called subVI, while the VI Setup options always take effect, whether it's run as a top-level VI or called as a subVI. We'll start first with the few and simple SubVI Node Setup options.

It is best to make your settings in the VI Properties . . . dialog rather than the SubVI Node Setup . . . dialog. The reason for this is that it is not obvious that a SubVI has been configured using the SubVI Node Setup . . . dialog. It can take a long time to track down why different instances of SubVIs are behaving differently, and the SubVI Node Setup . . . dialog is the last place people usually look.

SubVI Node Setup Options (Are Evil)

As we just mentioned in the previous warning, the SubVI node setup options can cause a great many problems and they are not commonly used. (If one instance of a VI is misbehaving, the SubVI Node Setup options is the first place to look!) It is, however, important that you know how this feature worksyou might just run across a node or two that has these options set. So, we will describe the various SubVI Node Setup . . . options and do a simple activity, now that you have had a stern warning not to use them.

When you select the setup option from the pop-up menu on a subVI, you get the dialog box shown in Figure 15.3.

Figure 15.3. SubVI Node Setup dialog

You can select any of the following options:

• Open Front Panel when loaded The subVI's front panel pops open when the VI is loaded into memory (such as when you open a VI that calls this subVI).

• Show Front Panel when called The VI front panel pops open when the subVI is executed. You'll find this option and the next to be pretty useful for creating interactive VIs.

• Close afterward if originally closed Causes the subVI front panel to close when its execution is complete, giving that "pop-up" window effect. This option is only available if the previous option is selected.

• Suspend when called Same effect as setting a breakpoint; that is, causing the VI to suspend execution when the subVI is called. You can use this as a debugging tool to examine the inputs to your subVI when it is called but before it executes.

Remember, all the subVI setup options apply only to the particular subVI node you set them on. They do not affect any other nodes of the same subVI anywhere else. Oh, yes, and you should not use any of these options.

Activity 15-1: Using SubVIs

This activity will let you use the SubVI Setup Options to create a "login" shell that can be used with any application.

1.	Make a simple front panel, as shown in Figure 15.4, that will call a "pop-up" subVI when the button Change User is pressed. Call this top-level VI Shell.vi. Figure 15.4. Front panel of the VI you will create during this activity
2.	Use the subVI Login.vi (which you will find on the CD) to build the block diagram, as shown in Figure 15.5. Figure 15.5. Block diagram of the VI you will create during this activity
3.	Pop up on the Login subVI, and choose SubVI Node Setup. Select only the Show Front Panel when called and Close afterwards if originally closed options, as shown in Figure 15.6. Figure 15.6. SubVI Node Setup options for the Login.vi subVI

When this VI is run, it will display the last value of the Current user (from the uninitialized shift register), until the Login VI is called and changes it.

Login must be closed before you run this example. Otherwise, it will not close after it finishes executinghence the phrase, "Close afterwards if originally closed."

Although you just learned how to use the SubVI Setup Options to create a subVI as a pop-up dialog, this practice is generally discouraged in any important LabVIEW application. We showed you this because you'll see it used in some older LabVIEW applications and even some of LabVIEW's examples. So it's OK to use this method for quick and trivial VIs. But for a more robust application, you will learn a better way to open and close the front panels of subVIs, using VI Property Nodes, later in this chapter.

VI Properties Options

VI properties are a bit more numerous. The dialog box that appears when you choose VI Properties . . . by popping up on the icon pane gives you a number of property sets: General, Memory Usage, Documentation, Revision History, Security, Window Size, Window Appearance, Execution, and Print Options. Some of these are read-only properties (such as memory usage); others are configurable. Let's examine these in more detail briefly.

General

This VI property set shows you the file path to the VI, the icon, and so on.

Memory Usage

This property pane shows you how much RAM your VI is using.

Documentation

Here you can (and should) type in documentation for your VI. Good programming practices dictate that you should always type a description of your VI in the VI Description field, as shown in Figure 15.7. This description will show up in the Help window if you hover the mouse button over your VI's icon. You can also optionally enter a Help Tag and a Help Path to an external Help file.

Figure 15.7. Documentation section of the VI Properties dialog

You can enter a help path to HTML (.html) files on all platforms or compiled help (.chm) files on Windows, Apple Help on Mac OS X, and QuickHelp on Linux. See Chapter 17, "The Art of LabVIEW Programming," for more information on adding online help to VIs.

Revision History

This property set allows you to set up a very simple source code history. It gives you the option of seeing what revision your VI is in, and any comments from previous revisions. This is only useful if you have been typing comments in this window every time you save the VI.

Editor Options

These options allow you to set the Alignment Grid Size and the Control Style for controls created from the right-click Create Control and Create Indicator shortcut menu options of various LabVIEW objects.

Security

By default, anyone who has your VI can view and modify the source code (the block diagram). In some cases, you may not want others to modify your block diagram code, either by accident or on purpose. Or you might not even want others to see the block diagram. Here you can specify a password that will be required for anyone to view or modify the block diagram.

If you password-protect a VI, be sure you remember or write down the password somewhere. There is NO way to access the VI's code if you forget the passwordnot even NI can help you. Be careful!

Password-protected VIs can be run on all platforms (Mac OS X, Windows, and Linux) and newer LabVIEW versions than where the VIs were created. However, VIs that have had their block diagrams removed can only be run on the version of LabVIEW they were created in. So, password protection of VIs might be a good way for you to distribute your VIs to others who may need to open them on different platforms or newer LabVIEW versionsthis allows you to distribute a single version of your files.

If you choose to distribute password-protected VIs, it is a good idea to only password protect a copy of the VIsnot your original, project source VIs. You might also consider selecting a long, random password, because nobody will need to get into the VIs (you have the original VIs that are not password protected). You can create a Source Distribution project Build Specification (in the LabVIEW Project Explorer) or you can use the OpenG Builder, which even has an option for randomized password protection of source distributions.

Window Appearance

The Window Appearance options, shown in Figure 15.8, let you control many details of your VI's window appearance. You can choose between the pre-defined setups of "top-level application window," "dialog," or "default," or you can customize the look.

Figure 15.8. The Window Appearance section of the VI Properties dialog and the Customize Window Appearance dialog floating above it

Most of the options are self-explanatory; however, a few comments are in order:

• Be careful with options such as disabling the Show Abort Button. A VI with this option can't be hard-stopped, even with the keyboard shortcut, once it's running! (You have to kill LabVIEW to stop it if you didn't provide a programmatic way to abort the VI.) Only use this for VIs you have tested and know will exit properly from the code.

• The Dialog Box option gives the VI an appearance of the standard OS system dialog box, and prevents accessing other LabVIEW windows. (A window that does not allow you to access others is commonly referred to as modal.) Be careful with this setting. If you open a modal VI that is not running, but is a subVI of a running VI, then you will be "locked out" and only allowed to interact with the modal VI you just opened. (This is not an uncommon situation. In Activity 15-9, you will create a utility that you can use to rescue yourself from this predicament.)

• The Floating window behavior will cause the window to stay frontmost, but allow you to interact with other windows behind it. For example, the LabVIEW Tools, Controls, and Functions palette windows are floating windows.

• Hilite <Enter> BooleanOK, so not all of these options are self-explanatory. This option will highlight (put a black border around) the Boolean control that has been assigned the <Return> or <Enter> key, as discussed in the next section.

• The Window Run-Time Position options allow you to define the window position and size, as well as the monitor where the VI will first appear, when the VI is run.

Window Size

This property allows you to force the VI to be a minimum pixel size. You can also specify settings for letting front panel objects automatically scale if the front panel is re-sized.

Print Options

These settings allow you to specify the options like headers and margins for printing.

Execution

The Execution options shown in Figure 15.9 allow you to set some very advanced execution tweaks.

Figure 15.9. Execution section of the VI Properties dialog

• Priority: Don't mess with this; you shouldn't need it. Trust me on this one. If you really want to know what this is about, read the LabVIEW manuals.

• Reentrant execution deserves a little more explanationwe will discuss it in the next section.

• Run When Opened does just that.

• Suspend When Called is a rarely-used debugging option (and, like the subVI Node Setup options, you should probably avoid it).

• Preferred Execution System: This is LabVIEW's attempt at multi-threading. It allows you to choose one of several threads for your VI to run it. If you don't know what I'm talking about, you won't need it either.

• Auto handle menus at launch causes LabVIEW to automatically handle menu selections in your running VI. If you remove the checkmark from this option, the run-time menu bar is disabled until you use the Get Menu Selection function (found on the Programming>>Dialog & User Interface>>Menu palette) to handle run-time menu selections.

• Allow Debugging, checked by default, gives you access to LabVIEW's debugging tools when the VI is running. You can uncheck it to obtain a slight 12% increase in speed and decrease in memory usage of the VI.

• Clear Indicators when Called causes LabVIEW to reset indicators values to their defaults, when the VI is first runotherwise, they will only change when their values are changed programmatically.

• Enable Automatic Error Handling causes LabVIEW to capture and display an Error Dialog if any VI or function on the block diagram outputs an error that is not wiredwe discussed error handling in Chapter 7, "LabVIEW's Composite Data: Arrays and Clusters."

Reentrant Execution

Reentrant execution is an important concept. Normally, when you have more than one instance of a subVI, only one instance can be called at a time (other instances must wait in line until no instance is running and it is their turn to execute). And, normally, all instances share the same data spacethey share the same control and indicator values as well as shift register and other data storage spaces, which is why only one can execute at a time. However, when a subVI is configured for reentrant execution, each instance will have its own data space and can be called independently of (and at the same time as) other instances.

If this sounds confusing, don't worry. Keep reading and study the examples here and you'll begin to see the difference between a reentrant and a non-reentrant VI.

There are two main reasons why you might want to configure a VI for reentrant execution. First, you may not want the non-reentrant behavior where only one instance may be called at a time. If a subVI takes a noticeable amount of time to complete execution and is called in several locations that might execute in parallel, the total execution time of your code might be slowed down by some instances of the subVI having to wait for another instance to finish executing, before they can execute. Second, you may want each subVI instance to have its own data space because they are being used as data storage containers for specific tasks. For example, in the block diagram shown in Figure 15.10, we are using the subVI Running Average on each data channel.

Figure 15.10. Block diagram showing the Running average subVI called in two locations

Running Average uses uninitialized shift registers as memory elements. Remember that uninitialized shift registers keep their last value even after the VI is stopped and run again (see Chapter 6, "Controlling Program Execution with Structures," for a discussion of uninitialized shift registers). If this VI were left in the default (non-reentrant) mode, it would give unexpected results because the call to either subVI node would contain the shift register data from the last call to the other node (because the subVIs will normally take turns executing). By choosing the "Reentrant execution" option, each subVI node is allocated an independent data storage space, just as if they were two completely different subVIs (see Figure 15.11).

Figure 15.11. Running Average.vi block diagram

Debugging Reentrant VI Instances ("Clones")

If you open the front panel of a reentrant subVI, as shown in Figure 15.12, the name of the VI in the window title bar is suffixed with a unique instance number and the text "(clone)".

Figure 15.12. Running Average.vi "clone" (reentrant instance)

Each instance of a reentrant subVI can be opened independently. The reentrant subVI "clones" allow you to interact with the reentrant subVI instances while your application is running. You can debug each clone independently using execution highlighting, single stepping, breakpoints, and wire probes, as well as watching the front panel control and indicator values change while the clone is running.

You will notice that the clones are in Run Mode and cannot be edited. However, if you change the clone to Edit Mode, by selecting Operate>>Change to Edit Mode from the menu (or using the <ctrl>+M shortcut key combination), the front panel of the reentrant VI (the real VI, not a clone) will appear. The clone(s) will remain open until you make a change to the reentrant VI, at which time they will close, because they are no longer valid (since the VI they were cloned from has changed).

Activity 15-2: Reviewing Recycled Reentrancy

As an interesting activity, first run this VI we just mentioned, Running Average.vi, which is on the CD, to see how it works. Then run the Reentrant VI (also on the CD) first as it is, and then change the "Reentrant Execution" option for the Running Average VI to compare the differences.

Keyboard Navigation

If you are one of those people who think mice are unfriendly (or your end users think so), there's good newsyou can set up your VI to allow users to "navigate" the controls with the <tab> key (and other keys). Without any special setup, you can always use <tab> to pick the control that will receive input (you can't pick indicators this way, because indicators don't accept inputs). A "selected" controlcalled the key focushas a rectangular border enclosing it. Once a control is the key focus, you can use the appropriate keys to enter its value. The following tips may be useful:

• If you directly type the value into the selected control, you must hit the <enter> key when you are done to make your entry valid.

• For numerical and ring controls, you can also use the arrow keys to advance to the desired number. Pressing <shift> with the <up> or <down> arrow key advances the value faster. You can set the minimum increment from the Data Range . . . option in the pop-up menu of the control.

• For Boolean controls, the <return> key toggles the Boolean value.

• Tabbing from control to control normally follows the order in which you created the controls

For VIs with several controls, you may wish to set your own tabbing navigation order; that is, determine once a control is selected, which control will be selected next when the <tab> key is pressed. This sequence is known as tabbing order in LabVIEW. To change the panel order, choose Set Tabbing Order . . . from the Edit menu. This works in the same way as the Cluster Order . . . option, discussed in Chapter 7. The front panel in Figure 15.13 shows what it looks like when Tabbing Order is selected.

Figure 15.13. Front panel with Set Tabbing Order selected

On your front panel, all controls will be boxed in with two numbers in the lower-right corner of each box. The number in the white background represents the previous panel order; the number in the black background represents the new panel order you are assigning to your diagram. To create the new panel order, click successively on each control in the desired order, or type a sequence number into the text input box on the toolbar that you want to assign to the next control that is clicked, and then click the OK button. To cancel all changes, click the X button.

You can also assign certain "special" keys to a control, from the Key Navigation dialog (see Figure 15.14), which is accessible by selecting Advanced>>Key Navigation . . . from a control's pop-up menu.

Figure 15.14. Key Navigation section of the Boolean Properties dialog

All controls allow you to define a "Focus" key that, when pressed, will select that control. Boolean controls allow you to define a "Toggle" key that, when pressed, will toggle the state of the Boolean (just as if you had pressed it with the mouse). And, numeric controls allow you to define "Increment" and "Decrement" keys that, when pressed, will increment and decrement the numeric's value (respectively).

The Key Navigation dialog also allows you to specify "Skip this control when tabbing," which causes that control to be skipped as the user is pressing the <tab> key to cycle key focus between controls.

You can assign function keys (<F1>, <F2>, etc.) to a control, as well as function keys with modifiers (such as the <shift> or <ctrl> keys). Pressing the selected key will set the key focus on that control without having to "tab" to it. You will find Key Navigation useful if you have many controls but have a few you use more often.

Finally, you can also programmatically set or disable a control's key focus. The Key Focus property of a control is a Boolean that, when true, means the control is "selected" and ready for keyboard input.

Figure 15.15. Key Focus property of a string control set using a Property Node

Activity 15-3: A Login VI

Build a Login VI with a nice front panel, as shown in Figure 15.16. This VI should make the Key Focus first appear in the LOGIN box. The VI should detect when the user has pressed <return> or <enter> and move the Key Focus to the PASSWORD box. The password characters should not be seen. Finally, the VI should appear in the middle of the screen with the same appearance as a dialog box from the OS. Don't forget to enable the Limit to Single Line options for the string controls on the front panel, as shown in Figure 15.16.

Figure 15.16. Setting the Limit to Single Line option for the LOGIN and PASSWORD string controls

The following hints will help you complete this activity.

1.	You will need to use the Key Focus control property.
2.	Pop up on the PASSWORD control and select the "Password" option for the string.
3.	Pop up on the LOGIN and PASSWORD control and select the "Limit to single line" option.
4.	How will this VI know when a user has finished the input string to the LOGIN? When a string control is configured to "Limit to single line," pressing the <return> or <enter> key does not add a new line to the string; rather, it will lose key focus (Key Focus = FALSE). You will need to periodically check whether the control has lost key focus. You can store the key focus value in a shift register and test whether it is currently FALSE AND previously TRUE.

The solution is found on the CD.