File MIES_Configuration.ipf¶

CONF Import user settings to configure paramters for Ephys experiments

Module brief description

The Configuration module allows to save and load the GUI state of complete windows including its subwindows

The main functions are CONF_SaveWindow and CONF_RestoreWindow. CONF_SaveWindow automatically detects if the current window is a DA_Ephys panel and uses the DA_Ephys GUI state savig configuration settings and saves additional information. CONF_RestoreWindow also detects if the current window is of DA_Ephys type and handles that specific for this case. CONF_RestoreDAEphys can be called directly as well if there is no panel open. It will open a new DA_Ephys panel automatically if no other viable candidate panel was found.

The GUI state is saved in a text file in json format. In the basic structure of the file the main blocks are the windows and subwindows and within are the control blocks. For notebook windows the content of the notebook is saved as plain text and restored as plain text. A bitmask parameter allows to configure which control information is saved. See WindowControlSavingMask Currently supported is Value, Position/Size, Userdata, Disabled state and Type of a control. Not implemented is e.g. Color/Background Color As Value only the V_Value and/or S_Value and/or S_DataFolder is saved. Special control properties for e.g. ListBox like V_SelCol are currently not implemented.

How GUI controls are handled can be controlled through userdata settings of each control. The following userdata settings are supported:

Config_NiceName: sets a human readable name of the control used in the configuration file This name may not be a duplicate of another controls name or ControlArray name. Also suffixing with “ ControlGroup” is not allowed.
Config_GroupPath: Sets a group path in which the control appears in the configuration file. If not set then “Generic” is used. The group path elements can not contain the ‘/’ character. Several levels can be separated by “;”, e.g. “level1;level2;”. In the configuration file the group path elements are suffixed by “ ControlGroup” which identifies them as path compared to actual control names.
Config_DontSave: When set to 1 the control is ignored on saving the window.
Config_DontRestore: When set to 1 the control is ignored on restoring the window.
Config_PushButtonOnRestore: Only valid with Button controls. When the button is restored a button press is issued.
Config_RestorePriority: Sets a double precision number that defines the order in which controls get restored. Lower numbers correspond to earlier restore. If not set a priority of Inf is used. If multiple controls have the same priority the order of restore is not defined.
Config_RadioCouplingFunc: A function name of a function that returns a text wave with lists of coupled CheckBoxes (aka RadioButtons). It is assumed that only one CheckBox of the group is in enabled state at the same time. See DAP_GetRadioButtonCoupling for example.
ControlArray: Stores a name of a group of controls. All controls with the same ControlArray name are saved as group with that name in the configuration file. ControlArrays save only values and nothing is saved if the configured WindowControlSavingMask does not include values.
ControlArrayIndex: Only valid if also ControlArray is set. Stores the index number of the control in its ControlArray. All member of the same ControlArray must have different indices. Currently not more than 100 controls are allowed for each ControlArray.

The function WindowtoJSON allows to give optional a list of control types that should be excluded.

If the type of the control was saved, it is checked against the GUI controls type on restore.

CheckBoxes are saved with true/false values.

For the DA_Ephys panel: The function CONF_DefaultSettings sets default values for parameters not present in the GUI.

Special mask flags:

EXPCONFIG_SAVE_ONLY_RELEVANT: Saves only most relevant value data of a control. It is configured in EXPCONFIG_GUI_PREFERRED
EXPCONFIG_SAVE_POPUPMENU_AS_STRING_ONLY: Saves value for PopupMenu only as string
EXPCONFIG_SAVE_POPUPMENU_AS_INDEX_ONLY: Saves value for PopupMenu only as index value
EXPCONFIG_MINIMIZE_ON_RESTORE: Minimize window while restoring it.
EXPCONFIG_SAVE_BUTTONS_ONLY_PRESSED: Saves Buttons only when its userdata Config_PushButtonOnRestore is “1”

Handling of window names on restore: The currently selected windows main window is used as reference. The main window name in the configuration file is internally replaced with the current main window. This allows to save from “DataBrowser” and load to “DataBrowser2”.

Handling of errors in input data: If input data is of unexpected format an ASSERTion or RTE is issued. The wrapping function converts the RTE to an ASSERT. The panel restore is aborted and the panel stays in its state. It gets unhided.

Default configuration for generic windows: By default only the Value property is saved and controls from EXPCONFIG_EXCLUDE_CTRLTYPES excluded.

Default configuration for DA_Ephys panel:

By default only the Value property is saved
Controls from DAEPHYS_EXCLUDE_CTRLTYPES are excluded.
The window is minimized while restoring
PopupMenu values are saved as string only
Buttons are only saved if its userdata Config_PushButtonOnRestore is “1”
Only most relevant data of a control is saved.

*_rig.json configuration files store settings that are specific to a rig. When restoring a DAEphys panel the settings from the rig file are joined with the settings in the DAEphys configuration file. Having entries for the same setting in both files is invalid and an assertion will be thrown.

