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: "Properties Viewer"Caption
type: Word or phraseThe 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!
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!
StorageLocation
type: Select from the listAutomatic 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 ("Measurement Information").
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!
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 ("Measurement Information").
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 FalseSet 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'
True or False
True may also be read like 'yes' and false like 'no'
StorageKey
type: Undefinedoptional storage key that can be used in different applications, so that applications can share a set of settings.
Mode
type: Select from the listChoose the kind of settings file this operator reads or writes.
Select one of those presets:
ValuesPerAddress
Specified are addresses of any variables in the application of which the values are stored. The resulting file contains lines similar to: $Address.Of.Variable$ = Value of that variable.
If the file is written, the value of each specified address is written right of the '=' sign.
If the file is read, the values right of the '=' sign are copied to the address left of the '=' sign.
IniFile
Specified are contents like in a classical 'ini' file. An ini file contains key-value pairs that are written similar to key = value. The key is any short name (spaces are allowed) and the value is any fixed value or text, or variable.
If the file is written, any variables in the text are replaced with their values.
FreeContent
Specified are free-format content that is stored in a UTF-8 text file. The content may contain any texts and variables.
If the file is written, any variables in the text are replaced with their values.
If the file is read, nothing else happens.
ValuesPerAddress
Specified are addresses of any variables in the application of which the values are stored. The resulting file contains lines similar to: $Address.Of.Variable$ = Value of that variable.
If the file is written, the value of each specified address is written right of the '=' sign.
If the file is read, the values right of the '=' sign are copied to the address left of the '=' sign.
IniFile
Specified are contents like in a classical 'ini' file. An ini file contains key-value pairs that are written similar to key = value. The key is any short name (spaces are allowed) and the value is any fixed value or text, or variable.
If the file is written, any variables in the text are replaced with their values.
FreeContent
Specified are free-format content that is stored in a UTF-8 text file. The content may contain any texts and variables.
If the file is written, any variables in the text are replaced with their values.
If the file is read, nothing else happens.
Encoding
type: Select from the listChoose the text encoding that is used to write and read the settings files.
Select one of those presets:
UTF8
UTF-8 is the default text encoding of the Application Settings operator. Use this encoding, unless you have a specific reason to use any of the other supported encodings.
The UTF-8 encoding supports all characters of the most common languages world-wide. If a character cannot be encoded by UTF-8, then Polybench cannot display or work with that character.
UTF-8 is compatible with the ASCII-encoding, in a way that a file encoded in ASCII can be interpreted by UTF-8.
UTF16LE
UTF-16 Little Endian is the default Unicode encoding on the Windows operating system; able of encoding most characters in most languages. UTF-16 and UTF-8 have almost the same capability of encoding characters, but in many cases UTF-8 results in a smaller file. In Chinese, Japanese, Hindi, or related languages, UTF-16 may result in smaller files than when encoded in UTF-8.
UTF16BE
UTF-16 Big Endian is the default Unicode encoding according to the RFC-2781 standard. Use this encoding only in very specific circumstances.
ASCII
ASCII is an old, 7-bit character encoding, able of efficiently encoding English texts. For most other languages, UTF-8 is recommended. Please note that many characters in non-English texts cannot be written to an ASCII-encoded file.
UTF32
UTF-32 is a 32-bit character encoding, able of encoding most characters in most languages world-wide. For most languages, UTF-8 or UTF-16 are more efficient in file size. Use this encoding only in very specific circumstances.
UTF8
UTF-8 is the default text encoding of the Application Settings operator. Use this encoding, unless you have a specific reason to use any of the other supported encodings.
The UTF-8 encoding supports all characters of the most common languages world-wide. If a character cannot be encoded by UTF-8, then Polybench cannot display or work with that character.
UTF-8 is compatible with the ASCII-encoding, in a way that a file encoded in ASCII can be interpreted by UTF-8.
UTF16LE
UTF-16 Little Endian is the default Unicode encoding on the Windows operating system; able of encoding most characters in most languages. UTF-16 and UTF-8 have almost the same capability of encoding characters, but in many cases UTF-8 results in a smaller file. In Chinese, Japanese, Hindi, or related languages, UTF-16 may result in smaller files than when encoded in UTF-8.
UTF16BE
UTF-16 Big Endian is the default Unicode encoding according to the RFC-2781 standard. Use this encoding only in very specific circumstances.
ASCII
ASCII is an old, 7-bit character encoding, able of efficiently encoding English texts. For most other languages, UTF-8 is recommended. Please note that many characters in non-English texts cannot be written to an ASCII-encoded file.
UTF32
UTF-32 is a 32-bit character encoding, able of encoding most characters in most languages world-wide. For most languages, UTF-8 or UTF-16 are more efficient in file size. Use this encoding only in very specific circumstances.
The text encoding determines how characters in the settings file are binary written in or read from the file.
Which encoding should be used is given by your language, because not all characters of your language may be representable by each encoding.
The most common encoding that is used on the internet, is UTF-8. Therefore, UTF_8 is the default setting in the Application Settings operator.
Which encoding should be used is given by your language, because not all characters of your language may be representable by each encoding.
The most common encoding that is used on the internet, is UTF-8. Therefore, UTF_8 is the default setting in the Application Settings operator.
Documentation
type: See descriptionOptional documentation of this object. If this object is an operator, the Documentation text is displayed below the operator symbol.
Special dialog to change properties of this object: Contents
Variable Parameters
Find more information about Variable Parameters here: "Variable Parameters"FileContents
type: See descriptionContents of the file that was last loaded using the Load function.
If this variable has not been used after 30 seconds after the file was loaded, then this variable is deleted again to save memory.
Functions
Find more information about Functions here: "Operator Functions"Save
Call to save the settings immediatelyParameter:
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'.
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 settingsParameter:
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'.
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'.
Append
Call to append settings or text to a settings file.Parameter:
Specify the name of the settings, without extension (or leave empty), then write > (greater than character) and then the text to append. Only text that appears after the '>' will be appended. Example: 'MyFile > this text is appended'
Specify the name of the settings, without extension (or leave empty), then write > (greater than character) and then the text to append. Only text that appears after the '>' will be appended. Example: 'MyFile > this text is appended'
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' (the caption of the Application Settings operator).
Although .ini is a default settings file extension, you may also use other extensions.
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 ("Measurement Information").
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 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