Saving a State of HMI Applications

The function of saving HMI applications' state allows to save the configuration, which is currently chosen in respective application controls, and to bring it back at a later time. This means, it gives the possibility of bringing back chosen settings after closing and restarting the application, but also of storing many configuration sets and to quickly restore one of them, e.g. after changing the type of inspected object.

Values stored in respective controls that are related to the parameter being edited by given control, which may influence the application execution through the connections to the program, are all considered in the saved controls' configuration. It does not necessarily have to be the visual state of an application, such as control size on the application window. One configuration set can include all controls in the application, but also only a chosen part of the controls narrowed down to the interior of proper containers.

A single application configuration is saved to a single configuration file. In other words, one file always corresponds to one saved HMI state. The location for storing configuration files can be set individually for each application being created. The format of a saved configuration file is strictly related to the controls' arrangement in the HMI application. Configuration files are not interchangeable between different applications and significant changes in the application project (like deleting existing controls and, at the same time, adding new ones of the same type) may preclude from correct loading of already existing configuration files.

In order to use the function of saving HMI applications' state, you should add to your project one (or more) controls from the State Management category. The function's behavior is parametrized by properties of such controls and the process of saving and loading application state is controlled by them. In case a state of only some of the controls present in an application should be saved, they should be placed together inside a separate container (a control from the Containers category) together with the control, which controls saving a state, and properly adjust the Range property of this control. It is possible to create many groups of controls like this and nest many containers one inside of another.

Available controls for managing the function of saving HMI applications' states are described below:

StateControlBox control

This control is an integrated application state manager. It allows the end-user to fully control the list of saved configurations, including: creating new configurations with given names, saving changes in existing configurations, loading configurations chosen from the list and removing existing configurations. There is no limitation regarding the number of saved application states.

This control consists of the following elements (from left to right):

combo box with saved configurations,

button for loading the configuration chosen in the combo box,

button for saving current application state to the configuration chosen in the combo box,

button for saving current application state to a newly created configuration with given name,

button for removing the configuration selected in the combo box.

Each of configurations is saved as a separate file in the folder, which is associated with this control. The list of configurations visible in the control corresponds to the list of files in this folder. The location of such folder in a file system is defined by the BaseDirectory and BaseSubdirectory properties. The combo box with configurations is filled with names of all files with required extension, which are found in given folder (therefore, it is advised to use a separate folder for configurations, which does not contain any other elements). You should not link more than one StateControlBox control with the same folder in the same application because it may cause incorrect overwriting of configuration files, suggesting of loading configurations meant for other application parts and the fact, that controls will not be able to synchronize with the changes that they introduce.

This control has the following properties, which are essential in relation to saving an HMI state:

BaseDirectory - it defines the starting location of a base folder of configuration files in a local file system. It accepts one of the predefined values:

ProjectDir - the folder where the project of currently executed application (.avproj file) or the application executable file (.avexe) is saved. In order for the control to work properly with such setting, it is necessary to save a project (the control will not be able to work properly in an unsaved project in Adaptive Vision Studio).

MyDocuments - the system folder of user's documents (e.g.: C:\Users\John\Documents\).

UserLocalSettings - the system folder of local settings of currently logged user (e.g.: C:\Users\John\AppData\Local\)

None - no starting folder, the BaseSubdirectory property will be pointing the full, absolute path to the folder.

In order to put configuration files in one of system folders, you should always use predefined values mentioned above (instead of inputting a fixed absolute path) because on different operating systems these folders may have different locations.

BaseSubdirectory - it defines the path to a folder with configuration files. In case of entering a relative path (e.g.: MyDataFiles\MyConfigurationFiles) such location defines a subfolder in the starting folder chosen by BaseDirectory property. In case of entering an absolute path (e.g.: D:\MyConfigurationFile\MyAppConfiguration or \\MyServer\\MyShare\MyConfigurations) such value defines a full absolute folder path.

CreateSubdirectory - setting it to True will cause folder defined by the BaseSubdirectory property to be fully created (when it does not exist yet) before saving a new configuration to it. In case of setting it to False (a default value), an attempt to save a configuration will fail when such folder does not exist yet.

ControlRange - it defines which of the controls present in an HMI application take part in saving and restoring their configurations. It accepts the following values:

Global - all controls in an entire HMI application save and load their state as part of an action of such controller,

