Jump to content

XControl: Difference between revisions

From LabVIEW Wiki
← Older edit
VisualWikitext
m →Abilities: bulleted list
mNo edit summary
 
(29 intermediate revisions by 6 users not shown)
Line 1: Line 1:
__NOTOC__
{{TOCright}}'''XControls''' were first introduced in [[LabVIEW 8]] and enhance the power of front panel objects. An XControl is a front panel object with a dedicated UI logic code linked and encapsulated in the XControl in order to react to user events on the controls it contains. An XControl consists of several parts, managed in a [[XCTL File Extension |''.xctl'']] file. The ''.xctl'' file is a XML file like similar to [[LabVIEW Project]] or [[LabVIEW Project Library]] files.  
{| align="right" border="0"
|__TOC__
|-
|}
==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.
Other parts of the XControl are called:
*[[XControl:Properties|Properties]]
*[[XControl:Abilities|Abilities]]
*[[XControl:Methods|Methods]]


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
{| class="wikitable"
|+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.
[[Image:XControl.xctl_Facade_Empty.png|center|thumb|600px|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.


{| class="wikitable"
== Limitations ==
|+ Facade Ability data in- and outputs
An XControl functions like a subpanel in the hosting VI. [[Subpanel]]s (and therefore XControls) ''can not'' be placed inside an array. Note that you ''can'' define your XControl data as an array of any LabVIEW data type, and you ''can'' use array controls in the facade vi.  
|-
! 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.


{| class="wikitable"
Using LabVIEW native objects (.lvclass files) inside the state control of an XControl tends to crash LabVIEW for versions less than 8.5.1 when the XControl is used in a different application instance.
|+ Special Facade Ability VI events
|-
! Event Name
! Function
! Called if
|-
| Data Changed
| 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 Changed
| 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===
Also, XControls have limitations when running in VIs that are part of a [[LabVIEW Project Library]] (or [[Packed Project Library|Packed Project Library (PPL)]]), or a [[LabVIEW Class]]. This makes it difficult to use in a large application using [[Actor Framework]] or plugin architectures using [[Packed Project Library|PPLs]]. See more in the [[QControl|QControls]] article.
To resize a XControl from within the XControl the following code can be used:
[[Image:XControl.Bounds.PNG]]


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.
== Tricks ==
*If you require a variable number of runtime instances of your XControl, Jarrod Slocum of [[National Instruments]] has created an example [http://community.ni.com/examples/linked-object-list-in-labview-8-0-using-xcontrols Linked Object List] based on a Subpanel ''inside'' an XControl.


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.
* If you want to react to dynamic events (or user events) you need them to register at the XControl Facade '''before''' the event happens.
* If Façade is not executing fast enough to keep up with data updates, it causes the updates to queue up. The updates will happen even after the VI stops running. To reduce data updates:
: (Thanks to Ram Kudukoli (of NI R&D) for sharing this with us at the recent CLA Summit)
:* Open the Xcontrol .xctl file in a text editor like Notepad.
:* Add the bolded line shown below:
<Property Name="NI.Lib.Version" Type="Str">1.0.0.0</Property>
<Property Name="NI.XClass.Flags" Type="Int">0</Property>
'''<Property Name="NI.XCtl.OptimizeDataUpdate" Type="Bool">true</Property>
<Property Name="NI.XItem.DeclaredLeakProof" Type="Bool">false</Property>'''
:* Save the .xctl file.
([http://lavag.org/topic/15680-no-update-on-x-control-value-change/page__view__findpost__p__94838 LAVAG source])


[[Category:User Interface]]
== See also ==
*[[QControl|QControls]]
 
[[Category:XControl]]

Latest revision as of 15:58, 9 June 2020

XControls were first introduced in LabVIEW 8 and enhance the power of front panel objects. An XControl is a front panel object with a dedicated UI logic code linked and encapsulated in the XControl in order to react to user events on the controls it contains. An XControl consists of several parts, managed in a .xctl file. The .xctl file is a XML file like similar to LabVIEW Project or LabVIEW Project Library files.

Other parts of the XControl are called:


Limitations

An XControl functions like a subpanel in the hosting VI. Subpanels (and therefore XControls) can not be placed inside an array. Note that you can define your XControl data as an array of any LabVIEW data type, and you can use array controls in the facade vi.

Using LabVIEW native objects (.lvclass files) inside the state control of an XControl tends to crash LabVIEW for versions less than 8.5.1 when the XControl is used in a different application instance.

Also, XControls have limitations when running in VIs that are part of a LabVIEW Project Library (or Packed Project Library (PPL)), or a LabVIEW Class. This makes it difficult to use in a large application using Actor Framework or plugin architectures using PPLs. See more in the QControls article.

Tricks

  • If you require a variable number of runtime instances of your XControl, Jarrod Slocum of National Instruments has created an example Linked Object List based on a Subpanel inside an XControl.
  • If you want to react to dynamic events (or user events) you need them to register at the XControl Facade before the event happens.
  • If Façade is not executing fast enough to keep up with data updates, it causes the updates to queue up. The updates will happen even after the VI stops running. To reduce data updates:
(Thanks to Ram Kudukoli (of NI R&D) for sharing this with us at the recent CLA Summit)
  • Open the Xcontrol .xctl file in a text editor like Notepad.
  • Add the bolded line shown below:
<Property Name="NI.Lib.Version" Type="Str">1.0.0.0</Property>
<Property Name="NI.XClass.Flags" Type="Int">0</Property>
<Property Name="NI.XCtl.OptimizeDataUpdate" Type="Bool">true</Property>
<Property Name="NI.XItem.DeclaredLeakProof" Type="Bool">false</Property>
  • Save the .xctl file.

(LAVAG source)

See also

Retrieved from "https://labviewwiki.org/w/index.php?title=XControl&oldid=28147"