NI Tutorial 3198

8/2/2019 NI Tutorial 3198

1/121/12 www.ni.c

Creating New Front Panel Objects with LabVIEWXControls

1.

2.

3.

4.

5.

6.

7.

8.

9.

Overview

LabVIEW 8 enables LabVIEW developers to create user-defined controls from existing LabVIEW controls. These custom controls are called XControls. With this new feature, you can combine th

basic functionality of LabVIEW controls with additional functionality you develop.

Table of Contents

General characteristics of XControls:

The Structure of an XControl

How to Build an XControl

Custom Properties for XControls

Custom Methods for XControls

XControl Run-Time Shortcut Menus

XControl Sizing:

Debugging an XControl:

Running the XControl

General characteristics of XControls:

They are represented on the block diagram by a single icon and hence dramatically reduce code size

They are re-usable. They can be used created on one computer and used on another with full functionality.

User functionality can also be easily added to an XControl. By simply adding an add itional component to the XControl front panel and programming the new component in the XControl block

diagram, the new functionality can be directly ported to all dependent VIs.

They are packaged into one library and hence all related VIs are grouped together for ease of portability.

They can be used in the project they are created in or added to the control palette and used by another VI that may not be part of any project.

The Structure of an XControl

To create an X Control, right click on My Computer in the Project Explorer menu and select .New>>XControl

X Controls are comprised of four required components and other optional/user-defined components. The required components are also known as abilities:

Data

State

Faade

Init

These abilities are actually just VIs and controls (.ctls) that define the XControls functionality. There are two optional abilities that can be added. They are the following:

Convert State For Save

UnInit

:Document Type Tutorial

: YesNI Supported

: Jul 27, 2007Publish Date
http://search.ni.com/nisearch/app/main/p/lang/en/pg/1/ap/tech/sn/catnav:tu,ssnav:dznhttp://search.ni.com/nisearch/app/main/p/lang/en/pg/1/ap/tech/sn/catnav:tu,ssnav:dzn


2/122/12 www.ni.c

To add either of the optional abilities, right-click on the XControl from the project menu and select . A screen will display which abilities are currently associated with the XControl. FromAbilities

there select the desired abilities.

Every XControl has its Data and State associated with it. Data is the type of data represented by the XControl (scalar, array, etc) and the State is the current state of the XControl (visible, control

indicator, etc). You define the data type and various state of your XControl.

The Faade VI manages the different states the XControl can get into and how it responds to user events. Hence this is a giant event handler VI that is called by LabVIEW only when there is an

event pending for it to handle. Whenever the Faade is called, LabVIEW passes in the current data and state of the XControl as inputs. The Faade VI then handles the event and updates the da

and state and returns them to LabVIEW to be stored with the control.

How to Build an XControl

To demonstrate how you create an XControl, we will build the Dual Mode Thermometer (DMT) example program that ships with LabVIEW 8. This example program can be found at the following

location or via the Example Finder utility.

\examples\general\xcontrols\Dual Mode Thermometer

Upon opening the LabVIEW Simple Dual Mode Thermometer project, the following files appear in the Project Explorer Window.

The Data ability Simple Dual Mode Thermometer Data.ctl

The Data ability is a type definition control that specifies which type of data LabVIEW will pass into and receive from the XControl. This can only be one data type; however, more complex types

such as Clusters, Waveforms, etc. may be used as the type definition.

For the purpose of this example, the data type is a double.


3/123/12 www.ni.c

The State ability Simple Dual Mode Thermometer State.ctl

The State ability is a type definition cluster that contains variables used to control the appearance and/or behavior of the X Control. It is here that a user can define all algorithms that must be

applied to the data.

For the Dual Mode Thermometer example, the state has a Boolean that identifies whether or not the temperature will be displayed in Fahrenheit mode. The user can change the mode by selecti

a checkbox which is part of the XControls facade. By default, the Fahrenhe it mode is disabled.