Saving a DAEphys panel that was originally restored from a configuration file:

entries from the “Common configuration data” block are updated with the values from the previous configuration, if they already existed. New entries are set at default values.
entries defined in an associated rig file are removed from the DAEphys panel configuration because they would appear in both files
the previously used rig file is copied to the new location
By default for both files (DAEphys configuration and rig file) new file names are generated. If the new files already exist a save dialog is opened to allow the user to modify the path/name.

Unnamed Group

static const double CONF_AUTO_LOADER_GLOBAL = 0x0¶: Parameters for CONF_GetSettingsPath()

static const double CONF_AUTO_LOADER_USER = 0x1¶

Functions

static variable CONF_DefaultSettings()¶

Creates a json with default experiment configuration block.

Returns:: json with default experiment configuration

variable CONF_OpenConfigInNotebook()¶

Open all configuration files in plain text notebooks.

Existing notebooks with the files are brought to the front.

static wave CONF_GetConfigFiles(string customIPath = defaultValue)¶: Return a text wave with absolute paths to the JSON configuration files.

variable CONF_AutoLoader(string customIPath = defaultValue)¶: Automatically loads all *.json files from MIES Settings folder and opens and restores the corresponding windows Files are restored in case-insensitive alphanumeric order. Associated *_rig.json files are taken into account.

static string CONF_GetSettingsPath(variable type)¶

Returns a symbolic path to the settings folder.

Parameters:: type – One of CONF_AUTO_LOADER_GLOBAL or CONF_AUTO_LOADER_USER
Returns:: name of an igor symbolic path to the settings folder

variable CONF_SaveWindow(string fName)¶

Saves the GUI state of a window and all of its subwindows to a configuration file.

Parameters:: fName – file name of configuration file to save configuration

variable CONF_RestoreWindow(string fName, string rigFile = defaultValue)¶

Restores the GUI state of window and all of its subwindows from a configuration file. If the configuration file contains a panel type string then a new window of that type is opened and restored.

Parameters:

fName – file name of configuration file to read configuration
rigFile – [optional, default = “”] name of secondary rig configuration file with complementary data. This parameter is valid when loading for a DA_Ephys panel

static variable CONF_SaveDAEphys(string fName)¶

Saves the GUI state of a DA_Ephys panel to a configuration file.

Parameters:: fName – file name of configuration file to store DA_Ephys configuration

variable CONF_PrimeDeviceLists(string device)¶

string CONF_RestoreDAEphys(variable jsonID, string fullFilePath, variable middleOfExperiment = defaultValue, variable forceNewPanel = defaultValue)¶

Restores the GUI state of a DA_Ephys panel from a configuration file.

Parameters:

jsonID – json ID of json object to restore DA_Ephys panel from
fullFilePath – full file path of the file where the json object was parsed from
middleOfExperiment – [optional, default = 0] Allows MIES config in the middle of experiment. Instead of setting MCC parameters they are pulled from actively recording MCCs to configure MIES]
forceNewPanel – [optional, default = 0] When set opens always a fresh DA_Ephys panel, otherwise follows this priority order:
- Reuses locked DA_Ephys panel with same device as saved in configuration
- Uses open unlocked DA_Ephys panel
- Opens new DA_Ephys panel

Returns:

name of the created DAEphys panel

static variable CONF_AddConfigFileUserData(string win, string fullFilePath, string rigFile)¶: Add the config file paths and SHA-256 hashes to the panel as user data.

static variable CONF_ParseJSON(string str)¶

Parses a json formatted string to a json object. This function shows a helpful error message if the parse fails.

Parameters:: str – [in] string in json format
Returns:: jsonID of the json object

static string CONF_GetDAEphysActiveHeadstages(variable jsonID)¶

Retrieves list of active headstages saved in a DA_Ephys configuration file.

Parameters:: jsonID – ID of existing json
Returns:: List of active head stages

static variable CONF_RequireConfigBlockExists(variable jsonID)¶

Checks if EXPCONFIG_RESERVED_DATABLOCK exists in json; ASSERTion is thrown if not found.

Parameters:: jsonID – ID of existing json

static string CONF_GetStringFromSettings(variable jsonID, string keyName)¶

Retrieves a string value from a setting.

Parameters:

jsonID – ID of existing json
keyName – key name of setting

Returns:

string from member with keyname in the EXPCONFIG_RESERVED_DATABLOCK

static variable CONF_GetVariableFromSettings(variable jsonID, string keyName, variable defaultValue = defaultValue)¶

Retrieves a variable/boolean/null value from a saved control note: boolean control property values are also saved in the EXPCONFIG_FIELD_CTRLVVALUE field.

Parameters:

