Reference Design Content
The Options Dialog Framework (ODF) is a reference design for adding an interface for managing options and settings within a LabVIEW-built application. It is based on the framework used by the options dialog in the LabVIEW development environment.
Please provide any comments, feedback, suggestions and questions in the comments below.
For the purpose of this discussion we differentiate between options/settings/preferences and (system) configuration.
Options/settings/preferences - parameters that configure the operation of an application such as where files are stored, how data is displayed, etc. The specific set of options is fixed by the application developer and you generally do not have a variable number of settings. The LabVIEW options dialog is a good example of this type of information.
System configuration - a description of the physical and logical setup and architecture of a system and the associated application. This typically includes information about HW targets, channels, modules, and configuration of these objects within the system. System configurations are often hierarchical in nature (tree object) and support adding many instances of different object types.
This document and the associated examples do not address system configuration. For a possible system configuration solution take a look at the xCE (Generic Configuration Editor Reference Example, http://zone.ni.com/devzone/cda/epd/p/id/6249). This reference design and framework uses LVOOP to define configuration objects and lets developers design their own configuration editor by inheriting from the provided bases classes.
Application Settings Architecture
Managing settings within an application typically consists of three components.
- Settings Storage - a method to store and persist application settings values between instances of running the application. This is typically implemented using a database or a file (INI, XML, etc.) on the local computer.
- Active Settings - a method to load and hold current settings values (current value table) in the application and access these values from the application logic. In LabVIEW this is typically implemented using one of a number of common methods (global, FGV, cluster in a shift register, shared variables, etc.)
- Settings Dialog - a user interface to directly view and update specific application settings. Some settings may be updated interactively while working with the application, while other settings are updated explicitly using the settings/options dialog. Not all application settings are necessarily exposed in the settings dialog.
Operations dealing with Application Settings include the following:
- Start of Application - settings are loaded from storage (Settings Storage) into active memory (Active Settings)
- Application Logic - the application code reads and writes settings in active memory (Active Settings) as necessary
- Settings Dialog - when the settings dialog is opened, the dialog pulls settings values from active memory into the UI of the dialog. When the dialog is closed the new values in the dialog UI are written back to active memory (Active Settings).
- Close of Application - settings values from Active Settings are saved to Settings Storage when the application is closed. This Save routine may also be called at other times in the application such as when the setting dialog is closed.
To implement this architecture we need the three basic settings components with interfaces that provide the necessary control to the application and other components. The following sections will discuss each of these three components. It should be noted that each component can be implement using a number of different methods and LabVIEW features and these implementations can be mixed and matched depending on the needs and preferences of the application and developer.
Configuration of Settings
As part of developing an application the developer needs to decide and define the list of settings (name, data type, etc.) used by the application. To simplify the process of managing settings throughout an application the goal is to define the list of settings in one location and have all other components dealing with settings use this common list. The following discussion and examples will attempt to provide a solution that follows this high-priority design criteria.
Active Settings
The Active Settings component is the core piece of implementing settings management in an application as it interfaces to the other three related components of the application (settings storage, settings dialog, application logic). It also makes sense that this component would be used to define the list of settings in an application.
To simplify using settings the Active Settings should provide access to settings values in a number of different ways:
- Access by Name - read and write current values in Active Settings by name
- Access by Node - read and write settings using a static node (similar to a local variable node) - this feature allows for
- List of Settings - return a list of all available settings including name and data type
- Get All Settings - return the complete set of settings including values. This method is typically used to persist the settings value to Settings Storage.
Implementation
There are quite a few different implementations of an Active Settings component in use in the LabVIEW community today, each offering different advantages and drawbacks, partially based on the personal preference of individual developers. These implementations include:
- Global variable
- Individual settings
- All settings in a cluster
- Functional Global Variable (FGV)
- LVOOP Class
- Shift Register
- Settings cluster
- Shared Variables
For the time being we will not make a specific recommendation or example to implement Active Settings.
Settings Storage
Storing settings values between instances of running an application is the other key component of managing settings in your application. Like for the Active Settings, there are a number of common LabVIEW implementations for settings storage. These include:
- Configuration file (INI)
- XML File
- Binary file
- Database
The config or INI file is a common solution as LabVIEW includes a good native solution for accessing these files.
XML files are popular for implementations that store active settings in a cluster, because it allows you to store the cluster as a whole in XML. Several Cluster to XML solutions exist in LabVIEW and the community.
Binary files can be used to quickly store any LabVIEW data structure to file, but are not suitable if you need to access the settings file outside of the application (non human readable) and does not handle additions and changes to settings well.
An ideal solution for Active Settings and Settings Storage will allow you to quickly and easily save all settings values to storage and retrieve them in a single operation without needing to customize this routine for you specific list of settings.
For the time being we will not make a specific recommendation or example to implement Settings Storage but will use INI files in our examples.
Settings Dialog
A settings or options dialog allows the user of the application to interactively modify specific settings exposed by the developers. As an example the LabVIEW options dialog provides access to a wide range of settings that affect the looks and behavior of the LabVIEW development environment.
Reference Example
To develop an options dialog for your own application can develop the dialog from scratch or you can use the same dialog framework used by the LabVIEW options dialog. The example included with this document provides an interface to use the same code as the LabVIEW options dialog.
The options dialog is customized by building a number of individual options pages. When the options dialog is opened you provide a list of options pages VI paths to the dialog VI which will load and display the pages dynamically.
Each options page is implemented in one VI and should be created from the VI template provided with the example. Each options page contains front panel controls to allow the user to set values for a list of related settings in your application. Customizing the options page template is documented in the diagram of the template VI. The options page VI integrates with the options dialog using a number of events and is displayed in a subpanel of the main dialog VI.
One of the important aspects of building and customizing your options pages is the load and save process of the settings values. In the template and example provide the settings values are loaded from and save to a config INI file directly, rather than loading them from active memory in a running application. This is different than the discussion and diagram above. You can adjust this code to load and save settings values from file or active memory.
The options page VIs are loaded and run the first time the particular page is shown in the options dialog. This means that VIs are loaded sequentially based on user interaction. When the dialog is closed, however, all of the running options page VIs are stopped at the same time based on a user event from the options dialog. This means that their respective Save routines are likely running simultaneously. This is important to remember so that you don't try to access a shared resources such as a file with multiple File Open calls, generating access errors. The example solves this conflict by using one File Save Load VI that reads and writes the config file for all options pages. This non-reentrant VI can only be called by one page at a time and the LabVIEW scheduler thus automatically manages sequential accesses to the file.
Note: Currently the options dialog framework VI is password protected while we refactor the code to make it user accessible. Stay tuned for an update of this reference example that includes the open source options dialog. In addition we are planning on adding tighter integration between the Settings Dialog, Active Settings, and Settings storage components, to have one fully integrated application settings management solution.
Building an EXE
When build an EXE using the ODF VIs, there are a couple of considerations you need to make.
- Since the option pages are called dynamically by ODF, you need to include these VIs in your built EXE (Always Include) or, if you prefer to keep the option pages outside of the EXE, you need to add them to the distribution of the EXE and associated files.
- Based on the location of the option page VIs in or with your EXE, the VI calling the ODF dialog needs to determine the proper path for the option page VIs. In some cases the path will be different whether you run in the development environment or as an EXE and your code needs to handle this difference. The same is true for the path of the configuration INI file which is determined and used in each of the option page VIs. Most likely this needs to be handled differently in the development environment versus a built application. The attached example (ODF EXE Example.zip) shows how to hande this difference.
- For any of your option page VIs, you need to include the front panel in the build options for the EXE.
See ODF EXE Example.zip for an example of a project using ODF and building an EXE. The top level VI and option page VIs contain the code that determines the dynamic paths of the option page VIs and configuration file.
Note: This example is using the options page VI template from ODF version 0.5 and will not work with earlier versions of ODF.
Please provide any comments, feedback, suggestions and questions in the comments below.
References
A different Options Dialog reference design based on the Actor Framework - https://decibel.ni.com/content/docs/DOC-32723
Version History
| Version | Date | Notes |
|---|---|---|
| v 1.0.0.0 | August 25, 2010 | Original release as ZIP file only |
| v 0.2.0.2 | August 27, 2010 |
Reverted version number from 1.0 to 0.2
|
| v 0.5.0.1 | January 7, 2015 |
Added new ZIP file saved in LabVIEW 2009
|
| ODF EXE Example.zip | April 7, 2015 | Example project including a Build Spec to create an application executable using ODF. This example requires ODF version 0.5.0.1 or later. |
Great work guys - thanks for making this accessible. It replaces an internal reuse package we have, which is a good thing! 
Speaking of which, can I encourage you to release it as a VIPM package?
Shaun,
If you want to share your code, I would create a new document in NI Talk (in this group or the general NI Developer Community space) and then add a link here.
crelf,
I'm definitely planning on creating a VI package, but was thinking more about where to put the files in the LV folder structure. For the VI templates it makes sense to put them alongside the existing templates, but I have not tried putting custom templates into that structure so far .
If you have some suggestions where to install the different parts of the code (framework VIs, examples, templates) I would love to hear them.
Christian
When my packages include templates, I tend to have them with all the other package VIs, include them in the palette – but I make them merge VIs. This is much easier and more intuitive (IMHO) than putting them in the templates folder (which, again IMHO, no one uses anyway). Either that or go with jgcode’s idea of having them accessible through a wizard in the tools menu, but I’d start with the merge VIs in the palette (I put mine under a “Preference Page Templates” sub-palette).
Chris, David,
The challenge in this case is that the VI temrplate is not just code, but also UI components/colors and VI properties. Using the Merge VI option does not include these features when placing the code on a blank VI. Given the nature of this reference design I think this is too much of a limitation. I do like the idea of an utility in the Tools menu to manage/create options pages.
True – actually, merge VIs and front panel stuff don’t work well – I’m sure there’s a bug there (eg: make a VI with a few controls and decorations, then merge it = the controls vs decorations are offset). I’m sure I’ve reported it before, but I can’t find the CAR right now…
crelf wrote:
I’m sure I’ve reported it before, but I can’t find the CAR right now…
One CAR is #39212 (but it's Jim's not yours) as per this thread on ni.com - for when objects dropped are repositioned.
As ChristianL mentioned - Merge VIs do not include VI Props etc...
The other show stopper is the fact that the Template in this case contains other Templates (as subVIs etc...).
Using Merge VIs will drop a copy of the called Template on the BD e.g. it will not instantiate a new e.g. subVI.
This is one of the issues I have transitioning Templates to the palettes - I don't know if it is possible to change this behaviour?
It is one of the Ideas I have, that would be cool for NI to implement, and probably worth I add to the Idea Exchange to get others feedback.
Anyways the "New..." Dialog is not that bad 
It is pretty slow, but I thats the most logic spot for all my Templates that fall into the above category - and I use it all the time.
If the dialog was cache'd between calls (with a Refresh Button and an IN for programmatic access) that would be better IMHO (another Idea).
Additionally another Idea is to allow Templates in the Tools Menu
At the moment Templates are ignored.
A fast way to access Templates would be just to select them from the Tools menu and a new instance would be created?
Thoughts?
Jonathon Green wrote:
crelf wrote:
I’m sure I’ve reported it before, but I can’t find the CAR right now…
One CAR is #39212 (but it's Jim's not yours) as per this thread on ni.com - for when objects dropped are repositioned.
As ChristianL mentioned - Merge VIs do not include VI Props etc...
Ah - that's why I couldn't find it. Actually, it is mine (I discovered the issue (see http://forums.jkisoft.com/index.php?showtopic=950) and taked to Jim about it as it was screwing up VIs I had in a package I was building.
Jonathon Green wrote:
Anyways the "New..." Dialog is not that bad
Sure, but you're missing my point - if all the interfaces to a reuse package are in the pallete, then that's where I'm going to look for them. Having one component in the "New..." dialog and everything else in the palette isn't intuative IMO. If I was going to do it that way, I'd need to put a dummy VI in the palette with text on it's icon that says something like "The template you're looking for is in the New dialog you idiot" and I'd prefer my software not to call me an idiot explicitly (it does it implicitly enough thank you very much).
re Creating VI from Templates in the Tools menu
I like that idea and I think we can create something pretty quick there. At least a simple VI that provides a small dialog with a list of templates available in the Tools menu/Project folder. You can then create a VI from template with two clicks instead of going through the New ... dialog.
re nrp's question on the Help button
That was a plain oversight on my part. I guess my brain filters out the word Help on UIs. The current design calls the main LV help (*.chm file) if no options pages are open. This should only happen if there is an error loading a page or the help info on the individual option page is missing (see next sentences). I'm planning on adding an input to the calling VI that allows you to specify what help you want in that case. Individual options pages specify their help file using the Help Tag and Help Path properties in the VI Properties>>Documentation for each individual VI. Again these are links to help files. You can edit these right now to link to your own help file. I will add this in the documentation of the template.
What other options would you like to see for linking to Help. i.e. is a help file (*.chm) a good option or would you also like to be able to open other types of documentation (HTML in a browser, text file, ???). Please provide feedback and suggestions.
re Template distribution: Before we hijack this thread much more, I've created a thread over here to discuss: http://lavag.org/topic/12982-where-do-you-put-the-templates-in-your-distributions
Unfortunately there are functions used in the published Options Dialog Framework which do not exist in LV 8.6 or earlier, so it will not properly save back to that version.
Jonathon,
David is correct that NI's General Purpose Software License Agreement (as well as a new set of Sample Code License Terms which will be puslished soon and will govern this type of content) do not permit for you to republish/redistribute source code content. I will contact you directly to discuss your project and figure out how we can let you use and publish the necessary code sections.
In general if anyone is interested in modifying and republishing source code from examples, reference designs, etc. that is available on ni.com, they should contact their NI representative to discuss their project and receive the necessary permission. Of course you can always use the code NI publishes as a guide for your own development and publish your own creations under the license terms of your own choosing.
Christian L
Systems Engineering Manager
National Instruments
Jonathon Green wrote:
Just to clarify a question that came up from the above, in plain English can I use code on NI websites including packages published for free on the LabVIEW Tools Network (assuming they under this license - on mob can't check right now) in commercial builds (.exe's)?
Yes, using this code in compiled EXEs or other object files (e.g. DLLs) and distributing those files is covered and permitted by the license terms.
Excellent Work! But I can't replace some text prompt or labels on the dialog for localization. At present, we can only custom the "OK" button label.
Here it is:
Below lies the NI option dialog in Chinese.
I have put this into a small application, however it does not seem to want to load the options dialogs correctly in a .exe. In the development environment, it works just fine.
I made sure that the paths are correct, and all the vi's are listed under the Category section and the blue bar updates with the proper text. But where the options are supposed to be listed, it just says "Cannot display selected Category page"
No errors pop-up, so I am not sure what the issue is.
I modified the build to include the vis in my build, but still the same results. I am listing all the files in the folder and loading those that match a certain pattern (see pic). All the pages are the same, just the vi title is different. My intent is to be able to add option pages for future test fixtures without having to re-build the application (just create a new VI, and change the filename and title).
I just posted an updated version of the VIs in a ZIP file (v 0.5.0.1). After some testing and feedback from the community I will also build and post a VIP file.
I added an example using ODF and building an EXE that shows how to use the Always Include build option to embed the option page VIs in the EXE. The top level VI dynamically determines the paths of the options dialog VIs (inside the EXE) and passes them to the ODF dialog.
