LabVIEW Options Dialog Framework (ODF)

[Christian_L]

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.

1. 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.
2. 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.
3. 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 Added VI package distribution Moved all dialog subVIs from LV resource folder into package Added support to show/hide Help button and specify dialog help file Moved API and framework into LV project library VIs install to ..\user.lib\ODF Added subpalette to User Libraries in Function Palette
v 0.5.0.1	January 7, 2015	Added new ZIP file saved in LabVIEW 2009 Removed all passwords from the ODF VIs Fixed issue that caused a hidden control appear in the dialog after repeatedly running the dialog Removed unused controls in dialog framework VIs and page template (these were not really visible in the previous version) Existing dialog pages should run without changes using the updated framework VIs, but if you create new dialog pages using the templates in this new version, they will not run with the dialog framework VIs from the previous version.
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.