The Init ability Simple Dual Mode Thermometer Init.vi

This ability is used to initialize the control. It has three inputs and one output. The inputs are:

Previous version

Previous display

Container state

The one output is:

Current State

Using information gained from the three inputs a, current state is output. LabVIEW calls the Init ability when the XControl is first placed on a front panel or when a VI containing that XControl is

loaded into memory. The Init ability also updates previous versions of the XControl to the latest version. When a VI containing an XControl is loaded into memory, LabVIEW calls Init and checks

the version has changed since the last time the VI was saved.

Init includes and controls and a indicator. When the version changes, Init converts the value of , which is passed in as a variantPrevious Version Previous State Current State Previous State

the new state format. The new state is passed to the indicator.Current State

The Facade ability Simple Dual Mode Thermometer Facade.vi

The Faade ability defines the appearance and behavior of the X-Control. You create the XControls appearance by adding controls and indicators to the front panel of the Faade. These can the

be controlled by the events in the block diagram. When making an XControl that will function as both a control and indicator, overlapping the controls and the indicators on the Front Panel is

needed as their visibility will be determined by the container state.


4/124/12 www.ni.c

The faade VI is called when the user interacts with the XControl and these user events need to be handled. The events can be either on the faade VIs front panel or they can be caused by

certain user actions on the X-control.

The faade VI has three inputs and three outputs.

The inputs are:

Data In: The current value of the XControl.

Display State In: The current state of display that is used to manipulate the Faades appearance.

Container State: This input state passes the information that tells whether the control is a control or an indicator, whether it is in edit or run mode, and provides a ref num to the container

The outputs include:

Data Out: The data that is passed to the Data State for use as the Data In during the next iteration

Display State Out: The data that is passed to the Display State to indicate the current state of the XControl

Action: This indicates what action has taken place on the current iteration of the Faade. This is particularly useful when using undo and redo actions in LabVIEW.

All calls to the X-Controls faade VI are made by LabVIEW. LabVIEW calls the faade VI only when there is an event pending for it to handle. There are four mandatory events for a ll faade VIs

and other custom events that can be added by the programmer.

The four mandatory events are:

Data Change: This occurs when data is passed into a Front Panel Terminal, Local, or Property Value of the particular XControl. This event will be used in conjunction with the display state to

update the current values of the controls on the Faades panel.

Direction Change: This occurs when the user changes the direction of the XControl from an indicator to a control and vice versa. This event will be used with the container state to update the

appearance of the XControl.

Exec State Change: This occurs whenever the VI owning the XControl changes from edit mode to run mode or vice versa. This event will be used to disable the ab ility to change an indicator

during runtime.

Display State Change: This occurs when the display state changes in response to a user invoking a property or method on the XControl.

In our Dual Mode Thermometer example, the Event Structure handles the following mandatory events:

[0] Timeout:


5/125/12 www.ni.c

Timeout occurs when the VI needs to be stopped. Always wire TRUE to the stop condition in the timeout case and FALSE in all other cases.

[1]Data Change:

LabVIEW calls the Facade VI with the Data Change event whenever data is written to the thermometers terminal or local or value property.

When the data value is changed, our XControl does the following:

1. Checks if the DMT is in Fahrenhe it mode or not

2. Sets the thermometer and slide to the appropriate value

[2] Display State Change:

LabVIEW calls the Facade VI with Display State Change event whenever LabVIEW needs to update the appearance of the XControl.

The code does the following:

1. Checks if the DMT is in Fahrenhe it mode or not

2. Sets the thermometer and slide to the appropriate value

[3] Direction Change

LabVIEW calls the Facade VI with the Direction Change event whenever the XControl changes from a control to indicator and vice-versa.

In the example, the slide is the control and the thermometer is the indicator. When the event occurs,

1. Checks to see if the XControl is currently an indicator

2. Sets the visibility of the thermometer and slide accordingly


6/126/12 www.ni.c

[6] Exec State Change

