This module, although being used for the Registration system for plug-ins can be used for other purposes too.
Credits and thanks for help with this module: I have to give credit and thanks to Jeff McClintock of SynthEdit for pointing me in the right direction with using this module, as I was making a rookie error connecting it up!
Also many thanks to Sylvain Cottarel for providing the precise rules governing the checking and updating of the preferences.xml file.
How the User Setting – Text module works.
This is what the SE help file has to say:
“Stores any setting common to all instances of your plug in. For example if you want your samples always loaded from a user-specified folder.”
The module takes your settings, and creates an XML file, this file is then saved in a folder where no user permissions are needed by SE. The name entered into the product plug in the properties panel will give the XML file it’s filename.
Note: Once you have decided on the name for the settings, don’t change it, if you give the Product plug a new name it will create another XML file and folder. For this reason the left hand side plugs cannot be updated with a string from another module. These values must be set manually in the properties panel when programming.
Multiple modules.
You can use multiple User Setting – Text modules and they will append a single xml file. This allows you to save product activation information and any other user settings that need be retained across plug in session regardless of any other parameters set by assignned presets.
Product.
“Product” should be fed with the name of your VST and this is the name of the xml file that this module will create and use to store your path (and other useful info if needed). Jeff has chosen a safe location where permission to save is never requested by Windows.
You can use more of these User Settings – Text to store a wide variety of useful settings.
Important Note: The product pin must be set with exactly the same name as the plug-in name or it won’t recall settings made to the xml properly for that plug in.
Key.
If we are using more than one module to store preferences fo a number of parameters, e.g. to save colours etc so the user can “skin” the plug-in with their own panel colour, text colour, and other settings then each User Settings-Text module preference type needs to have it’s own module, each with a unique “Key” text string to separate the parameters in the XML file.
About the XML File and it’s location.
You’ll find the xml file(s) created in : C:\Users\”USERNAME”\App Data\Local\”your vst name”\Preferences.xml.
The file is re-created if it has been removed, or is not found.
1) On opening the vst, any User setting – text module looks in the app data folder if it can find a folder which has a name equal to its Product pin input (The name of the VST).
2) If the module finds this folder, it checks the folder to see if it contains a Preferences.xml file.
3) If a Preferences.xml is located, the Module reads the file if a key is present corresponding to its Key pin input.
4) If the key contents are identical, the value of the key is sent to the Value output pins (GUI and DSP)
5) If the key is not present, the module writes the value present in its Value Gui plug in the xml file, or, if there is on key present, the module writes values of its Default value plug.
6) If the module doesn’t find the Preferences.xml file in the folder or simply doesn’t find the folder, the module creates a new folder with a name corresponding to its Product plug value, then creates the Preferences.xml file inside and then writes the key value following the previous rules into the xml file.
Important note: Just to make things 100% clear the module does not know the location of the VST it is in, just where to find the relevant preferences file. This will always be correct as the module always has the full path to find the file wherever the VST is located.
Example “Skin” Setup.
The setup below allows the user to select the background colour (Rectangle) The Text colour, the Border (DAM Rectangle) colours, and the colour of the Vector Knob’s cap.
The User Settings module properties are set as follows:
1) Product = Skins Test 1 Key = Background
2) Product = Skins Test 1 Key = Text
3) Product = Skins Test 1 Key = Knob Cap .
I used the name Skins Test 1 in my example Product value. This will generate the following XML File named Preferences.xml in the folder Skins Test 1
So it would be in this location: : C:\Users\"USERNAME"\AppData\Local\Skins Test 1\Preferences.xml.<?xml version="1.0" encoding="UTF-8"?>
<Preferences>
<My_Setting_Name>0</My_Setting_Name>
<Background>4</Background>
<Text>0</Text
<Knob_Cap>2</Knob_Cap>
</Preferences>
The number listed between each of the Key names being the integer of the selected option.
Creating your Settings:
The List Entry 4 module is used to store the names of the options.
So for a list of colour options you could have set the Item List as;
Light Grey, Medium Grey, Dark Grey, Red, Green, Blue
In the List To Text module you would set the Item List pug with the matching Hex ARGB values;FFAAAAAA, FF777777, FF444444, FFFF00000, FF00FF00, FF0000FF
Note: The sequence of colour names and ARGB values must match if you don’t want to confuse your users.
Note: There are some modules that may require a hash (#) symbol prefix on the ARGB code.
Note: Don’t forget to use commas to separate the values. The last entry needs no comma or any other symbol after it.
Storing Float values.
You could also use a Text to Float converter to control settings that need a Float value, e.g. If you were using a DAM Text Enter module which has the Font Size you could store a list of font sizes such as 12, 14, 16, 18 in both the List Entry and List to Text Modules. All you need do is connect the Item Text output plug of the List to Text module to the appropriate Float plug using a (GUI obviously) Text to Float converter. Just be careful of the Float values, some such as the Font size on the DAM Text Enter module will use the same values as the font size. Others may use a value between 0 and 1. Using decimals such as 0.4 is no problem, the modules will handle these values correctly.
Note: Both the List Entry 4 and List to Text modules have the same Item List values in this scenario; 12, 14, 16, 18
