XControl

Introduction

XControls are introduced in LabVIEW 8.0 and enhance the power of front panel objects in great ways.

Essentially an XControl is a front panel object with dedicated code linked in to react on certain user events.

An XControl exists of several parts, managed in a .xctl file. The .xctl file is a XML-file like the project-file. Other parts of the XControl are abilities.

Abilities

Abilities are LabVIEW files (mainly controls and VIs) that are needed of the XControl, and form the heart of the XControl

XControl abilities

Ability	Function	Called if/when	LabVIEW file type	Optional?
Init	To initialize memory, convert from previous version, load data from a previous session	The first time an Xcontrol is added to a VI an Xcontrol is upgraded a VI with an XControl is opened	Instrument (VI)	No
Data	Interface to the calling VI	NA	Control (ctl)	No
State	Contains local data for the XControl	NA	Control (ctl)	No
Facade	Contains the code running when the XControl is active	Every time an event inside the Facade VI is triggered	Instrument (VI)	No
Uninit	To close items allocated in Init	The XControl is unloaded from memory	Instrument (VI)	Yes
Convert state for save	Change the data that is saved inside a VI	The VI containing the XControl is saved	Instrument (VI)	Yes

Facade Ability VI

The Facade VI is the running heart and display of the XControl. It decides on which events applied to the XControl should be reacted to in which ways. The front panel of the Facade VI is shown in the owning VI as the control look.

Example XControl Facade VI showing the Timeout frame

Facade Ability VI Data

The Facade Ability VI has several data in- and outputs to fit in the XControl framework. Changing the names (labels) of these data in- and outputs will break the XControl.

Facade Ability data in- and outputs

Name	Description	Type
Data In	Returns last saved value of 'Data Out'	Control
Data Out	Outputs the value for use inside the containing VI	Indicator
Display State In	Holds internal data of the XControl	Control
Display State Out	Placeholder for internal data	Indicator
Container State	Holds information about the XControl for use inside the XControl	Control
Container State.Indicator?	Returns True if the XControl is an indicator	NA
Container State.Runmode?	Returns True if the VI containing the XControl is in Runmode.	NA
Container State.Refnum	Reference to the control representing the XControl	NA
Action	Contains commands for LabVIEW about the current XControl event session	Indicator
Action.DataChanged?	If this boolean is true LabVIEW will save te 'Data Out' value, if false the value will revert to 'Data In'	NA
Action.StateChanged?	If this boolean is true LabVIEW will save te 'Display State Out' value, if false the value will revert to 'Display State In'	NA
Action.Action Name	Can be used to track changes made by XControls for undo for instance	NA

Facade Ability VI Events

The Facade VI contains an event structure inside a while loop. To be useable inside the XControl framework the VI has to be terminated after each event. To enforce this LabVIEW's template XControl has a timeout of 0 ms which finishes the while loop, the XControl can be ended in any of the event cases.

Special Facade Ability VI events

Event Name	Function	Called if
Data Change	To keep the representation of the XControl up to date with the data of the XControl	On load of the XControl, if a new value to the terminal/local variable/'value' property is written or the 'value (sgl)' property is called
Display State Change	To communicate between XControl parts	The XControl is loaded into memory, a custom property or method is used
Direction Change	To inform the XControl of the 'gender' of it's terminal	The terminal of the XControl is converted from Control to indicator and visa versa. On initial drop of the XControl, or load into memory
Exec State Change	To inform the XControl of the mode of it's owning VI	If the owning VI is started or stopped. If the owning VI is loaded into memory

Facade VI tricks

• To resize an XControl from within the XControl the following code must be used:

• To gain control over the owning VI the property Container State.Refnum:Owning VI can be used, for instance to change the current cursor icon of the owning VI.

• Make a difference between run-time and edit-time. This allows for setting properties via a context menu for the developer while the user can't access these settings.

• Remember to update the Action control to store changes in the Data or State value

Init Ability VI

The Init ability is used to initialize an instance/run of an XControl. It allows for converting from an older version of the XControl to maintain data-persistance. For this function the version numbering of the XControl is used. Besides upgrades it gives the option to have seperate default values for controls and indicators.

Init VI tricks

• Unfortunately there is no way to detect why the Init VI was called (drop or load from disk). One way can be using a special flag-value inside the State value as shown by Stephen Mercer of National Instruments in his rolling LED display where this is used to force the drop of an indicator instead of the standard control.
• Since the Display state event is triggered by the Init VI this can be used for messaging.

State Ability control

The State ability is a cluster for internal data of the XControl, it is accesible from within every part of the XControl so it is the prefered mechanism for messaging between elements of the XControl.

Data Ability control

The Data ability determines the datatype of the terminal of the XControl, it can be used from the owning VI to write/read data from the XControl

Uninit Ability VI

This VI is called if the XControl is removed from the front panel or if the front panel of the owning VI is removed from memory. It can be used for closing of references, files and large memory allocations. This ability is called last for any instance of an XControl

Convert state for save Ability VI

This ability is called when the VI owning the XControl is saved to disk. It can be used to limit the size of the owning VI on disk, the variant output of this VI will be read back later by the Init ability.

Properties

Properties can be accessed from the owning VI and use VI server to communicate with the XControl. During creation of an property their is the option to make the property write or read only or write/read. After creation default VIs are created with a specific connector pane layout.

If a property read or write has taken place the Display State Changed Event is called, allowing the use of a messaging system.

Methods

Methods function alike Properties but can pass multiple (or none) parameters between the XControl State and the owning VI.