LabVIEW calls the Facade VI with Exec State Change event whenever the VI containing the XControl switches from idle mode to run mode and vice versa.

In this example, it is important that the user not be able to change the value of the temperature scale while in run time mode. Therefore, we disable the scale while it is running and enable it while

is not.

In the Dual Mode Thermometer example, a custom event occurs when the user manually changes the display state by enabling or disabling a control, e.g. selecting the Fahrenheit check box.

Note: There is a difference between the events generated by LabVIEW and events generated by a user. LabVIEW generates events when data is passed into the control either by a wire, propert

node, or a local variable. However, if the user changes anything on the XControl, then new events must be created to handle these situations. In the case of the Dual Mode Thermometer examp

that would be value changes on the thermometer, slide, and Fahrenheit controls.

[7] Thermometer: Value Change

LabVIEW calls the Facade VI with the Thermometer Value Change Event when the user changes the value of the Thermometer.

When data is changed the code does the following:

1. Checks to see if the XControl is in Fahrenheit mode

2. Sets the values of the slide accordingly

3. Updates the Data Out with the new value created after the code is executed

4. Informs LabVIEW that value changed by setting the boolean to TRUE.Data Changed?

[8] Slide: Value Change

Similarly when the value on the slide changes, the appropriate event is triggered and the changes are updated on the state VI.


7/127/12 www.ni.c

[9] Fahrenheit: Value Change

LabVIEW calls the Facade VI with Fahrenheit Value Change Event when the user changes the value of the Fahrenheit mode.

When data is changed the code does the following:

1. Checks to see if the XControl is in Fahrenheit mode.

2. Sets the values of the thermometer and slide based on the mode selected.

3. Update the Display State with the new value.

4. Inform LabVIEW that value changed by setting the State Changed? boolean to TRUE.

Custom Properties for XControls

A user can programmatically create and configure an XControls properties. XControls use property nodes to get and set properties (just like many other built in VIs in LabVIEW). When a property

needs to be retrieved or set, LabVIEW calls on the faade VI. If the user changes the display state with a property, the faade VI in turn updates the display VI so that the XControl reflects the cha

visually. When this happens, a Display State Change event is generated on the Faade VI.

As we saw earlier, an XControl is essentially a library of VIs. In the XControl library, each of the XControls property is represented by one or more VIs depending on if the property is read only,

write only or read/write.

To add a property to the XControl library, do the following:

1. Right click the XControl and select from the shortcut menu to display the Create Property dialog box. Add a property to the library from this box.New>>Property

2. LabVIEW will now create a folder within the XControl library that has the same name as the property.

3. A read/write property folder will contain two VIs while a read-only or a write-only property will create one VI. It is important to note that the property folder for any property within the XControl

cannot contain more than two VIs.

4. To edit the property, open the VI that is represented by that property and edit its functionality.

5. When editing any read property VI in the XControl, it is important to replace the Value indicator with an indicator matching the data type of the property.

6. When editing any write property VI in the XControl, it is important to replace the Value control with a control matching the data type of the property.

In the DMT example, there are two property VIs as seen here.


8/128/12 www.ni.c

The write property will set whether the display state is in Fahrenheit mode or not. For this a bundle by name function is used to set the state of the display.Fahrenheit Mode?

The read property will return whether the display state is in Fahrenheit mode or not. For this, we use the function to get the state of the display.Fahrenheit Mode? Unbundle By Name

Custom Methods for XControls

You can also programmatically create and configure an XControls methods. An XControl user would use the LabVIEW invoke nodes to execute the XControls methods. LabVIEW calls the Faad

VI after the user calls a XControls method. If the particular method happens to make changes to the display state, the Faade VI will update the display state so that the XControl can update its

appearance. For this reason, a Display State Change event is called every time the method is called.

Similar to the XControl Properties, each XControl method is represented by one or more VIs within the XControl library.


9/129/12 www.ni.c

1.

2.

3.

