Polybench® Reference
Allows the user to define addresses of values that should be stored to disk before exiting and reloaded after opening an application.

Application Settings

Overview

Allows to store values on specified addresses in your project. In a list you specify addresses that are linked to SET_PARAMETER actions in your project.

On a Save function call, this operator reads the values from those addresses and saves them to disk. On a Load function call, the settings are loaded and for all specified addresses a SET_PARAMETER action is called to write the values back.

If you don't specify a name in the Save and Load functions, then its file name is equal to the Caption of this operator by default.

Operator ports

This operator does not have inputs nor outputs. It cannot be connected to anything. You are free to place it anywhere on a design page.

Properties

Find more information about changing properties here: link

Caption
type: Word or phrase
The name of this object in the project. This name must not contain '.' or '$' characters. This name is used as the default settings file name.

If the Save function is called without a file name, then the Caption is used as file name. Therefore you must take care that if you use mutliple Application Settings operators in your application (which is allowed), that they all have a different Caption, otherwise one will overwrite the settings of the other.
Alternatively, you may specify a different file name in the Save (and Load) functions.
Note: you cannot fill in a complete file path here! Only the name of a file, without extension!

Addresses
type: Undefined
addresses of parameters that should persisted as application settings.

Click on the '...' button for this item. An editing box opens, in which you should type or copy addresses of variable parameters in your application.
This editing box is a little primitive (sorry about that). The easiest way to use it is to open the Variable Parameters dialag of any object, and then select the item of which you want to copy the address to the Application Settings. Then press 'Copy'. Then open the properties of the Application Settings and open this editing box. Then paste the address in it on a new line.

StorageLocation
type: Select from the list
Automatic storage location for the settings file.
Select one of those presets:
RoamingUser
Store application settings for the roaming user of the current Windows account. The settings are also available also if the current user logs in into its account on another Windows machine.
This is the default mode, used to save general settings of an application.

AllUsers
Store application settings for all user accounts on the current computer. You may use this as one of three options to save general settings of an application.
LocalUser
Store application settings for the current user only, on the current computer only. You may use this as one of three options to save general settings of an application.
Measurement
Store the settings in the current measurement session. This measurement session is the one the user has selected in the Manager, or the one that is currently being written. See also the Measurement Information operator (link).
Note that if the Manager is not running, the Application Settings operator cannot load or save the settings!

Patient
Store the settings for the current patient. Care has to be taken that multiple applications should use different setting file names if they store settings for a patient, otherwise one application overwrites settings of another.
Note that if the Manager is not running, the Application Settings operator cannot load or save the settings!


Use StorageKey
type: True or False
Set to true to use the StorageKey, so that multiple applications can share these settings.
Select one of those presets:
True or False
True may also be read like 'yes' and false like 'no'


StorageKey
type: Undefined
optional storage key that can be used in different applications, so that applications can share a set of settings.


Documentation
type: See description
Optional documentation of this object.

It is good practice to write in short notes why you have used this object, and why its properties are set the way they are set. If this object is an operator, the Documentation text is displayed below the operator symbol.

Functions

Find more information about Functions here: link

Save
Call to save the settings immediately
Parameter:
Optional: specify the name of a settings file, without extension. Example: 'My Settings'. If nothing specified, then the Caption is used as file name. You may also specify a full path and file name, including '.ini'.

Load
Call to load the settings
Parameter:
Optional: specify the name of a settings file, without extension. Example: 'My Settings'. If nothing specified, then the Caption is used as file name. You may also specify a full path and file name, including '.ini'.

Details

How to use

Put the Application Settings operator somewhere in your project. It does not have any signal connections (it does not have ports).
Open its properties and add addresses of values that you need to be stored as application settings.

Now, in your project you should define when the settings are actually stored. You have to do that yourself, by calling the FUNCTION action Save.
You also have to define yourself when the settings are loaded, by calling the FUNCTION action Load.