jsonID – ID of existing json
keyName – key name of setting
defaultValue – [optional, defaults to off] allows to query optional entries, if the value could not be found this is returned instead

Returns:

value of the EXPCONFIG_FIELD_CTRLVVALUE field of the control

static string CONF_FindControl(variable jsonID, string niceName)¶

Returns the path to the first control named nicename found in the json in all saved windows This might as well be a ControlArray.

Parameters:

jsonID – ID of existing json
niceName – nice name of control

Returns:

Path to control in json, empty string if not found

static string CONF_TraversalFinder(variable jsonID, string basePath, string niceName)¶

Returns the path to the first control named nicename found traversing the json starting at basePath This might as well be a ControlArray. This function runs recursively.

Parameters:

jsonID – ID of existing json
basePath – root of traversal start
niceName – nice name of control

Returns:

Path to control in json, empty string if not found

static wave CONF_GetWaveFromSavedControlArray(variable jsonID, string arrayName)¶

Retrieves a wave from a saved ControlArray It is REQUIRED that ALL ELEMENTS of the ControlArray are of NUMERIC type.

Parameters:

jsonID – ID of existing json
arrayName – name of ControlArray

Returns:

text wave with data from ControlArray

static string CONF_GetStringFromSavedControl(variable jsonID, string niceName)¶

Retrieves a string value from a saved control.

Parameters:

jsonID – ID of existing json
niceName – nice name of control

Returns:

value of the EXPCONFIG_FIELD_CTRLSVALUE field of the control

static variable CONF_GetVariableFromSavedControl(variable jsonID, string niceName)¶

Retrieves a variable value from a saved control.

Parameters:

jsonID – ID of existing json
niceName – nice name of control

Returns:

value of the EXPCONFIG_FIELD_CTRLVVALUE field of the control

static wave CONF_GetWindowNames(variable jsonID)¶

Returns a wave with all configuration sections ( aka control groups). This equals the top level keys without the EXPCONFIG_RESERVED_DATABLOCK key.

Parameters:: jsonID – [in] ID of existing json
Returns:: Text wave with all named configuration sections

static wave CONF_GetControlArrayList(string wName)¶

Returns a two column free wave with ControlArrayName and associated control list from a window.

Parameters:: wName – [in] Name of window
Returns:: Text wave with two columns and in each row ControlArray name (column ARRAYNAME) and control list (column CTRLNAMELIST)

static variable CONF_GatherControlsFromJSON(WaveText ctrlData, variable jsonID, string basePath)¶

Gathers recursively all control nice names and control paths from a configuration json by traversing all sub objects.

Parameters:

ctrlData – [in] ctrlData wave, 2d four column text wave as created in CONF_JSONToWindow(). This wave is updated by this function.
jsonID – [in] json object to traverse
basePath – [in] root path for traversal

string CONF_JSONToWindow(string wName, variable restoreMask, variable jsonID)¶

Restores GUI state of a window from a json The following userdata properties are considered: EXPCONFIG_UDATA_EXCLUDE_RESTORE, EXPCONFIG_UDATA_RESTORE_PRIORITY It is supported that the current main reference window in the GUI changes its name. It is not supported that a not yet restored subwindow of it changes its name.

Parameters:

wName – main reference window name in GUI
restoreMask – Bit mask which properties are restored from WindowControlSavingMask constants
jsonID – ID of existing json

Returns:

name of main window after restore

static variable CONF_RestoreNotebookWindow(string wName, string srcWin, variable jsonID)¶

Restores a notebook window content.

Parameters:

wName – Name of notebook window in Igor
srcWin – Name of window in JSON
jsonID – Id of JSON

static string CONF_FindWindow(string winHandle, string uKey = defaultValue)¶

Returns the window with the set window handle.

Parameters:

winHandle – window handle
uKey – [optional, default = EXPCONFIG_UDATA_WINHANDLE] userdata key that stores the handle value

Returns:

Window name of the window with the given handle; empty string if not found.

static variable CONF_RestoreControl(string wName, variable restoreMask, variable jsonID, string ctrlName, string jsonPath = defaultValue)¶

Restores properties of a control from a json The following control userdata properties are considered: EXPCONFIG_UDATA_EXCLUDE_RESTORE; EXPCONFIG_UDATA_BUTTONPRESS (for Buttons)

Parameters:

wName – Window name
restoreMask – Bit mask which properties are restored from WindowControlSavingMask constants
jsonID – ID of existing json
ctrlName – Control name
jsonPath – [optional, default = n/a] When given: the control is expected to be a named json object (with the control nice name) If not given: the jsons second level (assuming default format) is searched for the associated object. This is slower.

variable CONF_AllWindowsToJSON(string wName, variable saveMask, string excCtrlTypes = defaultValue)¶

Serializes all controls of a window and its subwindows into a json object.

File MIES_Configuration.ipf¶

Table of Contents

Previous topic

Next topic