4.

5.

6.

7.

Complete the following steps to add a method to the XControl library:

Right-click the XControl library and select from the shortcut menu to add a new method to the XControl library.NewMethod

LabVIEW creates a new method in the XControl library

Double-click the method in the XControl library to add the controls and indicators that represent the parameters of the method.

The method VI contains a d isplay state control and display state, container state and error indicators. It is very important not to delete any of these controls or indicators because LabVIEW

uses them to pass in essential information.

Add controls or indicators to represent the parameters of the method. Parameters can be input, output, or input/output parameters. Each control or indicator that you add to the VI can be p

of only one parameter. LabVIEW uses the name of the control or indicator as the name of the parameter.

If the parameter is an input/output parameter, you must use a control/indicator pair to represent the parameter. The control/indicator pair must be of the same data type.

Wire the controls or indicators to the connector pane. Right-click the method and select from the shortcut menu to display the Configure Method dialog box. Use this diConfigure Method

box to configure the parameters you added to the method.

The Simple Dual Mode Thermometer example has one custom method that converts temperature in Celsius to Fahrenheit. The method has one input for temperature in Celsius and returns the

temperature in Fahrenheit as output.

XControl Run-Time Shortcut Menus

You can customize an XControls run-time shortcut menu. To do this, you use the event for building the custom popup menu.Register for Shortcut Menu Activation

In the DMT example, LabVIEW calls the Facade VI with the Shortcut Menu Activation? Event when the user right clicks on the Slide, Thermometer or Fahrenheit controls.


1. Inserts a new separator Shortcut menu item.

2. Inserts a new Shortcut menu item to display the temperature.


10/1210/12 www.ni.c

LabVIEW calls the Facade VI with when the user right clicks on the Slide, Thermometer or Fahrenheit controls and selects a user item.Shortcut Menu Selection (User) Event


1. Checks to see which user item was selected

2. If "DISPLAY_TEMPERATURE" is selected, put up a dialog displaying temperatures in both scales - Celsius and Fahrenheit.

XControl Sizing:

XControls can be sized in two ways:

Enable front panel scaling on the Faade VI. This will automatically grow the controls on the Faade VI when the XControl is resized.

Register for Panel Resize event on the Faade VI. Size the controls programmatically by setting size properties in response to the event

Debugging an XControl:

An XControl runs in private context. This means that the XControl cannot be debugged when in use by another block diagram.

The faade VI can be debugged using the following steps:

Right click the XControl instance

Select Advanced>>Show Diagram

The property, method and ability VIs can be debugged using breakpoints.

When an XControl is in use, all its components are reserved and cannot be edited. To edit the XControl in use, right click the library and select the Unlock Library for Editing. This will cause all V

using that XControl to break. After editing, once again right click the library and select Apply Changes to Instances. The advantage of this is that all instances o f that XControl will be updated.

Running the XControl


11/1211/12 www.ni.c

The XControl can be placed on a VI either within the same LabVIEW project or on any VI that may need to use it.

In the DMT example, the uses the XControl. It reflects changes made to the DMT control on the DMT indicator using all the abilities, properties andRun Dual Mode Thermometer XControl.vi

methods discussed above.

Legal

This tutorial (this "tutorial") was developed by National Instruments ("NI"). Although technical support of this tutorial may be made available by National Instruments, the content in this tutorial ma

not be completely tested and verified, and NI does not guarantee its quality in any way or that NI will continue to support this content with each new revision of related products and drivers. THIS

TUTORIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND AND SUBJECT TO CERTAIN RESTRICTIONS AS MORE SPECIFICALLY SET FORTH IN NI.COM'S TERMS OF US

).http://ni.com/legal/termsofuse/unitedstates/us/
http://ni.com/legal/termsofuse/unitedstates/us/http://ni.com/legal/termsofuse/unitedstates/us/


12/12

NI Tutorial 3198

Documents

Transcript of NI Tutorial 3198