If you call the FUNCTION 'Save' or 'Load', then you may optionally specify a name of the file in the 'Value' part of the action. If you don't do that, the file gets the name of the Caption of this Application Settings operator. You may also specify a full path and file name for the settings file, for example:

Action: FUNCTION
Address: $Design.Application Settings
Value: $applicationfolder$\My Settings.ini

The settings are then stored in the folder where the current application is saved, and uses the name 'My Settings.ini'.
In this example, if you would leave Value empty, then the settings file is stored in an automatic and hidden location, and uses the name 'Application Settings'.

Where are the settings stored

It depends which automatic storage location the Application Settings operator should take; see the StorageLocation property.

In case the mode is RoamingUser, the settings are stored for the current roaming user. So the settings will also be there if the same user logs in into a Windows account on another computer.

In case the mode is AllUsers or LocalUser, the settings are stored on the local computer, for either all user accounts, or just the current user account.

In case the mode is Measurement, you can store settings that are specific for one measurement to that measurement. You have to take care that your application uses the correct measurement. Normally the measurement is taken that is currently selected in the Manager, unless your application is writing a new measurement. In that case the settings are read and written to that measurement folder.
To control the start and end of the selection of a new measurement you may want to use the Measurement Information operator (link).

It is also possible to store settings for the current patient. In that case the settings file is located in the folder where all the measurement folders are in (or more specific: the folder where the patient record .XPAT file is in). You have to take care to use a unique settings file name (which is the Caption of this operator), because other applications may also want to store settings on the patient level, and they should not overwrite eachothers settings file. Polybench does not check that!

Possibilities, limitations

It is allowed to have multiple Application Setting operators in one project, but please take care that they all have a different Caption, otherwise settings from one settings operator will overwrite that from another.

If you don't run the Manager, then obviously no measurement session information, or patient information is available. If you use the Measurement or Patient storage locations, then the Application Settings operator cannot save or load settings. The operator will become red and show a warning.

Storage location: advanced

If you choose RoamingUser, AllUsers, or LocalUser, then the settings file is stored in a hidden location. In your user account in Windows, there is a hidden Application Data folder, in which a Polybench folder is created. In the folder a folder is created with the ID of your application. The settings file has the extension .ini.

Contents of the settings file

The settings file has the form of a classical .ini file. The file is stored as readible text (UTF8 encoding); you can open it in any text editor.

On each line in the file an address string is written, followed by an equals-sign ('='), followed by the value on that address inside quotation marks.
Example:

$Design.K1.Value = "1111.000"
$Design.K2.Value = "65.000"
$Design.Channel Name Splitter.ChannelNames.Channel 1 = "K3"
$Design.Channel Name Splitter.ChannelNames.Channel 2 = "K1"
$Design.Channel Name Splitter.ChannelNames.Channel 4 = "Signal"

Examples

Example: Application Settings Demo
Demonstrates the use of the Application Settings operator. The operator saves the settings of three constants, but also that of the current channel list of a Channel Name Splitter. Press Save to save the settings and Load to load them. Of course, the first time you won't have any settings on disk.
Examples\DF0700210_001_Application Settings Demo.xmc

Example: Measurement Settings Demo
Demonstrates how settings can be stored and reloaded for a measurement. You may want to use this feature to save calibration and other settings that belong to one specific measurement.
In the demo the usage is described in more detail.
Examples\DF0700210_002_Measurement_Settings_Demo.xmc

Example: Patient Settings Demo
Demonstrates how settings can be stored and reloaded for the current patient (the patient that is selected in the Manager). The demo shows a list with patient information, just to see which patient is loaded.
It also shows two Input Fields that read and write to two global variables ($Favorite Desert$ and $Nick name$). Those variables are specified in the Application Settings operator, so that their values are stored.
The settings file will be stored in the same folder where the patient record (.XPAT file) is located. Check the settings in the Manager to get the storage location of patients.
Examples\DF0700210_003_Patient_Settings_Demo.xmc