InContainer - only those controls in an HMI application which are located in the same container as a state controller control take part in saving and loading their states (e.g. only controls which are located in the same GroupBox control as the StateControlBox control will save their states).

AutoLoad - when set to True, it causes chosen configuration to be automatically loaded to an HMI application after switching position on the list of saved configurations. In case of setting it to False (a default value), such configuration will be loaded only after clicking the "Load Configuration" button.

PromptBeforeSave - when set to True, it causes displaying an additional message asking for action confirmation (in order to prevent from overwriting the currently chosen file accidentally) after pressing the "Save Configuration" button. When set to False (a default value), the configuration currently chosen on the list will be overwritten immediately after pressing the "Save Configuration" button. This property does not influence the behavior of the "Save Configuration As..." button.

Additional properties of the StateControlBox control:

ButtonsSize - it allows to change the sizes of the control buttons located on the right side of the combo box. It accepts one of the following values: Small (a default value), Medium, Large.

StateControlButton control

This control resembles in appearance an ordinary button (ImpulseButton control) and provides the same properties defining its appearance. On the contrary to the ImpulseButton control, the reaction for clicking this control is performing one of the chosen actions of saving or loading application state.

On the design level this control becomes associated with one specific configuration file located in a constant path (described by the BaseDirectory and FilePath properties). It performs one of the saving or loading operations of application states on such file. On the contrary to the StateControlBox control, it does not provide an end-user with full control over the configuration list and allows to build an individual, non-standard user interface for controlling of application state saving.

This control has the following properties, crucial from the point of view of saving an HMI state:

BaseDirectory - it defines the starting location of the path to a configuration file, just like the BaseDirectory property of the StateControlBox control.

FilePath - it defines the path to a configuration file. It can point to a location which is relative to that one set by BaseDirectory, or to a full absolute path just like the BaseSubdirectory property of the StateControlBox control. The file name should be entered without extension (it will be added by the control automatically).

CreateSubdirectory - setting it to True will cause the folder, which should contain the file described by the FilePath property, to be fully created (when it does not exist yet) before saving a new configuration to it. In case of setting it to False (a default value), an attempt to save a configuration will fail when such folder does not exist yet.

ButtonMode - it defines the action, which the button should perform after clicking it. It can accept one of the following values:

Save - the current HMI application state is to be saved to the associated file.

Load - an HMI application configuration is to be loaded from the associated file.

ControlRange - it defines which of the controls present in an HMI application take part in saving and loading their configurations, just like the ControlRange property in the StateControlBox control.

StateAutoLoader control

This control can be used to automatically load chosen HMI configuration on application start or to automatically save current HMI state to a configuration file on application close. StateAutoLoader should be placed inside a container control which defines its range. This control is visible only in the design mode, it becomes invisible during runtime.

StateAutoLoader enables to create an non volatile HMI thanks to automatic loading and saving of a configuration file. Basically, it is recommended to use this control to automatically load HMI configuration on start and the StateControlButton control to manually save current HMI configuration to a file.

This control has the following properties, crucial from the point of view of saving and loading an HMI state (most of the properties are the same as those in the StateControlBox control):

AutoLoadOnOpen - when set to True, it causes that the configuration from the file defined in the FilePath property will be loaded on application start.

AutoSaveOnClose - when set to True, it causes that the current state of HMI will be saved to the configuration file defined in the FilePath property on application close. Please note that a configuration will not be saved if the application is closed in an unexpected way (e.g. on a power loss).

BaseDirectory - it defines the starting location of the path to a configuration file, just like the BaseDirectory property of the StateControlBox control.

FilePath - it defines the path to a configuration file. It can point to a location which is relative to that one set by BaseDirectory, or to a full absolute path just like the BaseSubdirectory property of the StateControlBox control. The file name should be entered without extension (it will be added by the control automatically). If no file is found in the given location and AutoLoadOnOpen is set to True, the loading on application start will be ignored and controls state will remain unaffected.

CreateSubdirectory - setting it to True will cause that the folder which should contain the file described by the FilePath property will be fully created (when it does not exist yet) before saving a new configuration to it. In case of setting it to False (a default value), an attempt to save a configuration will fail when such folder does not exist.

ControlRange - it defines which of the controls present in an HMI application take part in saving and loading their configurations, just like the ControlRange property in the StateControlBox control.